REST API

All functionality of Tradeshift is exposed through a REST API, but only a subset of this API is exposed publicly. The public API gives control over the following resources:

• Content – for handling raw documents (invoices, attachments, any kind of business documents)
• DocumentMetadata– holds document metadata
• DocumentList – lists of document references, based on filter- and search criteria
• DispatchRequest – sends documents to other Tradeshift companies, or to external networks
• TagList - gets a list of tags put on a specific document

The ‘Connection’ resource is used to manage the business network of your company, and for referencing senders and receivers of business documents.

• ConnectionTemplate– template-based search for discovering network information
• ConnectionDetail – for managing the details of a connection
• ConnectionOverview - summary information of a connection
• ConnectionList – overview list of connections
• TradeshiftConnection/ExternalConnection – for managing business connections

Users and tenants (companies in Tradeshift terms) are handled with the "Tenant" and "User" resources. Tenants and users are referenced in the API through their Tradeshift-internal IDs.

• Tenant - manages a tenant within Tradeshift. Referenced through 'Tenant ID'.
• User - manages a user within Tradeshift. Referenced through 'Actor ID'.

The Tradeshift API is a REST based API, using HTTPS and OAuth for security, and idempotent message delivery for reliability.

The main security protocol for API access is 2- and 3-legged OAuth over 1-way SSL with at least 128 bit encryption.

This document focuses on 2-legged OAuth, which is used to realize the in-house system integration scenario, which allows individual businesses to handle documents and dispatching remotely. Keys to the APIs are issued on a per-tenant basis. In contrast to the 3-legged OAuth, the 2-legged variant does not require an end user to intervene for delegated authorization.

The 2-legged OAuth flow is:

1. Client is registered with Tradeshift as OAuth consumer for a specific tenant. This gives the service the right to act on behalf of any user associated with a specific tenancy, and associated a set of credentials with it.
2. Requests are made thus:
   1. Adding the regular OAuth headers to the REST resource request (version, nonce, timestamp, consumer key, signature method and signature)
   2. Including the tenant as either query parameter or HTTP header
3. Service response is returned

Tradeshift implements the IETF  “draft-hammer-oauth-10 “ draft, which addresses the session fixation attack vulnerability of 3-legged OAuth in the Core 1.0 spec, see [http://tools.ietf.org/id/draft-hammer-oauth-10.txt].

For the public Tradeshift API, HMAC-SHA1 signatures are required.

Within Tradeshift, a company is represented through the concept of a 'Tenant'. All resources (documents, business networks, contacts and so on) are owned by a Tenant. Since Tradeshift is a multi-tenant platform, the concept of a 'User' is also represented in Tradeshift, corresponding to individual users signing up. Each user is associated with one specific company.

API access keys are issued at the Tenant level - so all operations have tenant-wide scope. Resources PUT to tradeshift have tenant wide ownership, and is not associated with any specific user of a company, internally.

A notable exception is connections, which refer to specific users. For each tenant at tradeshift, there is at least one user. Connections refer to a specific user, and the tenant association is implicit in that. When searching for potential users in the tradeshift platform, the relevant IDs are returned in order to be able to create a connection to the specific Tradeshift user.

For reliability, Tradeshift uses idempotent message delivery. For placing a business document, such as an invoice, into tradeshift storage, the pattern is:

1. Client generates a UUID which represents the unique document
2. The invoice is PUT to Tradeshift, with the UUID as a parameter
3. The service returns a delivery receipt

If, for some reason, the client does not receive a receipt (due network errors, client crash or other), the client may PUT the document again, using the same ID as before. This is how the scenario runs:

1. Client generates UUID which represents the unique document
2. The invoice is PUT to Tradeshift with the UUID as a parameter
3. The service accepts the document, and returns a receipt, in the HTTP response
4. The client crashes before receiving the receipt
5. When the client gets back up, it re-PUTs the document with the same UUID
6. The service registers that it has persisted the document already, ignores the document, and returns a successful response.

Semantics are:

• Message IDs must be unique, within the timeframe they are cached at the server side (10 minutes currently)
• If a message is received with a message ID that has been used within that timeframe, server will assume that messages are equivalent, and discard all messages carrying that ID, after the first message has been persisted, and return a successful response to the client

The tables below summarize the conventions that are used in Tradeshift for REST resources.

{
  "ErrorCode" : "InvalidInput",
  "Message" : "The input for the attemted operation 
was not valid. A list of ValidationErrors is provided",
  "ValidationError" : [ {
    "ErrorCode" : "NoInvoice",
  } ],
  "RequestId" : "494e041e-05aa-4c2b-bb6b-046a2d29042b"
}

The table below shows the HTTP codes returned by Tradeshift services.

Convention for representing the user on whose behalf a service is called is to include tenant and user ID. Tenant ID must be added to all protected resource requests. User ID may or may not be required, depending on the exact resource and context of the call. This is documented with each single resource.

Building on top of the features of the first Tradeshift release, the following API features are being worked on:

• Additional resources, which are currently Tradeshift-internal
• 3-legged OAuth support, in addition to 2-legged
• Support for OAuth signatures based on asymmetric keys (RSA-SHA1)
• Key management functionality

This section goes through the resources of the public APIs.

Tradeshift document store is the pivot for sending and receiving documents. Before sending a document, it must stored in Tradeshift using the Document resource. Once stored, the document has an ID that can be used for dispatching the document.

When a UBL document is uploaded to Tradeshift, it is processed in this pipeline:

When a valid documet is uploaded, a corresponding DocumentMetadata record is created within Tradeshift.

The document is validated according to the documentProfileId parameter provided during the PUT operation. This validation is performed synchronously. Note that a full validation cannot be performed before final receiver information is available, which a client is not required to set before creating a DispatchRequest resource.

Documents which have been PUT to the Tradeshift platform may not be modified. However, the metadata of the document may be updated.

Once the document has been uploaded, it may be dispatched by creating a ‘DispatchRequest’ resource. The DispatchRequest resource can then be queried for the state of the request (i.e. if the document has been delivered, if delivery is still being attempted, if the document was returned).

The generic parameters such as ‘tenantId’ and ‘actorId’ are not repeated for each resource, instead the resource is flagged if they are not applicable, or have altered semantics.