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:
You must 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
Approval Activity Services
Provides the following services:
  • Read Pending Approvals and Pending Approval details from Sterling B2B Integrator.
  • Update Pending Approval requests with appropriate comments.

These APIs are developed using the SpringBoot framework and are available on Swagger docs.

Default URL - http://<Install_Host>:<Liberty_port>/swiftapis/swagger-ui.html​.

Get APIs:

  • getRequests
    Query Parameters:
    • provide Pagination.
    • ownedBy as a query parameter. Allowed values(self/others) only.
    • status as query parameter. Allowed values(pending/rejected) only.
  • getRequestDetails

    Request Parameter:

    referenceId

Put APIs:

updateRequest
Request Parameters:
  • referenceId
  • action. Allowed values(Approve/Reject).
  • comment.
AS2 Organization Services Services to create, read, update, and delete the AS2 organization profiles.

The ReadIdentity Services API is used to retrieve the existing identity names, which is required while creating (POST) AS2Organization profiles.
AS2 TradingPartner Services Services to create, read, update, and delete the AS2 Trading Partner profiles.

The ReadIdentity Services API is used to retrieve the existing identity names, which is required while creating (POST) AS2TradingPartner profiles.

The ReadHTTPClientAdapter Services API is used to retrieve the HTTPClientAdapter value, which is required for creating (POST) and updating(PUT) AS2TradingPartner profiles.

Note:
  • If you update the TradingPartner delivery mode attribute from Synchronous to ASynchronous(HTTP/HTTPS/SMTP) or vice-versa using Update AS2TradingPartner Service, then you must also invoke the Update AS2TradingRelationship API. This step is required to update the BP process name of the contracts based on delivery mode of the trading partner. After you update the AS2Trading Relationship, you can proceed to perform the file transfer between the trading partners.
  • Updating the delivery mode attribute from Synchronous to Asynchronous(HTTP/HTTPS/SMTP) or vice-versa in AS2 TradingPartner API requires calling Update AS2TradingRelationship API on both client/server.
AS2 TradingRelationship Services Services to create, read, update, and delete the AS2 TradingRelationship profiles. The API also supports storing AS2 messages in Global Mailbox in addition to file system and mailbox.
BTF Services

Operations to create, read, update, and delete BTF Services.

These APIs are developed using SpringBoot framework and are available on Swagger docs.

Default URLs:

EBICS Client APIs:
http://<Install_Host>:<Liberty_port>/ebicsclientapis/swagger-ui.html​.

EBICS Server APIs:
http://<Install_Host>:<Liberty_port>/ebicsserverapis/swagger-ui.html​.
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 Order Services Services to create, read, update, delete, and review EBICS custom order types.

These APIs are developed using SpringBoot framework and are available on Swagger docs.

Default URL - http://<Install_Host>:<Liberty_port>/customorderapis/swagger-ui.html​.
Custom Protocols Service to read custom protocols available in the system.

Custom Sterling File Gateway Extensions Services (Custom Protocols)

 Services to read and update Sterling File Gateway extensions (Custom Protocols) in Sterling B2B Integrator.

The system creates two entries for Sterling File Gateway extensions of type custom protocol during factory setup. One of the entry corresponds to AFTExtensions.xml and AFTProperties.properties file and other entry to AFTExtensionsCustomer.xml and AFTExtensionsCustomer.properties files.

The Read API retrieves the contents of the AFTExtensions.xml and AFTProperties.properties and AFTExtensionsCustomer.xml and AFTExtensionsCustomer.properties files.

The Update API allows you to specify the Sterling File Gateway extensions like custom protocols and properties. When you update the content using the Update API, the system updates the AFTExtensionsCustomer.xml and AFTExtensionsCustomer.properties files, but does not allow you to modify the content of the AFTExtensions.xml and AFTProperties.properties files. The corresponding validation messages are displayed.
CustomJar Services Services to create, read, update, and delete custom jar files that can be deployed in a Sterling B2B Integrator environment. You can upload and deploy the third party jar files on specific nodes using the APIs.
Note:
  • You must provide the Node List as ALL (in capital letters) when you upload the third party Jar files to all nodes using this REST API.

  • 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:
  • You must provide the Node List as ALL (in capital letters) when you upload the custom services to all nodes using this REST API.

  • 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: 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”.
GetPayload API: Used to export data from a document into the storage subsystem.
  • If the size of document is < 2 MB, the GetPayload API returns the payload as a response string in the API output.
  • If the size of document is > 2 MB, the GetPayload API returns a URL that contains information about the document ID and isPlainText value.
Note: Sample URL: https://<IP_ADDRESS>:<PORT>/B2BAPIs/getPayloadData/<Document_Id>?isPlainText=false.

While executing the HTTP/HTTPS URL, you need to pass an authorization header that contains the login credentials of B2B APIs. Else, you cannot download the payload document. You can invoke the HTTP URL using custom client code or the CURL tool. For HTTPS, make sure to load the correct SSL certificates. The payload document is downloaded directly to the local file system.
File Gateway Arrived File Services Services to read, replay, and redeliver the files that arrive into Sterling File Gateway. Using the ReadFGArrivedFile API, you can also search the FG arrived files based on document IDs.
Redeliver FGArrived File API: Used to redeliver the files that arrive into Sterling File Gateway. When the file is redelivered through this API, some of the events listed below are not generated. However, the redeliver operation is successful. 

FGRoute event code and description which are not generated are: FG_0414 Route is now Delivering.
ArrivedFile event code and description which are not generated are: FG_0410 Arrived File is now Routing.
Delivery event code and description which are not generated are:
       1. FG_0423 Delivery is now Re-Delivering.
       2. FG_0201 Starting BP 'FileGatewaySendMessage' to send consumer file with workflow(WFID) and parameters.
