Requests
How to make API requests
Making an API request
An API request consist of:
HTTP method:
GET
,POST
,PUT
orDELETE
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 documentPUT
to update an existing JSON objectDELETE
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
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 tokenapi-connector
for buyer and supplier ERP integrationobject-storage
to upload and download documentsorder
for order/line commandsorder-search
for order queriesorder-line-search
for order-line queriessci-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:
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 formatYYYY-MM-DDThh:mm:ss
is used
XML body
Tradecloud supports XML:
Following the tXML standard for some
api-connector
andorder-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:
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:
XML text MUST be encoded using UTF-8
Last updated