B2B REST APIs available in Sterling B2B Integrator

Each REST resource contains information such as URIs, descriptions, and sample input and output data.

The B2B REST API documentation contains a list of resources that are provided by the B2B REST APIs. You must have a valid license for Sterling B2B Integrator to access the B2B REST APIs.

Important:
Set the following headers before executing any API:
  • Authorization - Type of authorization. Only basic authorization is supported.
  • Content-type - Type of the content. Example: Application/JSON, Application/XML.
  • Accept - Type of request accepted. Example: Application/JSON, Application/XML.
Note:
  • Sorting of the API results depends on the MSSQL database settings, whether it is configured as case sensitive or case insensitive.
  • Some of the APIs do not function as expected and exceptions are seen in the log files. These APIs have a dependency on the property security.passphrase.

    Error Stacktrace: java.security.UnrecoverableKeyException:The private key cannot be retrieved. The system passphrase is incorrect.

    Workaround: Add security.passphrase=password in the customer_overrides.properties file and restart Sterling B2B Integrator.
  • Each API can support different parameter formats for their respective calls. As an example, some APIs support XML, others support JSON, while some support both.
The following table lists the B2B REST APIs, with a brief description (in the order they appear in the Web Service Browser: API Reference):
B2B REST API Description
CodeList Services Services to create, read, update, and delete Trading Partner code lists stored in the Sterling B2B Integrator database.
CodeListCode Services Services to create, read, update, and delete the codes in the code list.
Community Services Services to create, read, update, and delete Communities in Sterling File Gateway.
Community services support custom protocols in addition to the ones preconfigured in Sterling File Gateway.
Note: Ensure that the custom protocol names you specify are valid and are available in your AFTExtension xml file.
Custom Protocol Services Service to read custom protocols available in the system.
CustomJar Services Services to create, read, update, and delete third party JAR files that can be deployed in a Sterling B2B Integrator environment. Third party jars can be uploaded and deployed on specific nodes using the APIs.
Note:
  • While uploading third-party JAR files to all nodes using this REST API, the Node List must be given as ALL in capital letters.
  • In the File Contents field, you must enter the base 64 encoded text of the file that needs to be used.
CustomService Services Services to create, read, update, and delete custom services that can be deployed in a Sterling B2B Integrator environment.
Note:
  • While uploading custom services to all nodes using this REST API, the Node List must be given as ALL in capital letters.
  • In the File Contents field, you must enter the base 64 encoded text of the file that needs to be used.
Document Services Services to create, read, update, and delete documents in Sterling B2B Integrator that contain payloads of messages. In addition to the create, read, update, and delete services, action is provided to append more data to the body of an existing document and to export data from a document into the storage subsystem.
Note: With the JVM heap size in the Liberty API server configured to 4 GB, the maximum size of the file you can download using the Get Payload API is 750 MB.
Note: If you are using Microsoft SQL server database with Sterling B2B Integrator, the document ID that is returned by the Document Services API is HTTP URL encoded and the colon (:) character in document ID is replaced with “%3A”.
File Gateway Arrived File Services Services to read and replay the files that arrive into Sterling File Gateway. Using the ReadFGArrivedFile API, you can also search the FG arrived files based on document IDs.
File Gateway Route Services Service to read the Sterling File Gateway Route details.
Mailbox Services Services to create, read, update, and delete Mailboxes in Sterling B2B Integrator. Shared and linked mailboxes are supported if the functionality is enabled in Sterling B2B Integrator.

Create Mailbox service also supports specifying users and groups that have permissions on the mailbox.
Mailbox Content Services Services to read the contents of mailboxes.
Mailbox Message Services Services to create, read, update, and delete messages in a mailbox. Along with the create, read, update, and delete services, a service is provided to create multiple messages in a mailbox upon receiving a request with the Content-Type header set to "multipart/form-data." Additionally, actions are provided to:
  • Extract a message from a mailbox. After the extraction is complete, the extraction count is decremented by one if the message is configured to limit extract by number of times.
  • Move a Message from one mailbox to another.
Message Batch Services Services to read the details of the messages of a specific Mailbox in a batch and to perform batch upload of messages to a Mailbox.
Partner Group Services Services to create, read, update, and delete partner groups.
PropertyFile Services Services to create, read, update, and delete custom property files.
PropertyNodeValue Services Services to create, read, update, and delete custom property values for specific Sterling B2B Integrator nodes.
Routing Rule Services Services to create, read, update, and delete routing rules in Sterling B2B Integrator. In addition to the create, read, update, and delete services, an action is provided to manually evaluate a Routing Rule.
Service Instance Services Services to create, read, update, and delete service instances. You can create instances of the following Adapters and its related services using the create service instance API:
  • File System Adapter
  • FTP Server Adapter
  • FTP Client Adapter
  • HTTP Server Adapter
  • SFTP Client Adapter
  • SFTP Server Adapter
  • Sterling Connect:Direct Server Adapter
  • Command Line Adapter 2

