Skip to main content
API docs by Redocly

Private Portal API (1.0.0)

Download OpenAPI specification:Download

The Private Portal API provides access to your Portal information. For the moment this covers Trade data, as well as Trade deliveries and their associated documents.

Trades represent the agreement reached at the end of a negotiation between buyer and seller. Trades typically reference one or more Trade deliveries. They are the equivalent of a purchase order in your ERP.

Within a Trade, the number of items in productTerms and deliveries can vary depending on deliveryType:

  • SINGLE_PRODUCT: productTerms contains exactly 1 item, deliveries can contain 1 or more items.
  • CALL_OFF: productTerms contains exactly 1 item, deliveries can contain 0 or more items. Their number is expected to grow as more deliveries are called off.
  • COMBINED_SHIPMENT: productTerms contains 1 or more items, deliveries contains exactly 1 item.

When polling the API you should filter by lastUpdate. Since users can freely edit Trades and add/edit Trade deliveries, the UI provides a readyToSync flag, which you can filter by. These Trades and Trade deliveries should have all the necessary ERP fields filled in.

Trace headers

In addition to the standard headers that you would expect, each response contains 2 specific headers. When asking for support, please provide them as reference if possible:

Header Description
X-Trace-Id Trace identifier used to track each request against internal logs
X-Server-Version Version of the server that responded

Errors

Kemiex uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Kemiex’s servers.

Unsuccessful responses contain 2 parts: an error code, and user-friendly message describing the issue. You can expect the following errors, though more may be added in the future:

Error Code
 Description
BAD_REQUEST_RESOURCE_NOT_FOUND Client-side error: the URL address is wrong
BAD_REQUEST_METHOD_NOT_SUPPORTED Client-side error: the HTTP method used in the request is not supported by the endpoint
BAD_REQUEST_MISSING_REQUIRED_PARAMETER Client-side error: at least one of the required parameters is not provided
BAD_REQUEST_PARAMETER_TYPE_MISMATCH Client-side error: a parameter value does not match its expected type
BAD_REQUEST_PARAMETER_VALUE_ILLEGAL Client-side error: a parameter value is outside the range of values allowed
BAD_REQUEST General client-side error: The request cannot be processed. This is a catch-all error thrown when the errors above do not apply
FORBIDDEN The API key is not provided, or the provided value is incorrect, or the associated account does not have access to the requested resource
INTERNAL_SERVER_ERROR An unexpected condition was encountered on the server

Trades

Trade-related operations

List all trades

Returns a list of Trades, ordered by lastUpdated descending. Trades include only limited information. Use the UUID value to perform a full entity retrieval.

Authorizations:
apiKey
query Parameters
lastUpdateFrom
required
string <date-time>
Examples:
  • lastUpdateFrom=2024-11-23T21:15:30+01:00 - Timestamp in UTC+1 timezone.
  • lastUpdateFrom=2024-11-23T20:15:30Z - Timestamp in Zulu timezone

Only return items items updated after the given date/time (ISO 8601 format).

lastUpdateTo
string <date-time>
Examples:
  • lastUpdateTo=2024-11-23T21:15:30+01:00 - Timestamp in UTC+1 timezone.
  • lastUpdateTo=2024-11-23T20:15:30Z - Timestamp in Zulu timezone

Only return items items updated before the given date/time (ISO 8601 format). If omitted, the current date/time is implied

readyToSync
boolean
Example: readyToSync=true

Only return Trades that are ready to sync. These Trades have at least one delivery marked as ERP ready.

page
integer <int32> >= 1
Default: 1
Example: page=1

The page number to retrieve. Starts from 1.

pageSize
integer <int32> [ 1 .. 500 ]
Default: 100
Example: pageSize=50

The number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "results": [
    • {
      }
    ],
  • "pageNumber": 3,
  • "pageSize": 40,
  • "totalResults": 193,
  • "totalPages": 5
}

Retrieve a Trade

Returns a Trade object.

Authorizations:
apiKey
path Parameters
tradeUuid
required
string <uuid>
Example: b43dd825-8a99-4676-aae7-9b91817c2c3c

The universal unique identifier of the desired trade

Responses

Response samples

