[![Circle CI](https://circleci.com/gh/contactually/zuora-ruby.svg?style=shield&circle-token=808be5d625e91e331bedb37a2fe94412bb3bc15e)](https://circleci.com/gh/contactually/zuora-ruby)
[![Code Climate](https://codeclimate.com/repos/569444dfa3d810003a00313f/badges/416bae00acf65d690efe/gpa.svg)](https://codeclimate.com/repos/569444dfa3d810003a00313f/feed)
[![Test Coverage](https://codeclimate.com/repos/569444dfa3d810003a00313f/badges/416bae00acf65d690efe/coverage.svg)](https://codeclimate.com/repos/569444dfa3d810003a00313f/coverage)

# Zuora SOAP API Client

## Features
* HTTP client to Zuora SOAP API
* Authentication and session storage
* SOAP XML request constructors from Ruby data
* Support for custom Zuora fields
* Light validation of SOAP call parameters
* Light wrapper over response, providing a Ruby object interface over Zuora's returned XML response 

## Usage


### Client

Create a client
```ruby
client = Zuora::Client.new(<username>, <password>) 
```

Execute a SOAP request. All Zuora calls are supported: `.create()`, `.update()`, `.amend()`, `.generate()`, `.delete()`, `subscribe()`.

### Quick Reference
See examples below and integration specs for full interfaces. 
```ruby
client.call! :query, "SELECT Id FROM Account"
client.call! :create, type: :Account, objects: [{}, {}]
client.call! :update, type: :Invoice, objects: [{ id: '123' }, { id: '123' }]
client.call! :delete, ids: ['123', '456']
client.call! :amend, amendments: {}, amend_options: {}, :preview_options: {}
client.call! :subscribe, 
  account: {}
  payment_method: {}
  bill_to_contact: {}
  sold_to_contact: {}
  subscribe_options: {}
  subscription: {}
  rate_plan: {}
```

#### Create Example

 ```ruby
response = client.call! :create,
  type: :BillRun,
  objects: [{ 
    invoice_date: '2016-03-01',
    target_date: '2016-03-01'
  }]
```
This would generate SOAP XML, make, and return an authenticated SOAP request.
```xml
    <?xml version="1.0"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.zuora.com/" xmlns:obj="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <soapenv:Header>
        <api:SessionHeader>
          <api:session><!-- SESSION TOKEN HERE --></api:session>
        </api:SessionHeader>
      </soapenv:Header>
      <soapenv:Body>
        <api:create>
          <api:zObjects xsi:type="obj:BillRun">
            <obj:InvoiceDate>2016-03-01</obj:InvoiceDate>
            <obj:TargetDate>2016-03-01</obj:TargetDate>
          </api:zObjects>
        </api:create>
      </soapenv:Body>
    </soapenv:Envelope>
```

A response object is returned. You can access the raw response:
```ruby
response.raw.body
```
```xml
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <api:createResponse xmlns:api="http://api.zuora.com/">
      <api:result>
        <api:Id>2c92c0f9526913e301526a7863df4647</api:Id>
        <api:Success>true</api:Success>
      </api:result>
    </api:createResponse>
  </soapenv:Body>
</soapenv:Envelope>
```

The `.to_h` method provides an interface that can be navigated as a hash or object.

```ruby
response.to_h.envelope.body.create_response.result 
=> { id: '2c92c0f9526913e301526a7863df4647', success: true }
```

#### .subscribe() example
Subscribe is a very large call that involves a lot of data. See the integration spec `spec/zuora/integration/subscription_spec.rb` for full example

 ```ruby
response = client.call! :subscribe, 
  account: {...},
  payment_method: {...},
  bill_to_contact: {...},
  sold_to_contact: {...},
  subscription: {...},
  rate_plan: {...}

```

# Changelog
* **[0.1.0 - 2016-01-12]** Initial release 
* **[0.2.0] - 2016-01-14]** Models
     - Refactored client to clarify logic 
     - Replaces `ActiveRecord::Model` and `::Validations` with a base module that provides powerful and extensible facilities for modeling remote resources in Ruby. 
       * required attributes, coercions, validations, type checking
       * dirty attribute tracking
       * extensible predicate library
     - Implements fine-grained validations per Zuora spec
     - Removes invalid model state paradigm used via `ActiveModel` in version 0.1.0.
     -  A model now performs its validations on `.new`, and will raise a detailed exception on mistyped, invalid or uncoercable data.
     - Adds VCR for mocking out HTTP requests
     - Adds integration specs for `Subscribe` `create!` and `update!` and `Account` `create!` and `update!`

* **[0.3.0 2016-1-28]** Focus on SOAP API, simpify client library feature set
    - Redesign API, eliminate previous Model constructs
    - Implement SOAP API Client, as it provides fuller functionality than REST 
    - Focus on constructing + composing hash-like Ruby objects into XML SOAP requests 
    - Add support for custom fields
    - Remove object-level validations; relies on Zuora's own error responses. Light validations on call constructors.
    - Provide object/hash lookup capabilities on Zuora Responses
    - See integration specs for full interface
    
# Commit rights
Anyone who has a patch accepted may request commit rights. Please do so inside the pull request post-merge.

# Contributors
* [John Gerhardt](https://github.com/jwg2s)
* [Shaun Robinson](https://github.com/env)

# License
MIT License. Copyright 2016 Contactually, Inc. http://contactually.com