Quick navigation

6. Adding files from external sources

This section explains how to add an external file to CargoX. This feature allows other software that generates documents to seamlessly integrate with CargoX with very little development and modifications.

Two methods of integration are available:

  1. The push method where an external service uploads a file to CargoX and redirects a user to an appropriate URL where she can claim the file.

  2. The pull method where a user is redirected to a special URL with the external file in the query string. The workflow for the user remains the same as in the push method.

Note

You may choose any of the methods of attaching files to CargoX envelopes below - they both produce the same result. Which one you decide to use depends on how your application is structured; in some cases one method might be preferred over another.

6.1. Uploading files directly

Tip

Use this method, if:

  • You have control of your backend system

  • You generate documents on the fly

  • You can do it asynchronously / you don't expect upload to take long

sequenceDiagram participant S as External system participant C as CargoX Platform participant U as User U->>S: Clicks button "Upload to CargoX" S->>C: Upload file to CargoX C->>S: Return location of uploaded file S->>U: Redirect user to CargoX U->>C: Log into the platform C->>U: Pick file U->>C: Selects file and attaches it to a draft

Fig. 6.1 Sequence diagram of posting a file to CargoX.

The workflow for pushing a file to CargoX contains the following steps:

  1. Upload a file via a HTTP POST request.

  2. Receive a redirect_url as part of the response of the POST request.

  3. Redirect the user the received redirect_url.

  4. The user will need to log in (if not already logged in). Afterwards she will be able to "collect" the file and attach it to a chosen envelope.

To upload a file to CargoX Platform, please use the following endpoint:

POST /api/v3/upload-to-cargox/

Call this method first. Use it to upload the file attachment. Here is an example of attaching the file using curl.

curl -X POST \
   -F file=@sample.pdf \
   -F expiry=10 \
   https://cargox.ditigal/api/v3/upload-to-cargox/

There are three input arguments that you can use while calling this endpoint:

Argument

Description

Required

Default

file

The uploaded file.

Yes

expiry

Time in minutes before the file is deleted from CargoX servers if not claimed.

No

60 (minutes)

company

The ID of a registered CargoX company for extra security. Only users of that company will be able to access the file.

No

(none)

6.1.1. Example response

A call such as the one above will generate the following response:

{
  "redirect_url": "https://cargox.digital/?claim_file=a5996f36-ad3e-4a20-9a5f-9d4056396115",
  "expiry": 10,
  "company": null,
  "file_name": "sample.pdf",
  "id":"a5996f36-ad3e-4a20-9a5f-9d4056396115"
}

The only thing left to do is to redirect the user to the redirect_url received in the response. This example would require redirecting the user to https://cargox.digital/?claim_file=a5996f36-ad3e-4a20-9a5f-9d4056396115

After logging in, the user will be prompted to add the external file to a draft.

6.2. Sending a reference to a hosted file

Tip

Use this method, if:

  • Your file is already generated and hosted somewhere (for example, on a S3 bucket).

  • You can't modify backend code (this integration type can be implemented on the client-side / in HTML only).

  • You need to submit larger files.

sequenceDiagram participant S as External system participant C as CargoX Platform participant U as User S->>S: Prepares a file for upload U->>S: Clicks button "Upload to CargoX" S->>U: Redirect user to CargoX C->>S: Pulls the file from (3rd-party) server U->>C: Log into the platform C->>U: Pick file U->>C: Selects file and attaches it to a draft

Fig. 6.2 Sequence diagram of referencing a hosted file.

If, for whatever reason you can't push the file to CargoX, you may let the platform pull it. The workflow of is slightly different in this case. The external service needs to host a file so that it is accessible by CargoX servers.

If the file is hosted at the following URL:

http://example.org/file.pdf

The user needs to be redirected to the following URL:

https://cargox.digital/?add_file=http://example.org/file.pdf

After logging in, the user will be prompted to add the external file to a draft.

6.3. Suggested graphics

To make it easy for users to understand what's going to happen with the file, CargoX has prepared several button styles which you can use in your platform to signal the transfer of the document to CargoX. These styles are shown below. Feel free to copy the HTML code and introduce it into your app.

Use the following code to create the button:

<a href="###" target="_blank"><img style="display: block; height: 40px;" src="https://cargox.digital/images/upload-to-cargox-button.svg"></a>

This is how the button will be presented to the user:

_images/upload-to-cargox.png