Breadcrumbs

Automation and Interoperability

ChainTraced can be connected to your own systems in two directions: your system calls the ChainTraced API to read and write data, and ChainTraced calls your system through webhooks when something happens. Both need an API key from your company account.

Interface

Direction

Typical use

REST API

Your system asks, ChainTraced answers.

Create products, counterparties and transactions from your ERP, read approved results, attach documents, copy specifications.

Webhooks

ChainTraced pushes, your system receives.

Be told when a transaction is created or changes status, or when a lot changes, without polling.

Endpoints, request formats and authentication are documented at openapi.chaintraced.com/v2. The same link is available as API Documentation on the API keys page.

Where: click your name and avatar at the bottom of the side menu and open the tab API Keys & Webhooks. The tab requires the API module in your subscription and API-key scopes on your user.

Create an API key

A key acts as a user of its own: what it does is logged and signed under the name you give it, and it can do only what its scopes allow.

  1. Click Create new API Key.

  2. Fill in Firstname, Lastname and Role, all three required. Together they are the identity shown when the key signs a transaction. Add a Description, for example the system that will use it.

  3. Choose the Scopes the key needs, the same scope groups as for users. Give it no more than the integration uses.

  4. Click Create API Key. The key is shown once, with the header format to use:

Authorization: API-KEY <your key>

Copy the key before you tick I have saved the key and close the dialog. It cannot be shown again. A lost key is not a problem: Remove it and create a new one.

Manage keys

Active API Keys lists every key with its Created and Last used dates.

Action

What it does

Edit details

Changes name, role and description.

Scopes

Changes what the key may do; takes effect at once.

Duplicate

Creates a new key with the same details and scopes, for rotating a key: switch your system to the new key, then remove the original. The dialog reminds you.

Remove

Revokes the key immediately.

Webhooks

A webhook is an HTTPS endpoint in your system that ChainTraced sends a POST request to when one of these events happens.

Event

Sent when

Transaction Created

A new transaction is created, by you or by a counterparty towards you.

Transaction Status Change

A transaction changes status, for example Requested to Needs your approval, or to Approved.

Lot Status Change

A manufacturing lot changes status.

Lot Update

A manufacturing lot is changed.

Webhooks are registered by ChainTraced for you. Send support@chaintraced.com:

  1. The HTTPS URL of your endpoint.

  2. The events you want.

  3. The value your endpoint expects in the Authorization header, for example a Basic credential, so you can verify that a request really comes from ChainTraced.

Your registered endpoints are listed under Webhooks on the same tab with Type, Authorization header and Created; View available event types shows the events and their payloads are described in the API documentation. Your endpoint should answer quickly and do the actual work afterwards.