Cargoplot APICargoplot API
API docs
OpenAPI spec

Documents

A shipment has a checklist of documents: one slot for each paper that is expected, such as the commercial invoice, the packing list or the house bill of lading. You can read the checklist, download the files in it, and put files into it from your own systems: a portal, your team, or your factory directly.

The checklist

GET
/v1/shipment/C2AE-XEE1/document
curl -H 'X-Cargoplot-Key: <token>' \
  'https://api.cargoplot.com/v1/shipment/C2AE-XEE1/document'

Every entry is a slot. Its id is the slot id, which is what an upload takes. A slot with no file has "document": null; one with a file carries the file's document, whose own id is what GET /v1/document/{document}/download takes. The two ids are different numbers, so keep them apart.

The checklist shows what the app shows you. Arrival notices are listed, and so are delivery orders when your organization has them, but both are download-only through the API: Cargoplot supplies them. Master bills of lading and master airway bills are not listed at all.

Upload into a slot

When you know which slot a file belongs to, send it there:

POST
/v1/shipment/C2AE-XEE1/document/3
curl -X POST 'https://api.cargoplot.com/v1/shipment/C2AE-XEE1/document/3' \
  -H 'X-Cargoplot-Key: <token>' \
  -H 'Content-Type: application/json' \
  -d "{\"file_name\": \"invoice.pdf\", \"content\": \"$(base64 -w0 invoice.pdf)\"}"

{shipment} takes the Cargoplot reference or the numeric id, as the reads do, and {slot} is the slot's id from the checklist. On macOS, base64 -i invoice.pdf does what base64 -w0 invoice.pdf does elsewhere.

The body is JSON with two keys:

Key
file_nameThe file's name, kept with the document. Any folder in it is dropped, and so are control characters. A name that is empty afterwards answers 400.
contentThe file, base64 encoded: the standard alphabet or the URL-safe one.

Any other key answers 400, and message names it. The file's type is never something you send: it is recognised from the file itself.

The answer is 200 with the slot, as the checklist renders it, and now with its document set.

What an upload does

It does what an upload in the app does. The slot becomes STATUS_RECEIVED, its provided_on is set, and a rejection_reason is cleared. The file's text is read and the file is classified, which is recorded beside the type of the slot without changing it. A file recognised as both a commercial invoice and a packing list answers both slots. The VAT, EORI and KvK numbers on a representation document are read onto your organization, as they are when you upload one in the app.

A slot that already holds a file takes a new one: it replaces the file. A rejected slot takes a new file too, which is how you answer a rejection.

Which files are accepted

The file is recognised by its content, not by anything you say about it, and its name has to agree with what it is.

TypeNotesExtensions
PDF.pdf
DOCX, XLSXThe modern Word and Excel formats.docx, .xlsx
TXTValid UTF-8 text that does not start like HTML or XML.txt, .csv, .tsv, .log, .json, .md
PNG, JPG, GIF.png, .jpg or .jpeg, .gif

A name with another extension answers 400 on file_name, whatever the file holds: a PDF called invoice.txt is refused, and so is a text file called invoice.bat, because the name is kept and travels with the document when the documents of a shipment are downloaded together. A name with no extension is fine.

Legacy .doc and .xls files, and macro-enabled .docm and .xlsm files, are refused: send them as PDF, DOCX or XLSX. So is anything else that is not in the table.

A file is at most 15 MiB once decoded, and not empty. The live figure is published as max_upload_bytes at GET /api-info.json, and shown with the other limits under rate limits. Base64 makes the request a third larger than the file, which stays inside the largest body the API reads.

Sending the same file again

Repeating an upload whose bytes are the same as the file the slot already holds writes nothing. The answer is the slot as it is, with Idempotent-Replayed: true among the response headers, so a retry after a timeout is safe. A file with the same bytes and another name is the same file. Any other retry is answered the same way when both carry the same Idempotency-Key.

Refusals

StatusWhen
400The file is refused: empty, over the limit, of a type that is not accepted, or without a usable file_name (empty, or with an extension that does not fit the file). details names the field, content or file_name. A slot that is not a number, a key the endpoint does not know and content that is not base64 answer 400 as well.
403The slot is on your checklist but not open to uploads through the API: a delivery order or an arrival notice.
404No such shipment in your organization, or no such slot on it that you can see. A slot of another shipment, a slot you cannot see, and one that does not exist answer the same.
413The request declares a body over the largest one the API reads. See errors.
429The upload allowance is used up. See rate limits.

Upload without a slot

When nobody has made a slot for a file, or you would rather not match slots yourself, send the file to the shipment:

POST
/v1/shipment/C2AE-XEE1/document
curl -X POST 'https://api.cargoplot.com/v1/shipment/C2AE-XEE1/document' \
  -H 'X-Cargoplot-Key: <token>' \
  -H 'Content-Type: application/json' \
  -d "{\"file_name\": \"packing list.pdf\", \"type\": \"TYPE_PACKING_LIST\", \"content\": \"$(base64 -w0 'packing list.pdf')\"}"

The body is the same, with two optional keys:

Key
typeWhat the file is, for instance TYPE_COMMERCIAL_INVOICE (glossary). Leave it out to have the file classified.
labelA name for the slot created for the file. It is ignored when an existing slot takes the file.

Where the file goes

The file goes where it would if it had arrived by email.

  1. The type. With a type, that is the type. Without one, the file is classified from its name and its text, and the type it is recognised as is used. A type you may not upload, a delivery order or an arrival notice or a master bill of lading or airway bill, is never chosen for you: the file goes into a new TYPE_OTHER slot. Naming one of those yourself answers 400 with a violation on type.
  2. The slot. One open slot of that type, a slot without a file, takes the file. When there is none, a slot is created for it, named with label. TYPE_OTHER always gets a new slot, named with label or else with the file name. A rejected slot or a slot that holds a file is not open.

The answer is the slot with its document set, as above. It is 200 when an existing slot took the file and 201 when a slot was created for it.

When several slots are open

If more than one slot of the type is open, nothing says which one the file is for, and the answer is 409:

json
{
  "code": 10,
  "message": "several document slots of this type are open and the file does not say which one it is for (slot ids 12, 13): upload into one of them with POST /v1/shipment/{shipment}/document/{slot}",
  "details": []
}

On a shipment with several suppliers this is the normal answer for commercial invoices, packing lists and house bills of lading, because the shipment keeps one slot of each for every supplier. Pick the slot yourself, from the checklist, and use the upload into a slot above: it is the way in there.

A shipment holds one insurance certificate. While its slot is empty, a certificate fills it; once it has a file, another certificate answers 409 naming the slot, and you can replace the file with an upload into that slot.

Sending the same file again

A file with the same bytes as one that is already in a slot you can see writes nothing, whatever type or name you send with it. The answer is that slot with Idempotent-Replayed: true.

Refusals

The refusals of an upload into a slot apply, except 403 and the slot's 404: there is no slot to refuse. A shipment that is not yours answers 404. The others are:

StatusWhen
400A type you may not upload, or a type that is not a document type, as well as the refusals of the file itself.
409Several open slots of the type, or the insurance certificate slot is already filled. message names the slot ids.

Pacing uploads

Uploads have an allowance of their own, which is spent instead of the write allowance, so a burst of files does not keep you from changing a shipment or an inquiry. Both uploads draw on it. Running out answers 429, with API upload rate limit exceeded, and a Retry-After header. See rate limits.

Large files take time: the API stores the file and reads its text before it answers, and a request has the time published as the request timeout. An upload that times out is safe to send again: if the file arrived and was attached, the repeat is answered as a replay; if it did not, the repeat stores it.