File Gateway Delivery Services Service to read the Sterling File Gateway delivery details of the file.
ReadFgDeliveryDetails API - Used to read the FGDelivery file details.
Note: This API lists the details pertaining to File Gateway delivery and does not list any details related to File Gateway events.
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 when Sterling B2B Integrator is installed using the Docker image.
PropertyNodeValue Services Services to create, read, update, and delete custom property values for specific Sterling B2B Integrator nodes.
PGPKey Services Services to create, read, and delete PGP Keys from Sterling B2B Integrator.

These APIs are developed using SpringBoot framework and are available on Swagger docs.

Default URL - http://<Install_Host>:<Liberty_port>/pgpapis/swagger-ui.html​.

Secret Key APIs:​

  • Create, Check-in, Get, Update, Delete​, Create PGP Subkey

  • Get APIs:
    • Get All
    • Get with KEYID
    • Get with ObjectID​

​Secret Key GET API with KEYID and ObjectID gets the actual Secret Key data.​

Public Key APIs:​

  • Check-in, Get, Delete​

  • GET APIs:​
    • Get All
    • Get with KEYID
    • Get with ObjectID​

Public Key GET API with KEYID and ObjectID gets the actual Public Key data.

Note: For Public Key and Secret Key APIs, the system uses base64 encoding format in the API response for Actual Key data.

You can use the API response in JSON/XML format for CheckIn on Sterling B2B Integrator systems directly.

API response in JSON/XML format for CheckIn requires base64 decoding for any other third party vendors.
PGP Server Profile Services Services to create, read, update, and delete PGP Server Profiles.

Default URL - http://<Install_Host>:<Liberty_port>/B2BAPIs/svc​.
Routing Channel Services Services to create, read, and delete Routing Channels.
Routing Channel Duplicate Check Services Service to read Routing Channel Duplicate Checks.
Routing Channel Template Services Services to create, read, update, and delete Routing Channel Templates.

These APIs are developed using SpringBoot framework and are available on Swagger docs.

Default URL - http://<Install_Host>:<Liberty_port>/sfgapis/swagger-ui.html​.
Note: In the Routing Channel Template, you can select how special characters in the producer filename must be handled. The Special Characters tab has 6 options that can be selected when creating a Routing Channel Template.
In the XML request, you can add the following as parameter values for the ProducerFilenameCleaning parameter:

1. Option# 1: Substitute Characters -> <ProducerFilenameCleaning Mode="SubstituteSequence" From="abc" To="xyz"/>
2. Option# 2: Replace Characters -> <ProducerFilenameCleaning Mode="SubstituteCharacters " From="abc" To="xyz"/>
3. Option# 3: Remove Characters -> <ProducerFilenameCleaning Mode="Remove" From="ABC" To=""/>
4. Option# 4: Remove UNIX(R) invalid characters -> <ProducerFilenameCleaning Mode="RemoveForUnix" From="" To="" />
5. Option# 5: Remove Microsoft(R) Windows -> <ProducerFilenameCleaning Mode="RemoveForWindows" From="" To="" />
6. Option# 6: Remove all characters except alphanumeric dash and period-> <ProducerFilenameCleaning Mode="RemoveSpecial" From="" To="" />
In the JSON request, you can add the following as parameter values for the ProducerFilenameCleaning parameter:

"ProducerFilenameCleaning":
{
    "Mode": "SubstituteCharacters",
    "From": "a",
    "To": "b"
},
{
    "Mode": "SubstituteSequence",
    "From": "abc",
    "To": "xyz"
},
{
    "Mode": "Remove",
    "From": "abc",
    "To": ""
},
{
    "Mode": "RemoveForUnix",
    "From": "",
    "To": ""
},
{
    "Mode": "RemoveForWindows",
    "From": "",
    "To": ""
},
{
    "Mode": "RemoveSpecial",
    "From": "",
    "To": ""
},
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 Client Adapter 2.0
  • SFTP Server Adapter
  • SFTP Server Adapter 2.0
    Note: For more information on SFTP Server Adapter 2.0 service instances, see SFTP Server Adapter 2.0.
  • 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 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.
Schedule Services Services to create, read, update, and delete the schedules.
Note:
  • A 400 error occurs intermittently when you create a Schedule using an API. But, the Schedule is actually created in Sterling B2B Integrator.
  • A 500 error occurs intermittently when you delete a Schedule using an API. But, the Schedule is actually deleted in Sterling B2B Integrator.

The following is the error trace for the above mentioned errors:

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.
SSH Host Identity Key Grabber Services The ReadSSHHostIdentityKeyGrabber API is used to fetch the host identity key based on hostname and port number.
TestSFGDeliveryStatus Services Service to route the file to the FTP server of the listening consumers and return the delivery status of file.
Note:
  • If the input filename already exists in sourceMailboxPath, then the Read TestSFGDeliveryStatus API routes the same file to the listening consumer. Else, it generates a random file with input filename whose size is 0 KB and routes the newly generated file to the consumer.
  • The Read TestSFGDeliveryStatus API returns the delivery status of the file as response, if the routing completes within the input defaultTimeout value. Else, it returns the producerMessageID.
  • The file delivery status can be retrieved based on the messageID through the ReadFGArrivedfile API.
  • When you check for Sterling File Gateway file delivery using TestSFGDeliveryStatus API, the test input file is delivered twice on the 10x UI.
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.
  • Trading Partner services provide support for Target File encoding configuration for Trading Partners.
UI Branding Services Services to read and update Sterling B2B Integrator UI Branding elements.
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 and will display these object values as [ ] 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 user exit files.
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