Commercial network management

Outline

You can use the TradeAware API programmatically to invite your suppliers to your commercial network on behalf of your business.

The general steps involve:

• Authentication to get a programmatic access token.

• Interactions on behalf of a business using the access token.

• Sending business invitations to your suppliers to request access to their data.

• Receiving business invitations from your buyers requesting access to your data and that of your suppliers.

We already described how to get a programmatic access token and how to use it to interact with the API in the pages related to Authentication.

Please note, your suppliers must accept your business invitation explicitly in the TradeAware web application or through the API in order for you to establish a business connection to get access to their data. The same is valid in reverse, if you receive a business invitation from one of your buyers, you must explicitly accept it for them to get access to your data.

IMPORTANT: Your suppliers might reject your business invitations if they are not sure who is inviting them and for what reason. Therefore, even as we are actively working to make the whole process as seamless as possible, we recommend staying in touch with your suppliers to avoid misunderstandings about what is TradeAware and how you are using it to achieve EUDR compliance.

Available endpoints to handle your commercial network

Currently we provide two main endpoints to handle your commercial network:

/business-invitations to send, list and update business invitations. Check the API reference for business invitations to learn more.

/business-connections to get your suppliers or buyers. Check the API reference for business connections to learn more.

Getting started

As mentioned previously, please refer to our documentation on Authentication to get a programmatic access token and to learn how to use it.

From this point, the assumption is you already have a valid programmatic access token ready to use.

There are two main use cases around the commercial network, when you are a supplier and when you are a buyer. It is possible for you to be in the middle of the supply chain and have both roles, which is currently supported by TradeAware.

Commercial network for buyers

As a buyer your may want to invite your suppliers to our platform so that you may gain access to their data. In order to do that, the following is a list of actions and their expected results.

Sending a business invitation to your supplier

Make a POST request as shown below to programmatically send a business invitation to a supplier that you would like to have in your network:

Required Fields:

• email The email of the business you are inviting to connect.

Optional Fields:

• customData custom data you want to add to the invitation for later referencing.

curl -X 'POST' \
  'https://api.tradeaware.live-eo.com/business-invitations' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <JWT_VALUE_OF_ACCESS_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "[e-mail]"
  "customData": {
    "field": "value"
  }
}'

The response will contain a business invitation ID which will be useful in checking the status of the invitation later. Below is an example of business invitation with the most important keys and values:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sentByUser": {
    "auth0UserId": "auth0|41ba-aa49-f114ca4c263f",
    "business": {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "email": "[e-mail]",
      "name": "My Business Inc.",
      "username": "John Doe",
      "addressStreet": "Salawati 143",
      ...
  },
  "email": "[e-mail]",
  "status": "PENDING",
  "createdAt": "2020-01-01T00:00:00.000Z",
  "updatedAt": "2020-01-01T00:00:00.000Z",
  "sourceIsInvitee": true
}

Adding Custom Data to business invitations

You can also use the optional customData field on invitations as shown above. This flexible structure allows users to store relevant information about the business the invitation is being sent to, provided it follows these rules:

• Maximum of 10 keys.

• Data must be of type string, number, or boolean. Arrays are not supported due to validation and storage constraints.

This data is only visible to the business that adds the data. i.e. the invited supplier cannot see data added to their invitation.

About the statuses of a business invitation

When you send a business invitation, the default status is PENDING and it will remain in that state until one of the following scenarios occurs:

• Your supplier updates it with ACCEPTED or REJECTED

• You update it with CANCELLED

• It is marked as EXPIRED by TradeAware the invited user is not on TradeAware and the invitation is not accepted within 5 days.

Explanation of status states:

• PENDING: First status of a new business invitation and it means you are waiting for your supplier to take action.

• ACCEPTED: Your supplier has accepted the business invitation and is now part of your commercial network, which allows you access to their data. At the same time, your supplier will see you as a “buyer” but they will not have access to any of your data. In this moment there is a business connection between you and your supplier. This new concept is another resource in TradeAware commercial network that we will review with more detail later in this page.