Content type
application/json
{
  • "uuid": "b43dd825-8a99-4676-aae7-9b91817c2c3c",
  • "id": 4321,
  • "created": "2025-02-27T07:48:46.185364Z",
  • "lastUpdated": "2025-02-27T08:06:22.136545Z",
  • "buyerEmail": "john.smith@example.com",
  • "buyerCompany": {
    • "name": "A wonderful name"
    },
  • "sellerCompany": {
    • "name": "A wonderful name"
    },
  • "deliveryType": "SINGLE_PRODUCT",
  • "deliveryTerms": {
    • "incotermType": "CFR",
    • "via": "air",
    • "source": {
      },
    • "destination": {
      }
    },
  • "calloffTerms": {
    • "startDate": "2024-03-21",
    • "endDate": "2024-08-25"
    },
  • "readyToSync": true,
  • "state": "OPEN",
  • "confirmationDate": "2024-03-21",
  • "contractId": "string",
  • "fxHedgeNeeded": true,
  • "productTerms": [
    • {
      }
    ],
  • "deliveries": [
    • {
      }
    ],
  • "buyerDocuments": [
    • {
      }
    ],
  • "sellerDocuments": [
    • {
      }
    ]
}

Trade deliveries

Operations related to trade deliveries

List all Trade deliveries

Returns a list of Trade Deliveries, ordered by lastUpdated descending. Trade deliveries include only limited information. Use the UUID value to perform a full entity retrieval.

Authorizations:
apiKey
query Parameters
lastUpdateFrom
required
string <date-time>
Examples:
  • lastUpdateFrom=2024-11-23T21:15:30+01:00 - Timestamp in UTC+1 timezone.
  • lastUpdateFrom=2024-11-23T20:15:30Z - Timestamp in Zulu timezone

Only return items updated after the given date/time (ISO 8601 format).

lastUpdateTo
string <date-time>
Examples:
  • lastUpdateTo=2024-11-23T21:15:30+01:00 - Timestamp in UTC+1 timezone.
  • lastUpdateTo=2024-11-23T20:15:30Z - Timestamp in Zulu timezone

Only return items items updated before the given date/time (ISO 8601 format). If omitted, thecurrent date/time is implied.

readyToSync
boolean
Example: readyToSync=true

Only return Trade deliveries that are marked as Ready to sync into ERP.

page
integer <int32> >= 1
Default: 1
Example: page=1

Desired page number of results. First page is 1.

pageSize
integer <int32> [ 1 .. 500 ]
Default: 100
Example: pageSize=50

Maximum number of results that should be returned per page. Please keep it constant for requests across multiple pages, in order to correctly receive all results.

Responses

Response samples

Content type
application/json

Bad Request Example

{
  • "errorMessage": "Method parameter 'lastUpdateFrom': Failed to convert value of type 'java.lang.String' to required type 'java.time.OffsetDateTime'; Failed to convert from type [java.lang.String] to type [@io.swagger.v3.oas.annotations.Parameter @org.springframework.web.bind.annotation.RequestParam java.time.OffsetDateTime] for value [2024-12-25]"
}

Retrieve a Trade delivery

Returns a Trade delivery object.

Authorizations:
apiKey
path Parameters
tradeDeliveryUuid
required
string <uuid>
Example: b43dd825-8a99-4676-aae7-9b91817c2c3c

The universal unique identifier of the desired trade delivery

Responses

Response samples

Content type
application/json
{
  • "uuid": "b43dd825-8a99-4676-aae7-9b91817c2c3c",
  • "id": "4321-03",
  • "created": "2025-02-27T07:48:46.185364Z",
  • "lastUpdated": "2025-02-27T08:06:22.136545Z",
  • "state": "OPEN",
  • "authorEmail": "john.smith@example.com",
  • "readyToSync": true,
  • "providerCode": "string",
  • "purchaseOrganizationCode": "string",
  • "customerCode": "string",
  • "deliveryTerms": {
    • "incotermType": "CFR",
    • "via": "air",
    • "source": {
      },
    • "destination": {
      }
    },
  • "deliveryDate": {
    • "type": "WEEK",
    • "weekNumber": "2025-W01",
    • "date": "2024-12-30"
    },
  • "eta": {
    • "type": "DAY",
    • "date": "2024-12-20"
    },
  • "etd": {
    • "type": "DAY",
    • "date": "2024-11-27"
    },
  • "blDate": {
    • "type": "DAY",
    • "date": "2024-11-26"
    },
  • "blNumber": "string",
  • "productTerms": [
    • {
      }
    ],
  • "buyerDocuments": [
    • {
      }
    ],
  • "sellerDocuments": [
    • {
      }
    ]
}

Files

File-related operations

Retrieve a File

Returns the download URL of a file uploaded on a Trade or Trade delivery.

Authorizations:
apiKey
path Parameters
fileUuid
required
string <uuid>
Example: b43dd825-8a99-4676-aae7-9b91817c2c3c

The universal unique identifier of the file

Responses

Response samples

Content type
application/json
{
  • "fileName": "Sales confirmation [Final version].pdf",
  • "downloadUrl": "string"
}