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

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.

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

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 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:

response.raw.body

<?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.

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

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
• Shaun Robinson

License

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