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 POST or PUT with a JSON body.
Use the Content-Type: application/xml header in case of PUT 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
Environments
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
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
A request can have an XML body, such as 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>
        ...
Tradecloud supports XML following the SCSN Standard​
XML text MUST be encoded using UTF-8​
Rules
Environments
Last modified 1yr ago