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:
- 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.
- 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.
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.
Uploading files directly
- 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
Sequence diagram of posting a file to CargoX.
The workflow for pushing a file to CargoX contains the following steps:
- Upload a file via an HTTP
POSTrequest. - Receive a
redirect_urlas part of the response of the POST request. - Redirect the user to the received
redirect_url. - 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.
POST /api/v3/upload-to-cargox/
To upload a file to CargoX Platform, use the following endpoint:
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 [email protected] \
-F expiry=10 \
https://cargox.digital/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) |
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.
Sending a reference to a hosted file
- 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.
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 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.
Suggested graphics
To make it easy for users to understand what's going to happen with the file, CargoX has prepared button styles which you can use in your platform to signal the transfer of the document to CargoX.
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:
