Consignment notes

When a carriage needs a consignment note, the carrier prepares it in Maxmove: a CMR for cross-border carriage, a German Frachtbrief within Germany, electronic or on paper. Sender, carrier, and consignee sign it at pickup and delivery. You can read the note and download the signed documents through the API.

Code examples use BASE_URL and headers from the Quickstart.

1. Wait for the event

   Maxmove sends delivery.consignment_updated whenever a note of the delivery changes: it is prepared, corrected, signed, sealed, delivered, cancelled, or replaced by paper. data.consignment is the note as the endpoint below returns it, without download links.

2. Read the notes

   Call GET /v1/deliveries/{deliveryId}/consignments. The key needs deliveries:read. The list is empty until the carrier prepares a note, and always empty for test deliveries.

   Field	Meaning
   number	The number printed on the note, for example CMR-027F3C2A41 or FB-027F3C2A41.
   type	international_cmr or german_freight_note.
   mode	electronic or paper.
   state	draft, awaiting_sender, issued, delivered, delivered_without_consignee, cancelled, or replaced_by_paper.
   version	Increases with every change of the particulars, state, or signatures.
   signatures[]	Who signed (role, signer_name), how (method), when (signed_at), and whether the signature is sealed into the evidence. decision is refused when a party refused to sign.
   reservations[]	The carrier's reservations about the goods at takeover and the consignee's at delivery.
   performing_carrier	The subcontractor who performs the carriage, when there is one.
   delivery_declaration	Set when the carrier delivered without the consignee's signature, for example when the goods were left at the door.
   files_ready	The current revision's PDF and evidence are sealed and archived.
   pdf_url, evidence_url	Short-lived links to the signed PDF and the sealed evidence (JSON). null until files_ready is true.

3. Download the files right away

   The links expire after a few minutes. Download the files when you read the list and store them yourself. Call the endpoint again for fresh links.

import { writeFile } from 'node:fs/promises';
 
async function storeConsignmentNotes(deliveryId: string) {
  const res = await fetch(`${BASE_URL}/deliveries/${deliveryId}/consignments`, { headers });
  const { consignments } = await res.json();
 
  for (const note of consignments) {
    if (!note.files_ready || !note.pdf_url) continue;
    const pdf = await fetch(note.pdf_url);
    await writeFile(`${note.number}-v${note.version}.pdf`, Buffer.from(await pdf.arrayBuffer()));
  }
}

def store_consignment_notes(delivery_id):
    res = requests.get(f"{BASE_URL}/deliveries/{delivery_id}/consignments", headers=headers)
    for note in res.json()["consignments"]:
        if not note["files_ready"] or not note["pdf_url"]:
            continue
        with open(f"{note['number']}-v{note['version']}.pdf", "wb") as f:
            f.write(requests.get(note["pdf_url"]).content)

How to read events#

• Several events per version. A signature first arrives unsealed and then sealed, and the files become ready later still. Each of these sends an event with the same version.
• Skip stale events. Events can arrive out of order. Ignore one whose data.consignment.version is lower than the last one you processed.
• Corrections need new signatures. When the carrier corrects an issued electronic note, revision_number increases and state is awaiting_sender until the sender signs the corrected version.
• Paper replacements. A note in replaced_by_paper names its paper replacement in replacement_id. Both are in the list.

Fleet orders#

Fleets read the notes of their own orders with GET /v1/fleet/orders/{fleetOrderId}/consignments. The key needs fleet_orders:read, and the response has the same consignments. Fleet orders don't send webhook events.

Errors#