3. Integration scenarios

There are many different ways to connect with CargoX Platform. Depending on your needs you may pick one of these or combine them as you see fit. They range in the amount of integration needed, time taken, and how deep you connect to CargoX Platform.

3.1. Upload to CargoX

Purpose

Allow your users to simply upload files to CargoX

Time needed

10 - 60 minutes

Required skill level

●●○○○ 2/5

Suitable for

Final, closed or internal systems with direct users.

CargoX account

Not necessary, but preferred

One of the more basic way of integrating is allowing your users to upload files to CargoX. This integration style does not require any API integration with CargoX and can be done without CargoX's involvement.

Read more about it on a separate page.

3.2. Third-party API access to data on the platform

Purpose

Offer your clients advanced CargoX features

Time needed

60 minutes - 15 days

Required skill level

●●●●○ 4/5

Suitable for

Aggregator companies which offer services to other companies (B2B) and to final, closed or internal systems with direct users.

CargoX account

Required

As a third party company you may access the data of other companies on the platform through the API. You may execute commands on user's behalf, check for incoming and outgoing envelopes. You may issue administration commands, such as adding or removing users and topping up credits 1.

Attention

Third-party integration requires the company to consent to your application having access to their data. The consent process is similar to how – for example – Facebook, Linkedin, Twitter, Google… work. You will need to issue an authorization request from your app to access the data, and a user (with sufficient privileges from the company will need to authorize it.

Authorization is visible in the user interface and may be revoked by the users at any time.

3.2.1. API Authentication for external systems

If an external system wants to access the specific API for company creation and similar, it needs to fetch an authentication token for itself directly.

This is done by requesting a grant type of client_credentials:

Example

curl -s https://client_id:[email protected]/oauth/token/ \
    --data="scope=read%20write&grant_type=client_credentials"

Response:

{
// Token expiry time
"expires_in": 600,
// Refresh token
"refresh_token": "cU8PqVszJXX8A3bzFWKjMUfJK3nXXB",
// Access token to be used in Authentication: Bearer <token>
"access_token": "WlMxwPLaAG3krmvJxyzkSiVgIGaPIdH",
// Token type. Currently only “Bearer” is available
"token_type": "Bearer",
"scope": "read write"
}

This token may then be used to call the 3rd-party API.

Note

Impersonating a user

If a 3rd-party API needs to impersonate a user / work on his behalf, it possible to retrieve an OAuth token for such user. For details on how this works, please contact CargoX.

3.2.2. Company authorization or registration

In order to access data on behalf of CargoX users the external system needs to be authorized to do so. Regardles of the users' registration status (registered or unregistered) the workflow for external systems remains the same and is as follows:

sequenceDiagram participant U as User participant S as External system participant C as CargoX Platform U->>S: Clicks button "Connect my CargoX account" S->>C: Calls the API endpoint for authorizing users C->>S: Returns the URL with a token S->>U: Redirect user to CargoX with token U->>C: Register or log into the platform C->>U: Shows dialog that external systems wishes to connect to their CargoX account U->>C: Accepts or denies the request U->>S: (Optionally) User is redirected back to external system

Fig. 3.1 Sequence diagram of authorizing an external system to user's account on CargoX.

The API endpoint for authorizing users is located at https://cargox.digital/api/v3/registrations/app-tokens/

The external system needs to create a POST request on that endpoint and may fill it with the company details. This allows for easier registration because the registration form will already be pre-filled with this data.

cat << EOF > company.json
{
  "name": "A Salt and Battery Ltd.",
  "country": "US",
  "user_first_name": "Sherlock",
  "user_last_name": "Holmes",
  "user_email": "[email protected]",
  "redirect_url": "https://3rd-party-registration-finish.example.org?registrationId=iddqd"
}
EOF

curl \
   -H 'Authorization: Bearer 3gjCob2ryo6WvYQtmAuwwEBfuvQkrr' \
   -X POST
   -H "Content-Type: application/json" \
   --data @company.json \
   https://cargox.digital/api/v3/registrations/app-tokens/

The result of this post will be an object that has the attribute registration_url which is used to redirect the user to the CargoX website. Upon completion of the workflow the user will be redirected back to redirect_url which was entered as part of the API call.

3.3. Affiliate model

3.3.1. Simple affiliate model

Purpose

Receive commission when users use the platform

Time needed

10 - 30 minutes

Required skill level

●○○○○ 1/5

Suitable for

Aggregator companies which offer services to other companies (B2B).

CargoX account

Required

The most basic level of integration where you redirect your users to CargoX Platform to handle the transfer of documentation. The link can either be a redirect or you may directly embed (IFRAME) CargoX platform into an existing solution.

Users still need to register at CargoX Platform and need to input all the information about the documents into CargoX Platform. Users buy credits for using the platform through our official sales channels. We track the spending of credits and you get a commission.

3.3.2. Extended affiliate model with API integration

Purpose

Offer your clients advanced CargoX features

Time needed

60 minutes - 15 days

Required skill level

●●●●○ 4/5

Suitable for

Aggregator companies which offer services to other companies (B2B).

CargoX account

Required

A more advanced integration where, the main capabilities still occur within CargoX Platform, but certain information is transferred automatically. This helps facilitate the process for the end user.

Basically mix of Third-party API access to data on the platform and Simple affiliate model.

3.3.2.1. Example

You might already have a business relationship with your clients and you are already charging them for your services. You would like to simplify their life and issue just one invoice for all services – including whatever worgok they do on CargoX.

You could buy credits from CargoX yourself and then top up your client accounts when needed.

3.3.3. Whitelabel model

Purpose

Offer your clients advanced CargoX features

Time needed

10 - 30 minutes

Required skill level

●○○○○ 1/5

Suitable for

Aggregator companies which offer services to other companies (B2B) and to final, closed or internal systems with direct users.

CargoX account

Required

This option allows you to customise our front-end to your company's look and feel. We can change colours, fonts, images, logos. We can also hide certain functionalities from the user interface if you'll be using the API to provide those services programmatically.

All the capabilities of the CargoX Platform are fully embedded into your platform. Your users can directly use the full functionalities of our platform in your system to manage their document workflow.

Important

The CargoX Platform is running on the global instance of the blockchain (Ethereum). There’s no way to limit / prevent the users of logging into the system through other affiliates or white labels. In other words: every company registers on the platform once. Once registered, it can log in through any affiliate / whitelabel page with the same credentials.

1

Level of access also depends on what kind of permissions your app has on the platform. Third-party API access apps go through a more rigorous vetting process and your possible scope depends on the outcome of this process.