Requests

How to make API requests

Making an API request

An API request consist of:

• HTTP method: GET, POST, PUT or DELETE

• HTTP headers: authorization and content type

• URL: HTTPS, environment, service, method and parameters

• JSON body which contains the payload

HTTP method

The API supports

• GET to get a specific JSON object, like a purchase order, or to download a document (one JSON object or document is returned) or to query objects (a JSON collection is returned)

• POST to create a new JSON object or upload a document

• PUT to update an existing JSON object

• DELETE to delete an existing JSON object or document

HTTP headers

Authorization

Use the Authorization header for basic authentication and token authorization, see Authentication

Content-Type

Use the Content-Type: application/json header in case of a POST with a JSON body.

Use the Content-Type: application/xml header in case of a POST with an XML body.

URL

The API uses the REST software architectural style that defines a set of constraints to be used for creating Web services. The API additionally uses a command and query style.

An URL is build up like this: https://environment/service/method/parameters?parameters

HTTPS scheme

The API only supports HTTPS, see Encryption.

Environments

Tradecloud has three environments:

• test environments have a short dynamic life cycle and have NO availability SLA

• the acceptance test environment has an availability SLA of 95% 10/5

• the production environment has an availability SLA of 99.5% 24/7

pageEnvironments

Services

Each environment has a set of services which you can find on each environment page, like the acceptance test environment and production environment

On the environment page for each service the API endpoint you can find the OpenAPI 2.0 Specification YAML file, the OpenAPI UI rendering, the health and label (version) is published.

Common used services are:

• authentication for authentication, to get a token

• api-connector for buyer and supplier ERP integration

• object-storage to upload and download documents

• order for order/line commands

• order-search for order queries

• order-line-search for order-line queries

• sci-connector for buyer ERP integration using SCSN

Methods

In each OpenAPI 2.0 Specification you can find the methods supported by the service. For example the api-connector service:

POST /api-connector/order sends an order by the buyer

POST /api-connector/order-response sends an order response by the supplier

Parameters

Most service methods have either path parameters, query parameters and/or a JSON body or XML body

Path parameters

A request can have a path parameter such as an {id} in object-storage service download method:

GET /object-storage/download/{id}

Query parameters

A GET request can have a query parameter such as a query in company-search:

GET /company-search?query=name

JSON body

The Tradecloud API supports a proprietary JSON format:

A POST request has a JSON body (payload), such as a purchase order sent to the api-connector service order method:

POST /api-connector/order

{
  "order": {
    "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "supplierAccountNumber": "12345",
    "purchaseOrderNumber": "PO123456789",
    "destination": {
        ...

JSON is a standard published as RFC 8259 and ECMA-404 (PDF)

• JSON text MUST be encoded using UTF-8

• JSON strings: some characters, like the quote, MUST be escaped

• JSON strings: for date/time values ISO 8601 date format YYYY-MM-DD or local date/time format YYYY-MM-DDThh:mm:ss is used

XML body

Tradecloud supports XML:

• Following the tXML standard for some api-connector and order-webhook-connector API endpoints.

• Following the SCSN Standard for the sci-connector API endpoint.

tXML

The Tradecloud API supports a proprietary XML format, called tXML, which is a 1-on-1 translation of the proprietary JSON format:

A POST request has a tXML body (payload), such as a purchase order sent to the api-connector service order method:

POST /api-connector/order

<?xml version="1.0" encoding="UTF-8"?>
<SendOrderByBuyer>
    <companyId>00f03b98-2511-489f-9695-13791b3f66b6</companyId>
    <supplierAccountNumber>12345</supplierAccountNumber>
    <purchaseOrderNumber>PO123456789</purchaseOrderNumber>
    <destination>
       ...

• XML text MUST be encoded using UTF-8

Isah SCI API

A sci-connector POST request has a SCSN body (payload), such as a purchase order sent to the sci-connector service order method:

PUT /sci-connector/order

<?xml version="1.0" encoding="UTF-8"?>
<Order>
    <ID>123</ID>
    <IssueDate>2018-10-06</IssueDate>
    <Note>[Free-form text]</Note>
    <BuyerCustomerParty>
        ...

• XML text MUST be encoded using UTF-8