Getting Shipment Documents

  • Ship
  • api
  • customs
  • documents
  • dangerous
  • hazardous
  • collection note

Ship can automatically generate customs documentation, and hazard labels for shipments. This page explains the various way in which Ship can return this documentation.

Documentation in Ship

Once a shipment is allocated, Ship automatically determines what documentation is required for it. Ship can generate the following document types:

  • cn22 - Customs documentation. Only generated for applicable international shipments.
  • cn23 - Customs documentation. Only generated for applicable international shipments.
  • commercial_invoice - Customs documentation. Only generated for applicable international shipments.
  • hazard_label - Generated for shipments containing dangerous goods.
  • collection_note - A driver's manifest for the shipment. Generated for all shipments.
Note

Ship also generates delivery labels, which have the same data structure as shipment documents and are also created after allocation. However, labels are managed through their own dedicated endpoints, and cannot be returned through Ship's Documents endpoints. For information on using delivery labels in Ship, see the Getting Shipment Labels page.

Ship offers two endpoints to retrieve documents once they have been generated:

  • Get Document retrieves a specific document.
  • Get Customs Documents retrieves all customs documents (that is, CN22, CN23, and commercial invoice documents) that have been generated for a particular shipment.
Note

Ship's auto-generated documents should not be confused with paperless documents. Paperless documents are documents that are attached to a shipment prior to allocation and transmitted to a carrier as part of that shipment's data. Auto-generated documents are created by Ship at the point of allocation and are intended to be printed before the carrier picks the shipment up.

For more information on using paperless documents in Ship, see the Adding Paperless Documents page.

Getting a Specific Shipment Document

To call Get Document, send a GET request to https://api.sorted.com/pro/documents/{shipment_reference}/{document_type}, where {shipment_reference} is the unique reference of the shipment that the document belongs to and {document_type} is the type of document you want to return for that shipment.

If the specified shipment has a document of the specified type, then Ship returns a document object representing that document. Otherwise, Ship returns an error.

Note

If you use the Get Document endpoint to get a collection_note for a shipment, then Ship returns a collection note for the contents of that shipment only. If you need collection notes for multiple shipments being picked up by the same carrier (as part of a scheduled collection, for example), you should use one of Ship's dedicated Collection Notes endpoints instead.

Getting All of a Shipment's Customs Documents

To call Get Customs Documents, send a GET request to https://api.sorted.com/pro/documents/{shipment_reference}, where {shipment_reference} is the unique reference of the shipment that you want to get customs documents for.

If the specified shipment has customs documents (that is, it is an international shipment), then Ship returns a list of document objects representing those documents. Otherwise, Ship returns an error.

Note

For full reference information on the Get Customs Documents endpoint, see the Ship API reference.

The Document Response

Both Documents endpoints return document objects. Get Document returns a single document, while Get Customs Documents returns a list.

The document object has four properties:

  • file - A base64-encoded byte array representing the file content.
  • content_type - The document's format (e.g. application/pdf).
  • document_type - The type of document (e.g. commercial_invoice).
  • dpi - The document's resolution in DPI.
Note

As customs documents are generated at the point of allocation, Ship returns a 404 - Not Found error if you attempt to get documents for an unallocated shipment. This code signifies that the request passed validation but there are no documents available for the specified shipment.

Examples

The example below shows a successful Get Document request for the cn22 document associated with shipment sp_00670175533382557003917067812864. Ship returns a document object representing that document. In this example, the Base64 data returned has been removed for clarity.

GET https://api.sorted.com/pro/documents/sp_00670175533382557003917067812864/cn22

The example below shows a successful Get Customs Documents request for all customs documents associated with shipment sp_00670175533382557003917067812864. Ship returns a list of document objects representing the cn22, cn23, and commercial_invoice documents associated with that shipment. In this example, the Base64 data returned has been removed for clarity.

GET https://api.sorted.com/pro/documents/sp_00670175533382557003917067812864

Using the Label Data

Once you have downloaded the file data, you will need to decode the file's Base64 in order to view the label itself. If you are unsure how to do so, see the MDN docs for more information.

Next Steps