The READ call for the Service Instance API returns the status of the adapter instance in binary. The READ call returns 0 if the Advanced status of the adapter instance is Start Failed, Stopped, or Disabled and returns 1 if the status is Active.

Note:
  • When the DeleteServiceInstance API is used with a service name, all services matching the service name in the system are deleted, thereby making it a bulk operation. So, while using the DeleteServiceInstance API with service name, you must add _bulk=true to the end of the URL For example,
    <Host_Name>:<port>/B2BAPIs/svc/serviceinstances/
?serviceName=<service_name>&_bulk=true
  • When using the CreateServiceInstance API, if under Request & Response you select application/xml for Accept and Content-Type, the XML object data that you pass for instParms must not contain any newline characters or carriage returns and special characters that are not part of the XML character set.
Trading Partner Services Trading Partner services support creating partner mailboxes and related objects in the Global Mailbox realm.
Trading Partner services support:
  • Custom protocols for listening consumers in addition to the ones preconfigured in Sterling File Gateway.
    Note: The ExtensionKey and ExtensionValue parameters of the customProtocolExtensions attribute corresponds to the custom protocol you select. Ensure that you pick up the right values for these parameters from your AFTExtension xml file. These values are not validated during the API calls.
  • Custom protocols for listening producers in addition to the ones preconfigured in Sterling File Gateway. For a FileGatewayListeningProducer BP that performs the polling and unlock operations, the following parameters must be set: CustomProtocol and protocolType.
    Note: Trading Partner B2B REST API does not support the export and import of listening producers that use custom protocol.
  • Custom protocols for update Trading Partner APIs.
    Note: The custom protocol names are not displayed on READ, UPDATE, and DELETE Trading Partner API calls, only the custom extension values are displayed. Hence, it is important that the custom protocol names that you provide are valid. Specify the correct customProtocolExtensions attribute and the corresponding custom protocol name. In case of any mismatch between the customProtocolExtensions attribute and the custom protocol name, the modified protocol name will not be updated.
    Note: If the tradingPartner.defaultReadFullDetail property in the /<install_dir>/properties/b2biAPIs.properties file is set to false, the UPDATE Trading Partner API retrieves only the community and partner name attributes. In such cases, you must first run the READ Trading Partner API to retrieve all the details of the business partner and then run the UPDATE Trading Partner API to update the trading partner details.
User Account Services Services to create, read, update, and delete Sterling B2B Integrator user accounts.
Note: When the userAccount.defaultReadFullDetail property in the /<install_dir>/properties/b2biAPIs.properties file is set to false:
  • The READ UserAccount API does not retrieve the groups, permissions, and authorizedUserKeys attribute values in the JSON response.
  • The UPDATE UserAccount API does not retrieve all the details of the user account. In such cases, you must first run the READ API for the specific user account to retrieve all the details and then run the UPDATE UserAccount API to update the user account details.
UserExit Services Services to create, read, update, and delete jar files for User Exit. User Exit jar files can be uploaded and deployed on specific nodes using the APIs.
Note: While uploading user exit jar files to all nodes using this REST API, the Node List must be given as ALL in capital letters.
Virtual Root Services Services to create, read, and delete virtual root mailboxes. The virtual root is the first level of the directory path for a user when they are navigating the mailbox navigation pane.
Workflow Services

Services to create, read, update, and delete business processes and actions to change the default version of the workflow and enable or disable the workflow.

Note: Keep the following points in mind when working with the Workflow API:
  • Workflow API does not support changing the default version of a BP.
  • Workflow API UI always loads only the default version of the BP.
  • Any changes that are made to the default version of the BP by using the Sterling B2B Integrator UI is not synced with the workflow API.
  • The WF None option available in the Workflow API indicates the Zero option Persistence Level.
Workflow Monitor Services Services to read, restart, and terminate workflow monitors.
Note: Keep the following points in mind when working with the Workflow Monitor API:
  • The RestartWorkFlowMonitor service returns the URL of the newly-created workflow monitor with an HTTP status of 201 (CREATED) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. You can retrieve the workflow ID of the newly-created workflow by parsing the response URL with the JSON object workFlowId. For example, <Host_Name>:<port>/B2BAPIs/svc/workflowmonitors/?_range=0-999&workFlowId=265933&fieldList=Full
  • By default, the ReadWorkFlowMonitor service lists the workflows in the ascending order. To view the latest records at the top of the list, you must specifically provide the sort option as sort=-<column Name> during the API call. For example, <Host_Name>:<port>/B2BAPIs/svc/workflowmonitors/?_range=0-999&_sort=-endTime&workFlowId=&fieldList=Full