SOAP Commerce API with Web Services 2.0
This topic discusses Web Services 2.0. For information on Web Services 1.0, see
Web Services 1.0.
Overview
The Commerce APIs provide functionality that is available through the regular bulk upload of the Asset Manager or the Real Time API provided through middleware. In addition, they provide the ability to create a new transaction (both with and without line items).
You can generate a skeleton input for each in the Commerce WSDL, which contains the following operations:
- createTransaction
- addToTransaction
- removeFromTransaction
- updateTransaction
- getTransaction
- exportFileAttachments
- importFileAttachments
For each operation, the following fields are always required in the header:
-
UsernameToken
- category: Security
- schemaLocation
Commerce SOAP API Details
For all SOAP APIs, the Failure Response Variables are exceptionCode and exceptionMessage.
Items in bold are the tags that are returned.
| createTransaction |
Supports the create of a commerce transaction without line items, as well as transactions with non-configurable line items from a specified process. For all transactions that need to be created with configurable line items, the Configuration SOAP API will have to be invoked. This will return the Transaction ID. |
- category
- schemaLocation
- process_var_name
- var_name
- attribute
|
- status
- transactionID
- transaction
|
| addToTransaction |
Adds new items to an existing transaction. It performs the Add from Catalog action.
The request message specifies the following parameters:
- process
- document
- action on the document
- items to be added to the transaction
|
- transactionID
- category
- schemaLocation
- process_var_name
- var_name
- attribute
- document_number
- document_var_name
To add a part:
All input variables above, plus
- part
- quantity
- price_book_var_name
|
- status
- transactionID
- transaction
|
| removeFromTransaction |
Removes an item from an existing transaction. It performs the Remove Line Items action. The input parameters include the document ID, document number, process name, and document name. They are wrapped in a specific structure, described below. |
- transaction ID
- category
- schemaLocation
- process_var_name
- document_number
- document_var_name
|
|
| updateTransaction |
Updates an existing transaction. It performs all Modify actions, as well as the Auto-fill action. It does not support the Create Document action. |
- transactionID
- category
- schemaLocation
- id
- process_var_name
|
|
| getTransaction |
Returns the transaction based on the Transaction ID, which is provided as input parameter. The API returns the complete transaction XML. The API returns the transaction XML. Note it does not return RTE or HTML attributes, which can be obtained with REST APIs.
|
- transactionID
- category
- schemaLocation
- id
- var_name
- attribute
|
|
| exportFileAttachment |
Export a file attachment using one of two methods to stream the data via SOAP:
- inline base64 content in a SOAP message
- binary stream with MIME containers via MTOM transmission.
These methods provide read/write of multiple attributes at once per transaction. This API can only be used by FullAccess users with Permission to Modify Users. There are two modes available for use:
- Content: Retrieves the content of the attached field(s).
- Metadata: Retrieves the file information or metadata for the references fields.
|
- category
- schemaLocation
- mode
- document_number
- variable_name
- process_var_name
- id
|
|
| importFileAttachment |
Import a file attachment using one of two methods to stream the data via SOAP:
- inline base64 content in a SOAP message
- binary stream with MIME containers via MTOM transmission.
These methods provide read/write of multiple attributes at once per transaction. This API can only be used by FullAccess users with Permission to Modify Users. There are two modes available for use:
-
Update: Attaches a files, or a set of files, to the transaction.
- Delete: Removes a file from the file attachment attribute.
|
- category
- schemaLocation
- mode
- document_number
- variable_name
- filename
- process_var_name
- id
|
|
Returning Specific Attributes in Commerce APIs
Return specific attributes from a web service request with the <bm:return_specific_attributes /> tag.
For example, you can pull in four main-document attributes and two sub-document attributes. In return, you get a shortened version of the transaction XML, displaying only those attributes.
The following APIs can return specific attributes:
- addToTransaction
- createTransaction
- getTransaction
Administration
- Click Admin to go to the Admin Home Page.
-
Click Web Services in the Integration Platform section.
The Web Services Test page opens.
- Confirm that the Web Service Version is 2.0.
- Click the Commerce tab.
- Select an API from the drop-down.
- Choose a Commerce Process from the Process Name: drop-down.
-
Click Generate Input to retrieve the skeleton.
For more information on the body of the Commerce Web Service, and for code examples, see SOAP Commerce API with Web Services 1.0. With the exception of the header, the Web Services 1.0 code examples are valid in Web Services 2.0.
Header Information for Web Services 2.0
For each API, the body of the SOAP XML is the same as it was for Web Services 1.0. This is the information contained between the <soapenv:Body> and </soapenv:Body> tags.
The header, contained between the <soapenv:Header> and </soapenv:Header> header, has changed with Web Services 2.0.
| No change |
<soapenv:Header> |
<soapenv:Header> |
| New tags |
|
<wsse:Security xmlns:wsse= "http://docs.oasis-open.org/wss/2004/
01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
|
| New user information replaces sessionId |
<bm:userInfo . . . >
<bm:sessionId>
. . . . .
</bm:sessionId>
</bm:userInfo>
|
<wsse:UsernameToken wsu:Id="UsernameToken-2">
<wsse:Username/><wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"/>
</wsse:UsernameToken>
|
| This is now in the URL, with the unique end point specified. |
<bm:category
xmlns:bm="urn:soap.bigmachines.com">
Commerce
</bm:category> |
Now reflected in the SOAP Server URL field. |
| No longer needed |
<bm:xsdInfo
. . . . .
</bm:xsdInfo>
|
|
| Ending the new authentication |
|
</wsse:Security>
|
| No change |
</soapenv:Header> |
</soapenv:Header> |
Notes
Oracle CPQ 20B implements XML Translation Line Limits to prevent performance issues that could occur when generating XML for quotes with an extremely large number of transaction lines.Since SOAP APIs do not support pagination, the SOAP response does not indicate that there are additional rows. This limit impacts the following APIs:
- getTransaction
- createTransaction
- addToTransaction
- getTransaction
- removeFromTransaction
- updateTransaction
Related Topics
See Also
