9. Callout Notifications, API Requests &
Responses
page
09
External
System
Callout Notification
(1) Event in Zuora
Triggers a Callout
Notification
(2) Receives
Notification
HTTP status code 200
(4) Depending on the Callout Data
Send API Request: query for
additional data
(5) Query is processed:
Sends API Response
API Request
API Response
(3) Parses the Notification Data
10. The Zuora Landscape with APIs
page
010
Pay-wall
(provisioning)
Marketing
System
Financial
System
Data
Warehouse
Web PortalCRM
SOAP
REST Actions
REST Functional
REST Actions
REST Functional
ExportsAQuA
Callouts Callouts
24. API Users
page
024
• Users are created from within the Zuora UI
• Users are granted: “UI Access” and/or “API Write Access”
•
• An API User has UI Access turned off
• Create an API User Role, set as a “Platform” Role in Zuora
• NOTE: If an API User account logs into the Zuora UI,
• That login is subject to forced password expirations
• This could result in API authentication failures
30. Zuora API Types & Categories
page
030
• Callout Notifications
• Describe API
• SOAP & REST Actions
• Non-CRUD (Functional) REST APIs
• AQuA
• Reporting
31. Callout Notifications
page
031
• Data is in JSON or XML format
• Authentication: None, Basic, Digest & NTLM
• 25 Second Timeout
• 10 seconds to establish a socket connection
• 15 seconds for data transfer
• NOTE: Timeout Limit cannot be changed
• Retry Limits
• Maximum of 5 delivery retries
• Maximum Number of minutes between callout attempts is 1440 (24 hours)
• Functional API to retrieve Callout Histories
33. Callout Notification - Example using
Hookbin.com
page
033
• Create a Hookbin Endpoint
• Enable the Callout Notification to point to the Hookbin Endpoint
• Create a New Subscription Event in Zuora
• View the Callout data in Hookbin
35. Zuora API Types & Categories
page
035
• Callout Notifications
• Describe API
• SOAP & REST Actions
• Non-CRUD (Functional) REST APIs
• AQuA
• Reporting
36. Describe API
page
036
• Lists Fields within Zuora Objects
• Shows Related Objects for Data Sources
• Versioned with WSDL numbers for compatibility
• https://apisandbox.zuora.com/apps/api/describe/Account
• https://apisandbox.zuora.com/apps/api/84/describe/Account
• GET calls return XML data by default
• HTML data can be returned with “format=html” query string
• https://apisandbox.zuora.com/apps/api/describe/Account?format=html
37. Describe API
page
037
• Lists Fields within Zuora Objects
• Shows Data Source Related Objects
• Versioned with WSDL numbers for compatibility
• GET calls return only XML and HTML data
38. Zuora API Types & Categories
page
038
• Callout Notifications
• Describe API
• SOAP & REST Actions
• Non-CRUD (Functional) REST APIs
• AQuA
• Reporting
39. SOAP and REST Actions
page
039
• SOAP & XML are the Past, REST & JSON are the Future
• SOAP APIs are no longer under active development
• There are no current deprecation plans, but all new features will be via REST
• Mostly for CRUD (Create, Read, Update, Delete) Operations
• Allows for changes of up to 50 objects at a time
• Non-CRUD calls include:
• BillingPreview (Generate preview of future invoice items)
• Execute (Split an invoice into multiple invoices)
• Generate (Generate Invoice on-demand)
• Amend
• Subscribe
42. DataSource Exports and AQuA - Similarities
page
042
• Asynchronous Data Source Queries
• Submit Query, Wait for Notification or poll job_ID status
• Download file upon completion
• Both work with the pre-joined DataSources
• Allow for data to be encrypted
• Allow for data to be compressed
• Event Callout Notifications upon completion
43. DataSource Exports and AQuA - Differences
page
043
Exports
• Allows for output in CSV and Excel Format
AQuA – Aggregate Query API
• Allows for output only in CSV Format
• Using Stateful queries allow for:
• Only get data that was updated since the last query.
• Export Deleted Objects since the last query
• AQuA results older than 72 hours are purged automatically
• Allows for data to be encrypted
• Event Callout Notification Upon Completion
44. Reports API
page
044
• Get Last Completed Report Run
• Get Report Data
• Export Report Run
• Run a Report
• Cancel a Report Run
• Search by Report Name
• Get Reports by Label
• Get Report Details
• Get Report by ID
• Get Report Details by Label
• Copy a Report and Assign Labels
• Get Report Labels for ReportID
• Create a Report and Assign
Labels
• Delete a Report
• Label or Unlabel a Report
• Save a Report
• Get Tenant Settings
• Update Tenant Settings
45. API Endpoints
page
045
Type Base / AQuA Rest Reporting
Sandbox https://apisandbox.zuora.com https://rest.apisandbox.zuora.com https://zconnectsandbox.zuora.com
Performance https://pt1.zuora.com https://rest.pt1.zuora.com https://zconnectpt1.zuora.com
Services* https://servicesXXX.zuora.com https://servicesXXX.zuora.com/app/ N/A**
Production https://www.zuora.com https://rest.zuora.com https://zconnect.zuora.com
*At this time, Only Legacy RESTworks in the services environment. (No REST Actions)
**ZConnect (Reports API) does not yet work in services environments
47. API Best Practices
page
047
• Keep a log of API Requests & Responses with their
timestamps.
• Review the Callout Notification log for errors
• Create separate API Users for each integrated system
• Every Month Check the Zuora Release Notes for changes &
enhancements to APIs
• Perform Negative testing to validate Error Handling
49. Definitions
page
049
API - Application Programming Interface - Set of clearly defined methods of
communication between various software components. A Zuora Function
Notification Callout - Event-based XML calls that Zuora makes to other systems
Zuora SOAP API - Simple Object Access Protocol - XML-message based
protocol used for implementing web services
Zuora WSDL - Zuora Web Services Definition Language - Contains definitions of
the Zuora SOAP API along with custom field definitions.
Zuora REST API - Representational State Transfer / RESTful Web services