Standards
Overview of standards used by the Tradecloud API and webhooks
Your integration must support these standards.
Basic authentication
Basic authentication is a simple HTTP authentication scheme built into the HTTP protocol. The client sends HTTPS requests with the Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password
Published as RFC 7617 "The 'Basic' HTTP Authentication Scheme"
Basic authentication is supported by both the API v2.0 and webhooks.
Bearer authentication
Bearer authentication is an HTTP authentication scheme that involves security tokens called bearer tokens. The client send HTTPS requests with the Authorization header that contains the word Bearer followed by a space and the token.
Published as RFC 6750 "The OAuth 2.0 Authorization Framework: Bearer Token Usage"
The bearer token is supported as part of JWT by the API v2.0.
The bearer token is supported as part of OAuth and as static token by the webhooks.
HTTP 1.1 and 2.0
The Hypertext Transfer Protocol is a stateless application-level protocol for distributed, collaborative, hypertext information systems.
HTTP 1.1. is published as RFC 7230 and RFC 7231 to 7237.
HTTP 2.0 is published as RFC 7540
ISO Date/Time
Date/time values use ISO 8601 date format YYYY-MM-DD or local date/time format YYYY-MM-DDThh:mm:ss
Published as ISO 8601-1:2019
JSON
Tradecloud supports JSON and XML. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format.
Published as RFC 8259 and ECMA-404 (PDF)
The JSON syntax does not assign any significance to the ordering of name/value pairs.
Therefor XML based transformations expecting ordering will break.
The Tradecloud compatibility rules apply to the JSON usage.
JWT
JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.
JWT is supported by the API v2 only (and not by the webhooks).
Media Types
Tradecloud supports a sub set of the RFC 6838 Media Type Specifications.
OAuth
OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server. OAuth relies on authentication scenarios called flows, which allow the resource owner (user) to share the protected content from the resource server without sharing their credentials. For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner.
Published as RFC 6749 "The OAuth 2.0 Authorization Framework"
The OAuth 2.0 Client Credentials Grant is supported by the order webhooks only (and not by the API v2 or shipment webhook at this moment). Order webhook OAuth uses the Microsoft Identity Platform (MSAL4J) -- it is not a general-purpose OAuth 2.0 client for other identity providers.
OpenAPI
The OpenAPI Version 2.0 Specification (OAS 2.0) creates a RESTful interface for easily developing and consuming an API by effectively mapping all the resources and operations associated with it.
REST
Representational state transfer (REST) is not a standard but a software architectural style that defines a set of constraints to be used for creating Web services. The Tradecloud API additionally uses a command and query style.
TLS v1.2 and v1.3
Transport Layer Security is a cryptographic protocol designed to provide communications security over a computer network.
URI
A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource.
Published as RFC 3986 with errata.
URLs can only be sent over the Internet using the ASCII character-set.
Since URLs often contain characters outside the ASCII set, the URL has to be converted into a valid ASCII format. URL encoding replaces unsafe ASCII characters with a "%" followed by two hexadecimal digits. URLs cannot contain spaces. URL encoding normally replaces a space with a plus (+) sign or with %20.
UTF-8
ISO/IEC 10646-1 defines a large character set called the Universal Character Set (UCS) which encompasses most of the world's writing systems. The originally proposed encodings of the UCS, however, were not compatible with many current applications and protocols, and this has led to the development of UTF-8
Published as RFC 9259
Units of Measure
Buyers send units in their own convention; suppliers see them as-is. No standard is enforced, despite field names such as purchaseUnitOfMeasureIso or unitOfMeasureUnece. If you want a standard, we recommend UN/ECE Recommendation N°20, but it is not required.
Exceptions to as-is handling:
the portal translates some human-unreadable units for display;
units are translated for the SCSN network;
Tradecloud treats equivalent buyer and supplier units as the same when comparing values.
XML
Tradecloud supports XML and JSON. The Extensible Markup Language its main purpose is serialization, i.e. transmitting arbitrary data.
Published as Extensible Markup Language (XML) 1.0 (Fifth Edition)
Tradecloud does not assign any significance to the ordering of XML tags.
Therefor XML based transformations expecting ordering will break.
The Tradecloud compatibility rules apply to the XML usage.
Last updated