• REJECTED: Your supplier rejected your business invitation. Please, confirm you sent the business invitation to the correct email address and remember to stay in touch with your supplier to address any misunderstandings. Feel free to send a new business invitation if necessary and the situation with your supplier has been clarified.

• CANCELLED: If you realize that the business invitation was sent in error or that it is no longer needed, you can cancel it so that the invited business will not have access to it anymore. This can be done only while the status of the business invitation is PENDING.

• EXPIRED: If your supplier neither accepts nor rejects the business invitation, and you don’t cancel it, it will be automatically expired after 5 days, if the user is not on the TradeAware platform. If they are on the TradeAware platform, it will not expire. Once expired you will have to send a new business invitation if you still want to request data from that supplier. We strongly suggest staying in touch with your suppliers to avoid these situations from occurring.

Please, notice that ACCEPTED, REJECTED, CANCELLED and EXPIRED are all final statuses in a business invitation. That means, once the business invitation is in any of those final statuses it can’t be changed.

Checking the status of a business invitation you have sent or received

To check the status of a business invitation, you can make a GET request to the endpoint listed below:

curl -X 'GET' \
  'https://api.tradeaware.live-eo.com/business-invitations/123e4567-e89b-12d3-a456-426614174000' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <JWT_VALUE_OF_ACCESS_TOKEN_HERE>'

The response will be identical to the response you received during the initial invitation creation and contain important information about the invitation's status

We suggest to use a polling strategy if you need time-critical responsiveness and of course, make sure your supplier knows you sent a business invitation for them to be part of your commercial network.

Cancelling a business invitation you sent

You can cancel a business invitation with the following call to the API:

curl -X 'PATCH' \
  'https://api.tradeaware.live-eo.com/business-invitations/123e4567-e89b-12d3-a456-426614174000' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <JWT_VALUE_OF_ACCESS_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "CANCELLED"
}'

This will cancel the business invitation and return a response that will show the status as CANCELLED. This means the business you invited will no longer see the business invitation or be able to take any further actions regarding that specific invitation. The business will not be part of your commercial network and you will not have access to their data.

Listing all the business invitations you sent

If you have sent any business invitations and would like to list them all, you can make a GET request as shown:

curl -X 'GET' \
  'https://api.tradeaware.live-eo.com/business-invitations?status=PENDING' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <JWT_VALUE_OF_ACCESS_TOKEN_HERE>'

This returns all the business invitations you have sent to your suppliers to become part of your commercial network and to have access to their data.

We are filtering the results to get only the business invitations you have sent and which are still in PENDING state. Check our API reference to know more about available options.

List all the suppliers in your commercial network

To get all the suppliers in your commercial network, make a GET request as shown:

curl -X 'GET' \
  'https://api.tradeaware.live-eo.com/business-connections/suppliers' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <JWT_VALUE_OF_ACCESS_TOKEN_HERE>'

This returns a list of all the business connections that have you as with the data of your suppliers in targetBusiness (for each item in the list).

Check what sourceBusiness and targetBusiness mean in our API reference for business connections.

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "sourceBusiness": {
      "id": "<YOUR BUSINESS ID>",
      "email": "[e-mail]",
      ...
    },
    "targetBusiness": {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "email": "[e-mail]",
      ...
    },
    ...
    "createdAt": "2021-01-01T00:00:00.000Z",
    "updatedAt": "2021-01-01T00:00:00.000Z",
    "plotsCount": 4
  }
]

See my supplier’s data through a business connection

You can see your supplier's data through another resource in the commercial network, the business connections! When your business invitation is ACCEPTED and your supplier becomes part of your commercial network, we create a new business connection to keep track of your commercial network in TradeAware.

So, in order to get your supplier's data you have to request:

curl -X 'GET' \
  'https://api.tradeaware.live-eo.com/business-connections/456e12345-e89b-12d3-a456-426614175001?includes=plots' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <JWT_VALUE_OF_ACCESS_TOKEN_HERE>'

The response will be the business connection data, including the plots of your supplier.

Another way to get all the plots of your suppliers (all of them, actually) is:

