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. Login with CargoX

Purpose	Offer your clients easier access to your services
Time needed	30 minutes - 2 hours
Required skill level	●●●○○ 3/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 users on the platform through the API. You may not execute commands on user's behalf.

Attention

Third-party integration requires the user 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 redirect user to CargoX Platform with certain parameters, and the user will need to grant access to your application.

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

3.3.1. Authorization flow

In order to access users' data 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->>U: Redirects user to CargoX with required parameters U->>C: Register or log into the platform U->>C: Accepts or denies the request C->>S: User is redirected back to external system S->>C: Uses authorization code to get access token

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

To initiate authorization process the external system needs to redirect user to CargoX Platform with two parameters in the URL. The first parameter is the external system client_id and the second is the redirect_uri, the URL where the user will be redirected after completing the authorization.

Below is an example of an URL where to send the user.

https://cargox.digital/?client_id=Y6SHcESVF5BPqhPf7cn4Gm9bePmT9hn8qbfnMm7h&redirect_uri=https://www.external-system.com

After user logs into his CargoX account and authorizes external system's application, the user will be redirected back to redirect_uri with authorization code added to URL parameters. Below is an example of such URL:

https://www.external-system.com?code=RbP0crrJo6FHq52gx8F8zMg0btZtea

External system can now use parameter code in combination with client credentials to obtain an access token. This is done by requesting a grant type of authorization_code. It is important to include the same parameter redirect_uri used previously in the authorization flow.

Example

curl --location --request POST 'https://cargox.digital/oauth/token/' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=Y6SHcESVF5BPqhPf7cn4Gm9bePmT9hn8qbfnMm7h' \
    --data-urlencode 'client_secret=by1waKYGtGz9dwroewaDBMwFtvqAJFseVIDFcXaNkNjUBGUQW0HGLdW9uVDH8RTufQCZtKI6flEXQciTawmstomHKVRFBisrBYfE2VNCw6YuJ8Pt2ICbfvYXX9IBumfO' \
    --data-urlencode 'grant_type=authorization_code' \
    --data-urlencode 'code=RbP0crrJo6FHq52gx8F8zMg0btZtea' \
    --data-urlencode 'redirect_uri=https://www.external-system.com'

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 user's API.

3.4. Create Envelopes with documents

Purpose	Offer your clients already created envelopes
Time needed	30 minutes - 2 hours
Required skill level	●●●○○ 3/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 create envelopes for users on the platform through the API.

Attention

Third-party integration requires the user to consent to your application having access to their data. The process of getting consent for API calls is described in the Third-party API access to data on the platform section.

3.4.1. Egypt ACI envelope

To create Egypt ACI Envelope we only have to create one POST call with few parameters:

• acid_number: ACID number for Egypt ACI.

• documents: Files to be added to the envelope.

• documents_metadata: JSON Metadata for documents.

• company_id: Optional, needed if third party system operates for more than one company.

• inbox_id: Optional, needed if company has more than one inbox.

Below is an example of an URL where to send POST request.

https://cargox.digital/api/v3/integrations/envelope-egypt-aci/

Example

curl --location --request POST 'https://cargox.digital/api/v3/integrations/envelope-egypt-aci/' \
     --header 'Authorization: Bearer 4mmivsUa11hRc27p08B750sKhfJZKR' \
     --form 'acid_number="8163854655616701000"' \
     --form 'documents_metadata="[
       {
         \"doc1.pdf\": {
           \"document_type\": \"INV\",
           \"meta_data\": \"{\\\"Internal number\\\":\\\"test internal number\\\",\\\"Release agent\\\":\\\"test release agent\\\"}\"
         }
       }
     ]"' \
     --form 'documents=@"/Documents/doc1.pdf"'

Response:

 [
    {
        "envelope_id": "1d6bde48-5a25-45db-8c18-94cb7a0256e3",
        "document_token_id": "bf8f75b2-ff24-46d1-9409-072b5972e351",
        "relayed_transaction": {
            "hash": "0x48d050bc7089c7f58eb459758e1a567593eab624428c653efd760ab323bd6e1f",
            "relay_nonce": 0,
            "recipient": "0xc8e04f362dB54e3FFeE14fC173f231B1A09DE851",
            "relayed_for": "0xf27B1E0B4Ad32727515ccdB5bd7e042877194FE1",
            "transaction_data": "0x3266df5b000000000000000000000000f27b1e0b4ad32727515ccdb5bd7e042877194fe100000000000000000000000000000000bf8f75b2ff2446d19409072b5972e351db45252961b433886541158b80a116094ba4c9d89a2a1a5e5ea038605b2efc2e000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000200000000000000000000000001d5862be3905da48cf6914dec3275bb635a2f5ae0000000000000000000000000000000000000000000000000000000000000001"
        }
    }
]

This response can be used to sign and send envelope through API.

3.4.2. Standard envelope

To create Egypt ACI Envelope we only have to create one POST call with few parameters:

• recipient_id: Inbox id of recipient company.

• documents: Files to be added to the envelope.

• documents_metadata: JSON Metadata for documents.

• company_id: Optional, needed if third party system operates for more than one company.

• inbox_id: Optional, needed if company has more than one inbox.

• pay_to_collect: Optional, defaults to False.

Below is an example of an URL where to send POST request.

https://cargox.digital/api/v3/integrations/envelope-egypt-aci/

Example

curl --location --request POST 'https://localhost:8081/api/v3//integrations/envelope-standard/' \
     --header 'Authorization: Bearer 4mmivsUa11hRc27p08B750sKhfJZKR' \
     --form 'recipient_id="33844efc-522e-4b96-863c-c1741a0646e1"' \
     --form 'documents=@"/C:/Users/wecht/OneDrive/Documents/doc1.pdf"' \
     --form 'documents_metadata="[
       {
         \"doc1.pdf\": {
           \"document_type\": \"GOO\",
           \"document_id\": \"123456\",
           \"meta_data\": \"{\\\"Internal number\\\":\\\"test internal number\\\",\\\"Release agent\\\":\\\"test release agent\\\"}\"
         }
       }
     ]"' \
     --form 'company_id="5df16c0a-0372-49a0-9079-dc00a927015f"' \
     --form 'pay_to_collect="False"'

Response:

 [
    {
        "envelope_id": "7fae51f9-49e1-4025-aa8e-533f3daac65c",
        "document_token_id": "686b0f72-fcb9-4527-b0e4-2424020bc5f6",
        "relayed_transaction": {
            "hash": "0x05c5ce21b1a2eea6e6528d62ca8af9020c8173ef3d3924232e88d2724fa89c23",
            "relay_nonce": 0,
            "recipient": "0xc8e04f362dB54e3FFeE14fC173f231B1A09DE851",
            "relayed_for": "0xf27B1E0B4Ad32727515ccdB5bd7e042877194FE1",
            "transaction_data": "0x3266df5b000000000000000000000000db2c6ffd852347e72c5779cd23cfcc949badaa7e00000000000000000000000000000000686b0f72fcb94527b0e42424020bc5f6b4bb8f6a8d1e8c3ef40233573606ba4737f59cd92f895e438ac441c0f6749ce2000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000200000000000000000000000001d5862be3905da48cf6914dec3275bb635a2f5ae0000000000000000000000000000000000000000000000000000000000000001"
        }
    }
]

This response can be used to sign and send envelope through API.

3.5. Affiliate model

3.5.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.5.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.5.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.5.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.