curl -X 'GET' \
  'https://api.tradeaware.live-eo.com/plots?includes=suppliers,mostRecentAnalysis' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <JWT_VALUE_OF_ACCESS_TOKEN_HERE>'

The response will contain all your plots, including the plots of our suppliers, and (if any exist) the most recent analysis for each plot.

Commercial network for suppliers

As a supplier, your may receive business invitations from your buyers in order for them to have access to your data. To share information with your buyers, here is a list of actions and their expected results.

Listing the business invitations you received

To list the business invitations you received, perform a GET request as shown below:

curl -X 'GET' \
  'https://api.tradeaware.live-eo.com/business-invitations?status=PENDING' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <JWT_VALUE_OF_ACCESS_TOKEN_HERE>'

This returns all the business invitations you have received from other businesses to become part of their commercial networks.

Please Note: Accepting any PENDING business invitation will give the sender access to your data. If necessary, confirm with your buyers the business invitations are coming from your actual buyers before accepting them.

It is extremely important you know who sent you an invitation before accepting it. We suggest staying in touch with your buyers to make sure there are no misunderstandings and you know who you are accepting invitations from to keep your data safe.

If you accept a business invitation by mistake, please, contact us to [e-mail] as soon as possible.

Accepting or rejecting a business invitation you have received

As a recipient of a business invitation, you have the option to either accept or decline it. To proceed, you may review all received invitations by filtering for those with a PENDING status and selecting the ID of the specific invitation you wish to act upon (by either accepting or rejecting it)."

The following PATCH request will accept a business invitation with the ID 123e4567-e89b-12d3-a456-426614174000 by changing the status from PENDING to ACCEPTED :

curl -X 'PATCH' \
  'https://api.tradeaware.live-eo.com/business-invitations/123e4567-e89b-12d3-a456-426614174000' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <JWT_VALUE_OF_ACCESS_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "ACCEPTED"
}'

If the request is successful, you will receive a response with the updated status of the business invitation and a reference to the new business connection with the buyer who sent the invitation..

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sentByUser": {
    "auth0UserId": "auth0|41ba-aa49-f114ca4c263f",
    "business": {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "email": "[e-mail]",
      "name": "Buyer Inc.",
      ...
  },
  "businessConnection": {
    "id": "456e12345-e89b-12d3-a456-426614175001",
    "sourceBusiness": {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      ...  
    },
    "targetBusiness": {
      "id": "<MY BUSINESS ID>"
      ...
    },
    "plotsCount": 4,
    ...
  },
  ...
  "email": "[e-mail]",
  "status": "ACCEPTED",
  "createdAt": "2020-01-01T00:00:00.000Z",
  "updatedAt": "2020-02-01T00:00:00.000Z",
  "sourceIsInvitee": true
}

Unlock new opportunities with your business connection! As a supplier, you can create detailed plots, request valuable analyses, and expand your commercial network by inviting your own suppliers. Your buyers will seamlessly receive this data, further enhancing your role within their commercial networks.

List all the buyers in your commercial network

Similar to the previous case, you can request:

curl -X 'GET' \
  'https://api.tradeaware.live-eo.com/business-connections/buyers' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <JWT_VALUE_OF_ACCESS_TOKEN_HERE>'

This returns a list of all the business connections that have you as targetBusiness with the data of your buyer in sourceBusiness (for each item in the list).

Check what sourceBusiness and targetBusiness mean in our API reference for business connections.

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "sourceBusiness": {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "email": "[e-mail]",
      "name": "Example Inc.",
      "username": "John Doe",
      "addressStreet": "Salawati 143",
      ...
    },
    "targetBusiness": {
      "id": "<YOUR BUSINESS ID>",
      ...
    },
    ...
    "createdAt": "2021-01-01T00:00:00.000Z",
    "updatedAt": "2021-01-01T00:00:00.000Z",
    "plotsCount": 4
  }
]

Next steps

Once you have sent business invitations to your suppliers and accepted the business invitations you received from your buyers you are ready to upload your plots data and request the analyses you need for them.

To learn how to do that please refer to our user guideline about plots data management and our API reference for plots and analysis.