{ "openapi": "3.1.0", "info": { "title": "Cargofollow", "version": "1.0.0-alpha", "description": "Developer-first infrastructure for electronic freight documents in the EU: eCMR, ePOD, signatures, inspection links and the eFTI dataset behind one `POST /v1/shipments`.", "contact": { "name": "Cargofollow", "url": "https://cargofollow.com", "email": "support@cargofollow.com" } }, "servers": [ { "url": "https://api.cargofollow.com", "description": "production" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "system", "description": "Health, version and the OpenAPI document." }, { "name": "shipments", "description": "Create, read, list, update, issue and cancel shipments; per-shipment events and integrity." }, { "name": "documents", "description": "PDF versions, attachments and HMAC-signed download URLs stored in R2 (eu)." }, { "name": "signatures", "description": "Signatures with roles, methods, trust levels and evidence; signature requests for the sign PWA." }, { "name": "sign", "description": "Token-scoped endpoints the sign PWA calls: context, submit, handoff." }, { "name": "remarks", "description": "Reservations at pickup or delivery, with photos stored as documents." }, { "name": "pod", "description": "The electronic proof of delivery: consignee signature, remarks, photos, time and location." }, { "name": "invoice", "description": "The e-invoice of a delivered shipment: UBL 2.1 in Peppol BIS Billing 3.0." }, { "name": "webhooks", "description": "Webhook endpoints (CRUD, secret, test ping) and deliveries (log, retry)." }, { "name": "events", "description": "Organisation-wide event feed with cursor and filters (90 days)." }, { "name": "request-logs", "description": "One summary row per API call, kept 30 days." }, { "name": "audit-log", "description": "Administrative acts of the organisation, append-only and kept two years." }, { "name": "notifications", "description": "The e-mail and SMS the organisation sent, with hashed recipients." }, { "name": "inspect", "description": "Read-only inspection endpoint behind the QR code, with view logging." }, { "name": "providers", "description": "The provider catalogue with capabilities and routing rules." }, { "name": "requirements", "description": "Country requirements for a lane: e-CMR ratification, Benelux pilot, ADR, cabotage, combined transport." }, { "name": "validate", "description": "The public validator without an API key (Turnstile, 10 requests per minute per IP, CORS)." }, { "name": "contact", "description": "The contact form of the marketing site, without an API key (Turnstile, a per-IP window, CORS)." }, { "name": "test", "description": "Sandbox helpers, only with a test key: simulate sign, deliver, remark or auto-advance." }, { "name": "tours", "description": "Several shipments as one driver's run, with the stops in driving order." }, { "name": "driver", "description": "Driver overview for the PWA: OTP on driver.phone, 12-hour session, own shipments." }, { "name": "efti", "description": "The eFTI projection: CMDS per subset, UIL, and the gate-facing platform interface." }, { "name": "export", "description": "GDPR export of organisation data as a zip of JSON and documents." }, { "name": "privacy", "description": "Erasure of the personal data of one data subject across an organisation." }, { "name": "usage", "description": "Metered usage per UTC day: shipments issued, signatures, notifications, storage." }, { "name": "billing", "description": "Inbound billing-provider webhooks; invoices and subscriptions, verified by signature." }, { "name": "auth", "description": "The better-auth mount for the console: magic link, sessions, organisations, members." }, { "name": "providers-webhook", "description": "Inbound provider webhooks, verified per provider and mapped onto shipment events." }, { "name": "ishare", "description": "iSHARE / BDI: federated access to one consignment note with delegation evidence." } ], "externalDocs": { "url": "https://cargofollow.com/docs", "description": "Guides, concepts and changelog" }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_test_… or sk_live_…", "description": "API key in the Authorization header; the prefix decides test or live mode." } }, "schemas": { "RemarkCreate": { "type": "object", "properties": { "phase": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "When the remark was made" }, "type": { "type": "string", "enum": [ "damage", "shortage", "delay", "other" ], "description": "Kind of reservation" }, "text": { "type": "string", "maxLength": 2000 }, "photo_document_ids": { "type": "array", "items": { "type": "string", "pattern": "^doc_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "document id" }, "maxItems": 5, "description": "Photos already uploaded as documents with kind `photo` on the same shipment" } }, "required": [ "phase", "type" ] }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" }, "Health": { "type": "object", "properties": { "ok": { "type": "boolean" }, "checks": { "type": "object", "properties": { "d1": { "type": "string", "enum": [ "ok", "error" ], "description": "Outcome of one binding probe" }, "kv": { "type": "string", "enum": [ "ok", "error" ], "description": "Outcome of one binding probe" }, "r2": { "type": "string", "enum": [ "ok", "error" ], "description": "Outcome of one binding probe" } }, "required": [ "d1", "kv", "r2" ] }, "environment": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "ok", "checks", "environment", "request_id" ] }, "Version": { "type": "object", "properties": { "name": { "type": "string" }, "api_version": { "type": "string" }, "schema_version": { "type": "integer" }, "environment": { "type": "string" } }, "required": [ "name", "api_version", "schema_version", "environment" ] }, "ValidationResult": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "False when at least one rule of severity `error` fired" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" }, "description": "Findings that would block the create" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" }, "description": "Findings that would ride along on the 201" }, "transport_type": { "type": "string", "enum": [ "national", "international", "cabotage", "combined" ], "description": "What the create would store, derived if omitted" } }, "required": [ "valid", "errors", "warnings", "transport_type" ] }, "ShipmentInput": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 100, "description": "Client's own reference; shown on the CMR" }, "consignor": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Sender (CMR box 1)" }, "carrier": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Carrier (CMR box 16)" }, "consignee": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Consignee (CMR box 2)" }, "principal": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Principal who ordered the transport; not on the CMR form" }, "successive_carriers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Party to the contract of carriage" }, "maxItems": 10, "description": "Successive carriers (CMR box 17)" }, "pickup": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Person on site" }, "instructions": { "type": "string", "maxLength": 2000, "description": "Instructions for the driver" } }, "required": [ "address" ], "description": "Place and date of taking over the goods (CMR box 4)" }, "delivery": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Person on site" }, "instructions": { "type": "string", "maxLength": 2000, "description": "Instructions for the driver" } }, "required": [ "address" ], "description": "Place designated for delivery (CMR box 3)" }, "goods": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Nature of the goods (CMR box 9)" }, "marks": { "type": "string", "maxLength": 200, "description": "Marks and numbers (CMR box 6)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of packages (CMR box 7)" }, "package_type": { "type": "string", "enum": [ "pallet", "box", "carton", "crate", "bag", "drum", "roll", "bundle", "container", "loose", "other" ], "description": "Method of packing (CMR box 8)" }, "gross_weight_kg": { "type": "number", "minimum": 0, "description": "Gross weight in kilograms (CMR box 11)" }, "volume_m3": { "type": "number", "minimum": 0, "description": "Volume in cubic metres (CMR box 12)" }, "hs_code": { "type": "string", "pattern": "^\\d{4,10}$", "description": "Harmonised System code (statistical number, CMR box 10)" }, "adr": { "type": "object", "properties": { "un_number": { "type": "string", "pattern": "^\\d{4}$" }, "class": { "type": "string", "maxLength": 10, "description": "ADR class, for example \"3\" or \"5.1\"" }, "packing_group": { "type": "string", "enum": [ "I", "II", "III" ], "description": "ADR packing group" }, "proper_shipping_name": { "type": "string", "maxLength": 200 }, "tunnel_code": { "type": "string", "maxLength": 10, "description": "Tunnel restriction code, for example \"(D/E)\"" }, "limited_quantity": { "type": "boolean" }, "environmentally_hazardous": { "type": "boolean" } }, "description": "Dangerous goods declaration under ADR" } }, "required": [ "description", "quantity", "package_type" ], "description": "One line of goods" }, "maxItems": 200, "description": "Goods lines; a business rule requires at least one" }, "vehicle": { "type": "object", "properties": { "plate": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Registration plate of the tractor or truck" }, "trailer_plate": { "type": "string", "maxLength": 20 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of registration" }, "equipment_category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the load unit named in trailer_plate" } }, "required": [ "plate" ], "description": "Truck and trailer performing the transport" }, "combined_transport": { "type": "object", "properties": { "sequence": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Position of this road leg in the combined transport chain, starting at 1" }, "carried_unit": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Container, swap body or trailer number of the carried unit" }, "category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the carried unit" } }, "description": "Intermodal unit carried on the load unit of this road leg" } }, "description": "Place of this road leg in a combined transport operation (EU2)" }, "driver": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "description": "Used for SMS sign requests and the driver overview" }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of the signing flow and documents" } }, "required": [ "name" ], "description": "Driver who receives the sign links" }, "charges": { "type": "object", "properties": { "carriage": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Carriage charges (CMR box 19)" }, "cash_on_delivery": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Cash on delivery (CMR box 15)" }, "payer": { "type": "string", "enum": [ "consignor", "consignee", "principal" ], "description": "Who pays the carriage" } }, "description": "Carriage charges and who pays them (CMR box 20)" }, "special_agreements": { "type": "string", "maxLength": 2000, "description": "Special agreements (CMR box 19)" }, "sender_instructions": { "type": "string", "maxLength": 2000, "description": "Sender's instructions (CMR box 13)" }, "documents_attached": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20, "description": "Documents attached (CMR box 5)" }, "waste": { "type": "object", "properties": { "notification_number": { "type": "string", "pattern": "^[A-Za-z0-9]{12,13}$", "description": "Notification number; absent for a shipment under the Annex VII procedure" }, "document_number": { "type": "string", "pattern": "^(?:[A-Za-z0-9]{12,13}\\.\\d{6}|GLW\\.[A-Za-z0-9]{12})$", "description": "Movement document or Annex VII document number the carrier confirms against" }, "ewc_code": { "type": "string", "pattern": "^\\d{2} ?\\d{2} ?\\d{2}\\*?$", "description": "What is being carried, as a List of Waste code" } }, "required": [ "ewc_code" ], "description": "Waste shipment details; present turns the consignment into a DIWASS case (schema version 2)" }, "transport_type": { "type": "string", "enum": [ "national", "international", "cabotage", "combined" ], "description": "Kind of transport; derived from the countries when omitted" }, "provider": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "Overrides the organisation default and routing rules" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Free-form key/value pairs of the client" } }, "required": [ "consignor", "carrier", "consignee", "pickup", "delivery", "goods" ], "description": "Shipment as a client creates it" }, "Shipment": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 100, "description": "Client's own reference; shown on the CMR" }, "consignor": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Sender (CMR box 1)" }, "carrier": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Carrier (CMR box 16)" }, "consignee": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Consignee (CMR box 2)" }, "principal": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Principal who ordered the transport; not on the CMR form" }, "successive_carriers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Party to the contract of carriage" }, "maxItems": 10, "description": "Successive carriers (CMR box 17)" }, "pickup": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Person on site" }, "instructions": { "type": "string", "maxLength": 2000, "description": "Instructions for the driver" } }, "required": [ "address" ], "description": "Place and date of taking over the goods (CMR box 4)" }, "delivery": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Person on site" }, "instructions": { "type": "string", "maxLength": 2000, "description": "Instructions for the driver" } }, "required": [ "address" ], "description": "Place designated for delivery (CMR box 3)" }, "goods": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Nature of the goods (CMR box 9)" }, "marks": { "type": "string", "maxLength": 200, "description": "Marks and numbers (CMR box 6)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of packages (CMR box 7)" }, "package_type": { "type": "string", "enum": [ "pallet", "box", "carton", "crate", "bag", "drum", "roll", "bundle", "container", "loose", "other" ], "description": "Method of packing (CMR box 8)" }, "gross_weight_kg": { "type": "number", "minimum": 0, "description": "Gross weight in kilograms (CMR box 11)" }, "volume_m3": { "type": "number", "minimum": 0, "description": "Volume in cubic metres (CMR box 12)" }, "hs_code": { "type": "string", "pattern": "^\\d{4,10}$", "description": "Harmonised System code (statistical number, CMR box 10)" }, "adr": { "type": "object", "properties": { "un_number": { "type": "string", "pattern": "^\\d{4}$" }, "class": { "type": "string", "maxLength": 10, "description": "ADR class, for example \"3\" or \"5.1\"" }, "packing_group": { "type": "string", "enum": [ "I", "II", "III" ], "description": "ADR packing group" }, "proper_shipping_name": { "type": "string", "maxLength": 200 }, "tunnel_code": { "type": "string", "maxLength": 10, "description": "Tunnel restriction code, for example \"(D/E)\"" }, "limited_quantity": { "type": "boolean" }, "environmentally_hazardous": { "type": "boolean" } }, "description": "Dangerous goods declaration under ADR" } }, "required": [ "description", "quantity", "package_type" ], "description": "One line of goods" }, "maxItems": 200, "description": "Goods lines; a business rule requires at least one" }, "vehicle": { "type": "object", "properties": { "plate": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Registration plate of the tractor or truck" }, "trailer_plate": { "type": "string", "maxLength": 20 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of registration" }, "equipment_category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the load unit named in trailer_plate" } }, "required": [ "plate" ], "description": "Truck and trailer performing the transport" }, "combined_transport": { "type": "object", "properties": { "sequence": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Position of this road leg in the combined transport chain, starting at 1" }, "carried_unit": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Container, swap body or trailer number of the carried unit" }, "category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the carried unit" } }, "description": "Intermodal unit carried on the load unit of this road leg" } }, "description": "Place of this road leg in a combined transport operation (EU2)" }, "driver": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "description": "Used for SMS sign requests and the driver overview" }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of the signing flow and documents" } }, "required": [ "name" ], "description": "Driver who receives the sign links" }, "charges": { "type": "object", "properties": { "carriage": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Carriage charges (CMR box 19)" }, "cash_on_delivery": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Cash on delivery (CMR box 15)" }, "payer": { "type": "string", "enum": [ "consignor", "consignee", "principal" ], "description": "Who pays the carriage" } }, "description": "Carriage charges and who pays them (CMR box 20)" }, "special_agreements": { "type": "string", "maxLength": 2000, "description": "Special agreements (CMR box 19)" }, "sender_instructions": { "type": "string", "maxLength": 2000, "description": "Sender's instructions (CMR box 13)" }, "documents_attached": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20, "description": "Documents attached (CMR box 5)" }, "waste": { "type": "object", "properties": { "notification_number": { "type": "string", "pattern": "^[A-Za-z0-9]{12,13}$", "description": "Notification number; absent for a shipment under the Annex VII procedure" }, "document_number": { "type": "string", "pattern": "^(?:[A-Za-z0-9]{12,13}\\.\\d{6}|GLW\\.[A-Za-z0-9]{12})$", "description": "Movement document or Annex VII document number the carrier confirms against" }, "ewc_code": { "type": "string", "pattern": "^\\d{2} ?\\d{2} ?\\d{2}\\*?$", "description": "What is being carried, as a List of Waste code" } }, "required": [ "ewc_code" ], "description": "Waste shipment details; present turns the consignment into a DIWASS case (schema version 2)" }, "transport_type": { "type": "string", "enum": [ "national", "international", "cabotage", "combined" ], "description": "Kind of transport; derived from the countries when not given, cabotage and combined only on explicit input" }, "provider": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "eCMR provider that executes the consignment" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Free-form key/value pairs of the client" }, "id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "mode": { "type": "string", "enum": [ "test", "live" ], "description": "Data mode; follows from the API key" }, "status": { "type": "string", "enum": [ "draft", "issued", "in_transit", "delivered", "completed", "cancelled" ], "description": "Lifecycle status" }, "version": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of the current version, starting at 1" }, "current_version_id": { "type": "string", "pattern": "^ver_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment version id" }, "schema_version": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] } ], "description": "Version of the canonical model this stored snapshot was written with" }, "ecmr_number": { "type": "string", "pattern": "^([A-Z0-9]{2,16})-(\\d{4})-(\\d{6,9})$", "description": "Consecutive consignment note number, assigned at issue" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "issued_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "delivered_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "cancelled_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "cancel_reason": { "type": "string", "maxLength": 500 }, "current_version": { "$ref": "#/components/schemas/ShipmentVersionRef" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" }, "description": "Business-rule findings that do not block, from the last validation" }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri", "description": "This shipment" }, "events": { "type": "string", "format": "uri", "description": "Event feed of this shipment (M1-05)" }, "documents": { "type": "string", "format": "uri", "description": "Documents of this shipment (M1-06)" } }, "required": [ "self", "events", "documents" ], "description": "Absolute URLs of the related resources" } }, "required": [ "consignor", "carrier", "consignee", "pickup", "delivery", "goods", "transport_type", "provider", "id", "mode", "status", "version", "current_version_id", "schema_version", "created_at", "updated_at", "current_version", "warnings", "links" ] }, "ShipmentVersionRef": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ver_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment version id" }, "version": { "type": "integer", "exclusiveMinimum": 0, "description": "Sequence number within the shipment, starting at 1" }, "schema_version": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] } ], "description": "Version of the canonical model this stored snapshot was written with" }, "document_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the frozen subset of the snapshot" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" } }, "required": [ "id", "version", "schema_version", "document_hash", "created_at" ], "description": "Current version of the shipment" }, "ShipmentCreateRequest": { "anyOf": [ { "$ref": "#/components/schemas/ShipmentCreate" }, { "$ref": "#/components/schemas/ShipmentImport" } ] }, "ShipmentCreate": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 100, "description": "Client's own reference; shown on the CMR" }, "consignor": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Sender (CMR box 1)" }, "carrier": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Carrier (CMR box 16)" }, "consignee": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Consignee (CMR box 2)" }, "principal": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Principal who ordered the transport; not on the CMR form" }, "successive_carriers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Party to the contract of carriage" }, "maxItems": 10, "description": "Successive carriers (CMR box 17)" }, "pickup": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Person on site" }, "instructions": { "type": "string", "maxLength": 2000, "description": "Instructions for the driver" } }, "required": [ "address" ], "description": "Place and date of taking over the goods (CMR box 4)" }, "delivery": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Person on site" }, "instructions": { "type": "string", "maxLength": 2000, "description": "Instructions for the driver" } }, "required": [ "address" ], "description": "Place designated for delivery (CMR box 3)" }, "goods": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Nature of the goods (CMR box 9)" }, "marks": { "type": "string", "maxLength": 200, "description": "Marks and numbers (CMR box 6)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of packages (CMR box 7)" }, "package_type": { "type": "string", "enum": [ "pallet", "box", "carton", "crate", "bag", "drum", "roll", "bundle", "container", "loose", "other" ], "description": "Method of packing (CMR box 8)" }, "gross_weight_kg": { "type": "number", "minimum": 0, "description": "Gross weight in kilograms (CMR box 11)" }, "volume_m3": { "type": "number", "minimum": 0, "description": "Volume in cubic metres (CMR box 12)" }, "hs_code": { "type": "string", "pattern": "^\\d{4,10}$", "description": "Harmonised System code (statistical number, CMR box 10)" }, "adr": { "type": "object", "properties": { "un_number": { "type": "string", "pattern": "^\\d{4}$" }, "class": { "type": "string", "maxLength": 10, "description": "ADR class, for example \"3\" or \"5.1\"" }, "packing_group": { "type": "string", "enum": [ "I", "II", "III" ], "description": "ADR packing group" }, "proper_shipping_name": { "type": "string", "maxLength": 200 }, "tunnel_code": { "type": "string", "maxLength": 10, "description": "Tunnel restriction code, for example \"(D/E)\"" }, "limited_quantity": { "type": "boolean" }, "environmentally_hazardous": { "type": "boolean" } }, "description": "Dangerous goods declaration under ADR" } }, "required": [ "description", "quantity", "package_type" ], "description": "One line of goods" }, "maxItems": 200, "description": "Goods lines; a business rule requires at least one" }, "vehicle": { "type": "object", "properties": { "plate": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Registration plate of the tractor or truck" }, "trailer_plate": { "type": "string", "maxLength": 20 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of registration" }, "equipment_category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the load unit named in trailer_plate" } }, "required": [ "plate" ], "description": "Truck and trailer performing the transport" }, "combined_transport": { "type": "object", "properties": { "sequence": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Position of this road leg in the combined transport chain, starting at 1" }, "carried_unit": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Container, swap body or trailer number of the carried unit" }, "category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the carried unit" } }, "description": "Intermodal unit carried on the load unit of this road leg" } }, "description": "Place of this road leg in a combined transport operation (EU2)" }, "driver": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "description": "Used for SMS sign requests and the driver overview" }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of the signing flow and documents" } }, "required": [ "name" ], "description": "Driver who receives the sign links" }, "charges": { "type": "object", "properties": { "carriage": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Carriage charges (CMR box 19)" }, "cash_on_delivery": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Cash on delivery (CMR box 15)" }, "payer": { "type": "string", "enum": [ "consignor", "consignee", "principal" ], "description": "Who pays the carriage" } }, "description": "Carriage charges and who pays them (CMR box 20)" }, "special_agreements": { "type": "string", "maxLength": 2000, "description": "Special agreements (CMR box 19)" }, "sender_instructions": { "type": "string", "maxLength": 2000, "description": "Sender's instructions (CMR box 13)" }, "documents_attached": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20, "description": "Documents attached (CMR box 5)" }, "waste": { "type": "object", "properties": { "notification_number": { "type": "string", "pattern": "^[A-Za-z0-9]{12,13}$", "description": "Notification number; absent for a shipment under the Annex VII procedure" }, "document_number": { "type": "string", "pattern": "^(?:[A-Za-z0-9]{12,13}\\.\\d{6}|GLW\\.[A-Za-z0-9]{12})$", "description": "Movement document or Annex VII document number the carrier confirms against" }, "ewc_code": { "type": "string", "pattern": "^\\d{2} ?\\d{2} ?\\d{2}\\*?$", "description": "What is being carried, as a List of Waste code" } }, "required": [ "ewc_code" ], "description": "Waste shipment details; present turns the consignment into a DIWASS case (schema version 2)" }, "transport_type": { "type": "string", "enum": [ "national", "international", "cabotage", "combined" ], "description": "Kind of transport; derived from the countries when omitted" }, "provider": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "Overrides the organisation default and routing rules" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Free-form key/value pairs of the client" }, "issue": { "type": "boolean", "description": "Issue the consignment note right after creating it, in one call" } }, "required": [ "consignor", "carrier", "consignee", "pickup", "delivery", "goods" ] }, "ShipmentImport": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "olf" ], "description": "Format of the document in `import`" }, "import": { "type": "object", "properties": {}, "additionalProperties": {}, "description": "The eCMR document itself; for `olf` an OLF sealed document or a bare `EcmrModel`" }, "issue": { "type": "boolean", "description": "Issue the consignment note right after creating it, in one call" } }, "required": [ "format", "import" ] }, "ShipmentList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shipment" }, "description": "Newest first" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page; null on the last page" } }, "required": [ "data", "next_cursor" ] }, "ShipmentPatch": { "type": "object", "properties": { "reference": { "type": [ "string", "null" ], "maxLength": 100, "description": "Client's own reference; shown on the CMR" }, "consignor": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Sender (CMR box 1)" }, "carrier": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Carrier (CMR box 16)" }, "consignee": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Consignee (CMR box 2)" }, "principal": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Principal who ordered the transport; not on the CMR form" }, "successive_carriers": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Party to the contract of carriage" }, "maxItems": 10, "description": "Successive carriers (CMR box 17)" }, "pickup": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Person on site" }, "instructions": { "type": "string", "maxLength": 2000, "description": "Instructions for the driver" } }, "required": [ "address" ], "description": "Place and date of taking over the goods (CMR box 4)" }, "delivery": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Person on site" }, "instructions": { "type": "string", "maxLength": 2000, "description": "Instructions for the driver" } }, "required": [ "address" ], "description": "Place designated for delivery (CMR box 3)" }, "goods": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Nature of the goods (CMR box 9)" }, "marks": { "type": "string", "maxLength": 200, "description": "Marks and numbers (CMR box 6)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of packages (CMR box 7)" }, "package_type": { "type": "string", "enum": [ "pallet", "box", "carton", "crate", "bag", "drum", "roll", "bundle", "container", "loose", "other" ], "description": "Method of packing (CMR box 8)" }, "gross_weight_kg": { "type": "number", "minimum": 0, "description": "Gross weight in kilograms (CMR box 11)" }, "volume_m3": { "type": "number", "minimum": 0, "description": "Volume in cubic metres (CMR box 12)" }, "hs_code": { "type": "string", "pattern": "^\\d{4,10}$", "description": "Harmonised System code (statistical number, CMR box 10)" }, "adr": { "type": "object", "properties": { "un_number": { "type": "string", "pattern": "^\\d{4}$" }, "class": { "type": "string", "maxLength": 10, "description": "ADR class, for example \"3\" or \"5.1\"" }, "packing_group": { "type": "string", "enum": [ "I", "II", "III" ], "description": "ADR packing group" }, "proper_shipping_name": { "type": "string", "maxLength": 200 }, "tunnel_code": { "type": "string", "maxLength": 10, "description": "Tunnel restriction code, for example \"(D/E)\"" }, "limited_quantity": { "type": "boolean" }, "environmentally_hazardous": { "type": "boolean" } }, "description": "Dangerous goods declaration under ADR" } }, "required": [ "description", "quantity", "package_type" ], "description": "One line of goods" }, "maxItems": 200, "description": "Goods lines; a business rule requires at least one" }, "vehicle": { "type": [ "object", "null" ], "properties": { "plate": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Registration plate of the tractor or truck" }, "trailer_plate": { "type": "string", "maxLength": 20 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of registration" }, "equipment_category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the load unit named in trailer_plate" } }, "required": [ "plate" ], "description": "Truck and trailer performing the transport" }, "combined_transport": { "type": [ "object", "null" ], "properties": { "sequence": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Position of this road leg in the combined transport chain, starting at 1" }, "carried_unit": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Container, swap body or trailer number of the carried unit" }, "category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the carried unit" } }, "description": "Intermodal unit carried on the load unit of this road leg" } }, "description": "Place of this road leg in a combined transport operation (EU2)" }, "driver": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "description": "Used for SMS sign requests and the driver overview" }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of the signing flow and documents" } }, "required": [ "name" ], "description": "Driver who receives the sign links" }, "charges": { "type": [ "object", "null" ], "properties": { "carriage": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Carriage charges (CMR box 19)" }, "cash_on_delivery": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Cash on delivery (CMR box 15)" }, "payer": { "type": "string", "enum": [ "consignor", "consignee", "principal" ], "description": "Who pays the carriage" } }, "description": "Carriage charges and who pays them (CMR box 20)" }, "special_agreements": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Special agreements (CMR box 19)" }, "sender_instructions": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Sender's instructions (CMR box 13)" }, "documents_attached": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 200 }, "maxItems": 20, "description": "Documents attached (CMR box 5)" }, "waste": { "type": [ "object", "null" ], "properties": { "notification_number": { "type": "string", "pattern": "^[A-Za-z0-9]{12,13}$", "description": "Notification number; absent for a shipment under the Annex VII procedure" }, "document_number": { "type": "string", "pattern": "^(?:[A-Za-z0-9]{12,13}\\.\\d{6}|GLW\\.[A-Za-z0-9]{12})$", "description": "Movement document or Annex VII document number the carrier confirms against" }, "ewc_code": { "type": "string", "pattern": "^\\d{2} ?\\d{2} ?\\d{2}\\*?$", "description": "What is being carried, as a List of Waste code" } }, "required": [ "ewc_code" ], "description": "Waste shipment details; present turns the consignment into a DIWASS case (schema version 2)" }, "transport_type": { "type": "string", "enum": [ "national", "international", "cabotage", "combined" ], "description": "Kind of transport; derived from the countries when omitted" }, "provider": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "Overrides the organisation default and routing rules" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Free-form key/value pairs of the client" } }, "description": "Partial update of a shipment; nested objects are replaced as a whole, null clears an optional field" }, "ShipmentCancel": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the shipment is cancelled; stored as `cancel_reason` and in the event" } }, "required": [ "reason" ] }, "ShipmentEventList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentEvent" }, "description": "In chain order: `seq` ascending" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page; null on the last page" } }, "required": [ "data", "next_cursor" ] }, "ShipmentEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment event id" }, "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "seq": { "type": "integer", "exclusiveMinimum": 0 }, "type": { "type": "string", "enum": [ "shipment.created", "shipment.issued", "shipment.updated", "shipment.cancelled", "shipment.pickup_signed", "shipment.delivered", "shipment.completed", "signature.completed", "document.created", "remark.added", "inspection.viewed", "provider.sync_failed", "efti.uil_issued", "efti.authority_access", "efti.combined_transport_stamped" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "actor": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "api_key", "user", "signer", "provider", "system", "public", "authority" ] }, "id": { "type": "string", "maxLength": 100, "description": "Key id, user id, request token id or provider name" }, "label": { "type": "string", "maxLength": 200, "description": "Human-readable name for the timeline" } }, "required": [ "type" ], "description": "Actor that caused the event" }, "payload": { "type": "object", "additionalProperties": {} }, "prev_hash": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest, lower-case hex" } ] }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest, lower-case hex" } }, "required": [ "id", "shipment_id", "seq", "type", "occurred_at", "actor", "payload", "prev_hash", "hash" ], "description": "Shipment event" }, "IntegrityReport": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True when every link verifies and no `seq` is missing" }, "events": { "type": "integer", "minimum": 0, "description": "Number of stored events" }, "head_hash": { "type": "string", "description": "`hash` of the last event, the value to pin; the empty string when there is none" }, "broken_at": { "type": "integer", "exclusiveMinimum": 0, "description": "`seq` of the first event whose `prev_hash` or `hash` does not verify" }, "seq_gaps": { "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0 }, "description": "Missing `seq` values between 1 and the highest stored one" }, "verified_at": { "type": "string", "format": "date-time", "description": "When this verification ran" } }, "required": [ "ok", "events", "head_hash", "seq_gaps", "verified_at" ] }, "InspectionLink": { "type": "object", "properties": { "token_id": { "type": "string", "pattern": "^ins_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "inspection token id" }, "url": { "type": "string", "format": "uri", "description": "The page behind the QR code: `SIGN_BASE_URL/i/`" }, "expires_at": { "type": "string", "format": "date-time", "description": "A year after creation, or 90 days after delivery when that is earlier" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "rotated_from": { "type": "string", "pattern": "^ins_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The token this one replaced" }, "qr_svg": { "type": "string", "description": "The QR code of `url` as an SVG document" }, "qr_png_url": { "type": "string", "format": "uri", "description": "The same QR code as PNG, behind the API key" }, "qr_svg_url": { "type": "string", "format": "uri" }, "view_count": { "type": "integer", "minimum": 0 }, "last_viewed_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" } }, "required": [ "token_id", "url", "expires_at", "created_at", "qr_svg", "qr_png_url", "qr_svg_url", "view_count" ] }, "ProviderLink": { "type": "object", "properties": { "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "provider": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "eCMR provider that executes the consignment" }, "external_id": { "type": [ "string", "null" ], "description": "The consignment's id at the provider" }, "mapping_version": { "type": "integer", "exclusiveMinimum": 0 }, "sync_status": { "type": "string", "enum": [ "pending", "synced", "failed", "cancelled" ], "description": "State of the link between a shipment and its provider" }, "last_operation": { "type": [ "string", "null" ], "enum": [ "create", "update", "cancel", "status", "document", null ], "description": "ProviderAdapter operation" }, "last_error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "description": "Stable adapter error code, see packages/providers" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "description": "Why a provider call failed" }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "last_trace": { "type": [ "object", "null" ], "properties": { "step": { "type": "string", "enum": [ "normalize", "validate", "select", "publish", "status" ], "description": "Step of the provider-sync workflow" }, "provider": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "eCMR provider that executes the consignment" }, "operation": { "type": "string", "enum": [ "create", "update", "cancel", "status", "document" ], "description": "ProviderAdapter operation" }, "outcome": { "type": "string", "enum": [ "ok", "skipped", "failed" ], "description": "How the step ended" }, "attempt": { "type": "integer", "exclusiveMinimum": 0, "description": "Attempts the step needed" }, "external_id": { "type": "string" }, "sync_status": { "type": "string", "enum": [ "pending", "synced", "failed", "cancelled" ], "description": "State of the link between a shipment and its provider" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable adapter error code, see packages/providers" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "description": "Why a provider call failed" }, "detail": { "type": "string", "description": "Why the step was skipped or what it decided" }, "instance_id": { "type": "string", "description": "Workflow instance that wrote the trace" }, "event_id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment event id" }, "occurred_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" } }, "required": [ "step", "provider", "operation", "outcome", "instance_id", "event_id", "occurred_at" ], "description": "The last step the provider-sync workflow recorded" }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "retry": { "type": "string" }, "shipment": { "type": "string" } }, "required": [ "self", "retry", "shipment" ] } }, "required": [ "shipment_id", "provider", "external_id", "mapping_version", "sync_status", "last_operation", "last_error", "last_synced_at", "created_at", "updated_at", "last_trace", "links" ] }, "ProviderSyncRetry": { "type": "object", "properties": { "instance_id": { "type": [ "string", "null" ], "description": "Workflow instance that was started; null when the binding is unavailable" }, "operation": { "type": "string", "enum": [ "create", "update", "cancel" ], "description": "Operation the provider-sync workflow performs" }, "link": { "$ref": "#/components/schemas/ProviderLink" } }, "required": [ "instance_id", "operation", "link" ] }, "Document": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "document id" }, "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "kind": { "type": "string", "enum": [ "ecmr_pdf", "pod_pdf", "attachment", "signature_image", "photo", "other" ], "description": "What the file is" }, "version_id": { "type": "string", "pattern": "^ver_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Shipment version a rendered PDF belongs to" }, "filename": { "type": "string", "maxLength": 255 }, "mime": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png", "image/webp", "application/json" ], "description": "Mime type" }, "size": { "type": "integer", "minimum": 0, "description": "Size in bytes" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the file content" }, "locale": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of a rendered document" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "download_url": { "type": "string", "format": "uri", "description": "Signed URL for the file itself; valid for five minutes from this response" } }, "required": [ "id", "shipment_id", "kind", "mime", "size", "sha256", "created_at", "download_url" ] }, "DocumentList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Always null: a shipment carries few documents, so the list is complete" } }, "required": [ "data", "next_cursor" ] }, "Signature": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sig_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "signature id" }, "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "version_id": { "type": "string", "pattern": "^ver_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Version whose frozen content was signed" }, "role": { "type": "string", "enum": [ "consignor", "carrier", "consignee" ], "description": "Who signs: CMR boxes 22, 23 and 24" }, "method": { "type": "string", "enum": [ "drawn", "click_otp", "api", "photo_of_paper" ], "description": "How the signature was given (ADR 0004)" }, "trust_level": { "type": "string", "enum": [ "platform_auth", "ades", "qes" ], "description": "Trust level of the signature; platform_auth is the default, ades and qes need a QTSP" }, "kind": { "type": "string", "enum": [ "signature", "seal" ], "description": "A natural person signs; a legal person seals (OLF semantics)" }, "signer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "company": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" } }, "required": [ "name" ], "description": "The person who signed" }, "evidence": { "type": "object", "properties": { "signed_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "ip": { "type": "string", "maxLength": 45 }, "user_agent": { "type": "string", "maxLength": 500 }, "geo": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 }, "accuracy_m": { "type": "number", "minimum": 0 } }, "required": [ "lat", "lng" ] }, "otp_channel": { "type": "string", "enum": [ "email", "sms" ] }, "device": { "type": "string", "enum": [ "own", "driver", "api" ], "description": "Signed on an own device, on the driver device, or via the API" }, "token_id": { "type": "string", "pattern": "^sgr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Signature request that was used" }, "locale": { "type": "string", "pattern": "^[a-z]{2}$", "description": "ISO 639-1 language code, lower case" }, "auth_context": { "type": "string", "maxLength": 500, "description": "How the calling system authenticated the signer (method `api`)" }, "simulated": { "type": "boolean", "enum": [ true ], "description": "The signature was produced by a sandbox simulation, never by a real signer" } }, "required": [ "signed_at", "device" ], "description": "Evidence recorded with a signature" }, "document_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "document_hash of the signed version" }, "image_document_id": { "type": "string", "pattern": "^doc_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "PNG of a drawn or photographed signature" }, "certificate_ref": { "type": "string", "maxLength": 200, "description": "Certificate reference for seals, ades and qes" }, "sealed_by": { "type": "string", "maxLength": 200, "description": "Legal person that sealed" }, "qtsp": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Which QTSP signed, as the register names it" }, "format": { "type": "string", "enum": [ "CAdES-B-B" ], "description": "ETSI EN 319 122-1 baseline, without a timestamp" }, "level": { "type": "string", "enum": [ "ades", "qes" ] }, "certificate_ref": { "type": "string", "maxLength": 400, "description": "Issuer distinguished name and serial" }, "signed_at": { "type": "string", "format": "date-time", "description": "The signing time in the signed attributes" }, "digest_algorithm": { "type": "string", "enum": [ "sha256" ] }, "signature_algorithm": { "type": "string", "minLength": 1, "maxLength": 60 }, "identification_reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The identification at the QTSP that authorised this signature" } }, "required": [ "provider", "format", "level", "certificate_ref", "signed_at", "digest_algorithm", "signature_algorithm", "identification_reference" ], "description": "Present when a QTSP produced the `ades` or `qes` signature (M5-02)" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "verified": { "type": "boolean", "description": "True while `document_hash` equals the document hash of the current version of the shipment: the frozen content has not changed since the signature" }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri", "description": "This signature" }, "shipment": { "type": "string", "format": "uri", "description": "The signed shipment" } }, "required": [ "self", "shipment" ], "description": "Absolute URLs of the related resources" } }, "required": [ "id", "shipment_id", "version_id", "role", "method", "trust_level", "kind", "signer", "evidence", "document_hash", "created_at", "verified", "links" ] }, "SignatureCreate": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "consignor", "carrier", "consignee" ], "description": "Who signs: CMR boxes 22, 23 and 24" }, "method": { "type": "string", "enum": [ "api", "photo_of_paper" ], "description": "`api`: the calling system authenticated the signer; `photo_of_paper`: a photo of the signed paper, uploaded first as a document of this shipment" }, "trust_level": { "type": "string", "enum": [ "platform_auth", "ades", "qes" ], "default": "platform_auth", "description": "Trust level of the signature; platform_auth is the default, ades and qes need a QTSP" }, "kind": { "type": "string", "enum": [ "signature", "seal" ], "default": "signature", "description": "A natural person signs; a legal person seals (OLF semantics)" }, "signer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "company": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" } }, "required": [ "name" ], "description": "The person who signed" }, "evidence": { "type": "object", "properties": { "signed_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "ip": { "type": "string", "maxLength": 45 }, "user_agent": { "type": "string", "maxLength": 500 }, "geo": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 }, "accuracy_m": { "type": "number", "minimum": 0 } }, "required": [ "lat", "lng" ] }, "device": { "type": "string", "enum": [ "own", "driver", "api" ], "description": "Signed on an own device, on the driver device, or via the API" }, "locale": { "type": "string", "pattern": "^[a-z]{2}$", "description": "ISO 639-1 language code, lower case" }, "auth_context": { "type": "string", "maxLength": 500, "description": "How the calling system authenticated the signer (method `api`)" }, "simulated": { "type": "boolean", "enum": [ true ], "description": "The signature was produced by a sandbox simulation, never by a real signer" } }, "required": [ "signed_at", "device" ] }, "image_document_id": { "type": "string", "pattern": "^doc_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The uploaded photo (method `photo_of_paper`); a document of this shipment" }, "certificate_ref": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Certificate reference; required for a seal and for `ades` and `qes`" }, "sealed_by": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The legal person that sealed; required for a seal" } }, "required": [ "role", "method", "signer", "evidence" ] }, "SignatureList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signature" }, "description": "In signing order" } }, "required": [ "data" ] }, "SignatureVerification": { "type": "object", "properties": { "signature_id": { "type": "string", "pattern": "^sig_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "signature id" }, "trust_level": { "type": "string", "enum": [ "platform_auth", "ades", "qes" ], "description": "Trust level of the signature; platform_auth is the default, ades and qes need a QTSP" }, "format": { "type": "string", "enum": [ "CAdES-B-B" ] }, "signature_intact": { "type": "boolean", "description": "The CMS parses and the signature value checks out over its signed attributes" }, "digest_matches": { "type": "boolean", "description": "The signed `message-digest` equals the `document_hash` this signature bound" }, "document_current": { "type": "boolean", "description": "The hash that was signed is still the document hash of the current version, so the frozen content has not been rewritten since" }, "chain_complete": { "type": "boolean", "description": "The signer certificate was issued by the CA the envelope carries with it" }, "signed_at": { "type": "string", "format": "date-time", "description": "From the signed attributes" }, "certificate": { "$ref": "#/components/schemas/QtspCertificate" }, "trusted_list": { "type": "object", "properties": { "checked": { "type": "boolean", "enum": [ false ] }, "reason": { "type": "string" } }, "required": [ "checked", "reason" ], "description": "Whether the issuing CA was looked up on an EU trusted list; never, and why" }, "problems": { "type": "array", "items": { "type": "string" }, "description": "Everything that failed, in the order it was found" }, "cms": { "type": "string", "description": "The detached CMS SignedData, DER in base64. Feed it to an external validator together with the 32 raw bytes of `document_hash` as the detached content." }, "certificate_der": { "type": "string", "description": "The signer certificate, DER in base64" } }, "required": [ "signature_id", "trust_level", "format", "signature_intact", "digest_matches", "document_current", "chain_complete", "certificate", "trusted_list", "problems", "cms", "certificate_der" ] }, "QtspCertificate": { "type": "object", "properties": { "subject": { "type": "string" }, "issuer": { "type": "string" }, "serial": { "type": "string", "description": "Lower-case hex" }, "not_before": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "not_after": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "qualified": { "type": "boolean", "description": "The certificate carries the ETSI EN 319 412-5 QcCompliance statement" }, "sha256": { "type": "string", "description": "sha256 of the DER certificate, lower-case hex" } }, "required": [ "subject", "issuer", "serial", "not_before", "not_after", "qualified", "sha256" ] }, "SignatureRequestCreated": { "allOf": [ { "$ref": "#/components/schemas/SignatureRequest" }, { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The page the signer opens: `SIGN_BASE_URL/s/`. Only this response carries it, because the URL contains the token." }, "token": { "type": "string", "description": "The raw token, 32 random bytes in base64url. Only this response carries it; the database stores its sha256." } }, "required": [ "url", "token" ] } ] }, "SignatureRequest": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sgr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "signature request id" }, "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "role": { "type": "string", "enum": [ "consignor", "carrier", "consignee" ], "description": "Who signs: CMR boxes 22, 23 and 24" }, "channel": { "type": "string", "enum": [ "link", "email", "sms", "qr" ], "description": "How a signature request reaches the signer" }, "status": { "type": "string", "enum": [ "pending", "used", "expired", "revoked" ], "description": "`pending` until it is submitted, its `expires_at` passes or it is withdrawn with `POST /v1/signature-requests/:id/revoke`" }, "trust_level": { "type": "string", "enum": [ "platform_auth", "ades", "qes" ], "description": "The level the sign page has to reach" }, "recipient": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "expires_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "sent_at": { "type": "string", "format": "date-time", "description": "When the e-mail or SMS went out" }, "used_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "revoked_at": { "type": "string", "format": "date-time", "description": "When the link was withdrawn; the sign page answers 410 `token_revoked` from then on" }, "signature_id": { "type": "string", "pattern": "^sig_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The signature the link produced" } }, "required": [ "id", "shipment_id", "role", "channel", "status", "trust_level", "expires_at", "created_at" ] }, "SignatureRequestCreate": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "consignor", "carrier", "consignee" ], "description": "Who signs: CMR boxes 22, 23 and 24" }, "channel": { "type": "string", "enum": [ "link", "email", "sms", "qr" ], "default": "link", "description": "`link` and `qr` only return the URL; `email` and `sms` also send the link to `recipient` and log the attempt in `GET /v1/notifications`" }, "recipient": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "required": [ "name" ], "description": "Who signs; `email` needs an address and `sms` a phone number" }, "expires_in": { "type": "integer", "minimum": 3600, "maximum": 2592000, "description": "Lifetime in seconds; 604800 when omitted" }, "locale": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of the notification and of the sign page" }, "trust_level": { "type": "string", "enum": [ "platform_auth", "ades", "qes" ], "default": "platform_auth", "description": "What this signature has to be worth (M5-02). `platform_auth` is the default and needs nothing of the signer beyond the link; `ades` and `qes` add a step to the sign page — the signer identifies themselves at the trust service provider, which then signs the `document_hash`. `GET /v1/requirements` recommends a level per corridor." } }, "required": [ "role" ] }, "SignatureRequestList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SignatureRequest" }, "description": "In creation order" } }, "required": [ "data" ] }, "SignContext": { "type": "object", "properties": { "token_id": { "type": "string", "pattern": "^sgr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "signature request id" }, "role": { "type": "string", "enum": [ "consignor", "carrier", "consignee" ], "description": "The role this link may sign, and nothing else" }, "status": { "type": "string", "enum": [ "pending", "used", "expired" ] }, "allowed_methods": { "type": "array", "items": { "type": "string", "enum": [ "drawn", "click_otp" ] } }, "otp_channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "sms" ] }, "description": "The channels this link can send a one-time password to, best first — empty when the link names no reachable recipient, in which case `click_otp` has nowhere to send a code and only `drawn` is left. The addresses themselves stay behind the API; a challenge answers them masked." }, "locale": { "type": "string", "description": "From `?locale=`, `Accept-Language` or the recipient" }, "expires_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "recipient_name": { "type": "string" }, "shipment": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 100, "description": "Client's own reference; shown on the CMR" }, "consignor": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Sender (CMR box 1)" }, "carrier": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Carrier (CMR box 16)" }, "consignee": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Consignee (CMR box 2)" }, "principal": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Principal who ordered the transport; not on the CMR form" }, "successive_carriers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Party to the contract of carriage" }, "maxItems": 10, "description": "Successive carriers (CMR box 17)" }, "pickup": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Person on site" }, "instructions": { "type": "string", "maxLength": 2000, "description": "Instructions for the driver" } }, "required": [ "address" ], "description": "Place and date of taking over the goods (CMR box 4)" }, "delivery": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Person on site" }, "instructions": { "type": "string", "maxLength": 2000, "description": "Instructions for the driver" } }, "required": [ "address" ], "description": "Place designated for delivery (CMR box 3)" }, "goods": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Nature of the goods (CMR box 9)" }, "marks": { "type": "string", "maxLength": 200, "description": "Marks and numbers (CMR box 6)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of packages (CMR box 7)" }, "package_type": { "type": "string", "enum": [ "pallet", "box", "carton", "crate", "bag", "drum", "roll", "bundle", "container", "loose", "other" ], "description": "Method of packing (CMR box 8)" }, "gross_weight_kg": { "type": "number", "minimum": 0, "description": "Gross weight in kilograms (CMR box 11)" }, "volume_m3": { "type": "number", "minimum": 0, "description": "Volume in cubic metres (CMR box 12)" }, "hs_code": { "type": "string", "pattern": "^\\d{4,10}$", "description": "Harmonised System code (statistical number, CMR box 10)" }, "adr": { "type": "object", "properties": { "un_number": { "type": "string", "pattern": "^\\d{4}$" }, "class": { "type": "string", "maxLength": 10, "description": "ADR class, for example \"3\" or \"5.1\"" }, "packing_group": { "type": "string", "enum": [ "I", "II", "III" ], "description": "ADR packing group" }, "proper_shipping_name": { "type": "string", "maxLength": 200 }, "tunnel_code": { "type": "string", "maxLength": 10, "description": "Tunnel restriction code, for example \"(D/E)\"" }, "limited_quantity": { "type": "boolean" }, "environmentally_hazardous": { "type": "boolean" } }, "description": "Dangerous goods declaration under ADR" } }, "required": [ "description", "quantity", "package_type" ], "description": "One line of goods" }, "maxItems": 200, "description": "Goods lines; a business rule requires at least one" }, "vehicle": { "type": "object", "properties": { "plate": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Registration plate of the tractor or truck" }, "trailer_plate": { "type": "string", "maxLength": 20 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of registration" }, "equipment_category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the load unit named in trailer_plate" } }, "required": [ "plate" ], "description": "Truck and trailer performing the transport" }, "combined_transport": { "type": "object", "properties": { "sequence": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Position of this road leg in the combined transport chain, starting at 1" }, "carried_unit": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Container, swap body or trailer number of the carried unit" }, "category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the carried unit" } }, "description": "Intermodal unit carried on the load unit of this road leg" } }, "description": "Place of this road leg in a combined transport operation (EU2)" }, "driver": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "description": "Used for SMS sign requests and the driver overview" }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of the signing flow and documents" } }, "required": [ "name" ], "description": "Driver who receives the sign links" }, "charges": { "type": "object", "properties": { "carriage": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Carriage charges (CMR box 19)" }, "cash_on_delivery": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Cash on delivery (CMR box 15)" }, "payer": { "type": "string", "enum": [ "consignor", "consignee", "principal" ], "description": "Who pays the carriage" } }, "description": "Carriage charges and who pays them (CMR box 20)" }, "special_agreements": { "type": "string", "maxLength": 2000, "description": "Special agreements (CMR box 19)" }, "sender_instructions": { "type": "string", "maxLength": 2000, "description": "Sender's instructions (CMR box 13)" }, "documents_attached": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20, "description": "Documents attached (CMR box 5)" }, "waste": { "type": "object", "properties": { "notification_number": { "type": "string", "pattern": "^[A-Za-z0-9]{12,13}$", "description": "Notification number; absent for a shipment under the Annex VII procedure" }, "document_number": { "type": "string", "pattern": "^(?:[A-Za-z0-9]{12,13}\\.\\d{6}|GLW\\.[A-Za-z0-9]{12})$", "description": "Movement document or Annex VII document number the carrier confirms against" }, "ewc_code": { "type": "string", "pattern": "^\\d{2} ?\\d{2} ?\\d{2}\\*?$", "description": "What is being carried, as a List of Waste code" } }, "required": [ "ewc_code" ], "description": "Waste shipment details; present turns the consignment into a DIWASS case (schema version 2)" }, "transport_type": { "type": "string", "enum": [ "national", "international", "cabotage", "combined" ], "description": "Kind of transport; derived from the countries when not given, cabotage and combined only on explicit input" }, "id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "status": { "type": "string", "enum": [ "draft", "issued", "in_transit", "delivered", "completed", "cancelled" ], "description": "Lifecycle status" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "version_id": { "type": "string", "pattern": "^ver_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment version id" }, "document_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The content this signature will bind (ADR 0004)" }, "issued_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" } }, "required": [ "id", "status", "version", "version_id", "document_hash" ], "description": "The consignment note, scoped to the role of the sign link" }, "signatures": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "consignor", "carrier", "consignee" ], "description": "Who signs: CMR boxes 22, 23 and 24" }, "method": { "type": "string", "enum": [ "drawn", "click_otp", "api", "photo_of_paper" ], "description": "How the signature was given (ADR 0004)" }, "trust_level": { "type": "string", "enum": [ "platform_auth", "ades", "qes" ], "description": "Trust level of the signature; platform_auth is the default, ades and qes need a QTSP" }, "signer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "company": { "type": "string", "maxLength": 200 } }, "required": [ "name" ] }, "signed_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" } }, "required": [ "role", "method", "trust_level", "signer", "signed_at" ] }, "description": "Already signed, in signing order" }, "remarks": { "type": "array", "items": { "$ref": "#/components/schemas/RemarkSummary" }, "description": "The reservations of CMR box 18, newest first, as the list endpoint orders them" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "document id" }, "kind": { "type": "string", "enum": [ "ecmr_pdf", "pod_pdf", "attachment", "signature_image", "photo", "other" ], "description": "What the file is" }, "filename": { "type": "string" }, "mime": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png", "image/webp", "application/json" ], "description": "Mime type" }, "size": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest, lower-case hex" }, "url": { "type": "string", "format": "uri", "description": "A signed download URL that lives five minutes (ADR 0007)" } }, "required": [ "id", "kind", "mime", "size", "sha256", "url" ] } }, "related_requests": { "type": "array", "items": { "$ref": "#/components/schemas/SignRelatedRequest" }, "description": "The other sign links of this shipment, without their tokens" }, "trust_level": { "type": "string", "enum": [ "platform_auth", "ades", "qes" ], "description": "The level this link has to reach (M5-02). `platform_auth` is the default and needs nothing extra; `ades` and `qes` need the identification step below first." }, "identification": { "$ref": "#/components/schemas/SignIdentification" }, "token": { "type": "string", "description": "Present only when this context was opened with a handoff token: the original sign token, so the new device can submit with it" } }, "required": [ "token_id", "role", "status", "allowed_methods", "otp_channels", "locale", "expires_at", "shipment", "signatures", "remarks", "documents", "related_requests", "trust_level" ] }, "RemarkSummary": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rmk_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "remark id" }, "phase": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "When the remark was made" }, "type": { "type": "string", "enum": [ "damage", "shortage", "delay", "other" ], "description": "Kind of reservation" }, "text": { "type": "string", "maxLength": 2000 }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "author": { "type": "string", "description": "Who recorded it; absent on a remark without an actor" } }, "required": [ "id", "phase", "type", "created_at" ] }, "SignRelatedRequest": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sgr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "signature request id" }, "role": { "type": "string", "enum": [ "consignor", "carrier", "consignee" ], "description": "Who signs: CMR boxes 22, 23 and 24" }, "status": { "type": "string", "enum": [ "pending", "used", "expired", "revoked" ], "description": "`pending` until it is submitted, its `expires_at` passes or it is withdrawn with `POST /v1/signature-requests/:id/revoke`" } }, "required": [ "id", "role", "status" ] }, "SignIdentification": { "type": "object", "properties": { "reference": { "type": "string", "description": "Names this identification, for `GET /v1/sign/:token/identification`. Absent on the context, which reports a step nobody has started yet." }, "provider_name": { "type": "string", "description": "What the signer is told they identify themselves at, in so many words" }, "level": { "type": "string", "enum": [ "ades", "qes" ], "description": "The level this identification is for" }, "status": { "type": "string", "enum": [ "required", "pending", "verified" ], "description": "`required` until the signer starts, `pending` while the provider is still asking them things, `verified` once `identification_token` may be sent along with the signature" }, "identification_token": { "type": "string", "description": "Present once `status` is `verified`; pass it to `POST /v1/sign/:token`" }, "redirect_url": { "type": "string", "format": "uri", "description": "Where the signer goes to identify themselves, when the provider has a flow of its own. Absent means there is nowhere to send them and the step is already done." }, "expires_at": { "type": "string", "format": "date-time", "description": "When this identification stops counting" } }, "required": [ "provider_name", "level", "status" ], "description": "Present exactly when `trust_level` is `ades` or `qes`" }, "SignSubmit": { "oneOf": [ { "type": "object", "properties": { "method": { "type": "string", "enum": [ "drawn" ] }, "signer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "company": { "type": "string", "maxLength": 200 } }, "required": [ "name" ] }, "image": { "type": "string", "minLength": 1, "description": "Base64-encoded PNG of the drawn signature, at most 204800 bytes" }, "geo": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 }, "accuracy_m": { "type": "number", "minimum": 0 } }, "required": [ "lat", "lng" ], "description": "Only stored when `consent` is true" }, "device": { "type": "string", "enum": [ "own", "driver" ], "default": "own", "description": "`driver` when the signer borrowed the driver device; `own` otherwise" }, "consent": { "type": "boolean", "enum": [ true ], "description": "The signer agreed to sign electronically" }, "identification_token": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The `identification_token` of `POST /v1/sign/:token/identification`. Single use and valid fifteen minutes; only on a link with `trust_level` `ades` or `qes`." }, "pod": { "type": "object", "properties": { "received_colli": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Packages actually taken over, against the sum of `goods[].quantity` (CMR box 7)" }, "notes": { "type": "string", "minLength": 1, "maxLength": 500, "description": "What the consignee wants recorded about the count; damage goes in a reservation" } }, "description": "The colli count of the consignee; only on a consignee sign link" } }, "required": [ "method", "signer", "image", "consent" ] }, { "type": "object", "properties": { "method": { "type": "string", "enum": [ "click_otp" ] }, "signer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "company": { "type": "string", "maxLength": 200 } }, "required": [ "name" ] }, "otp_verified_token": { "type": "string", "minLength": 1, "description": "The `otp_verified_token` of `POST /v1/sign/:token/otp/verify`. Single use and valid five minutes; test mode also accepts the fixed sandbox value `test-ok`." }, "otp_channel": { "type": "string", "enum": [ "email", "sms" ], "description": "The channel the code was asked for, when it was not the first of `otp_channels`. A proof is bound to the address it was earned on, so this is what tells the API which of the two to check it against, and it is what the evidence records." }, "device": { "type": "string", "enum": [ "own", "driver" ], "default": "own", "description": "`driver` when the signer borrowed the driver device; `own` otherwise" }, "consent": { "type": "boolean", "enum": [ true ] }, "identification_token": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The `identification_token` of `POST /v1/sign/:token/identification`. Single use and valid fifteen minutes; only on a link with `trust_level` `ades` or `qes`." }, "pod": { "type": "object", "properties": { "received_colli": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Packages actually taken over, against the sum of `goods[].quantity` (CMR box 7)" }, "notes": { "type": "string", "minLength": 1, "maxLength": 500, "description": "What the consignee wants recorded about the count; damage goes in a reservation" } }, "description": "The colli count of the consignee; only on a consignee sign link" } }, "required": [ "method", "signer", "otp_verified_token", "consent" ] } ] }, "SignIdentificationStart": { "type": "object", "properties": { "signer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "company": { "type": "string", "maxLength": 200 } }, "description": "Who the provider is asked to identify, when the caller knows it better than the link does; the recipient of the sign link otherwise. Not what ends up in the certificate — that is the `signer` of the signature itself." }, "return_url": { "type": "string", "format": "uri", "description": "Where the provider returns the signer; the sign page itself when left out" } } }, "SignHandoff": { "type": "object", "properties": { "handoff_url": { "type": "string", "format": "uri", "description": "`SIGN_BASE_URL/s/`, valid once" }, "expires_at": { "type": "string", "format": "date-time", "description": "Ten minutes after the request" }, "qr_svg": { "type": "string", "description": "The QR code of `handoff_url` as an SVG document" } }, "required": [ "handoff_url", "expires_at", "qr_svg" ] }, "SignPhotos": { "type": "object", "properties": { "photos": { "type": "array", "items": { "$ref": "#/components/schemas/Document" }, "description": "The stored photos, in the order the parts were sent" } }, "required": [ "photos" ] }, "Remark": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rmk_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "remark id" }, "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "phase": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "When the remark was made" }, "type": { "type": "string", "enum": [ "damage", "shortage", "delay", "other" ], "description": "Kind of reservation" }, "text": { "type": "string", "maxLength": 2000 }, "photo_document_ids": { "type": "array", "items": { "type": "string", "pattern": "^doc_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "document id" }, "maxItems": 20, "description": "Photos stored as documents" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/Document" }, "description": "The photo documents of this remark, in the order they were attached" } }, "required": [ "id", "shipment_id", "phase", "type", "photo_document_ids", "created_at", "photos" ] }, "SignOtpChallenge": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "Where the code went" }, "destination": { "type": "string", "description": "The recipient, masked: `a***a@example.com`, `+316*****78`" }, "expires_at": { "type": "string", "format": "date-time", "description": "Ten minutes after the request" }, "resend_in_seconds": { "type": "integer", "minimum": 0, "description": "How long to wait before offering a new code, so the window is not burnt" } }, "required": [ "channel", "destination", "expires_at", "resend_in_seconds" ] }, "SignOtpVerified": { "type": "object", "properties": { "otp_verified_token": { "type": "string", "description": "Pass as `otp_verified_token` to `POST /v1/sign/:token`; works exactly once" }, "expires_at": { "type": "string", "format": "date-time", "description": "Five minutes after the verification" } }, "required": [ "otp_verified_token", "expires_at" ] }, "SignOtpVerify": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^\\d{6}$", "description": "The six digits from the message" } }, "required": [ "code" ] }, "RemarkList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Remark" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Always null: a shipment carries few remarks, so the list is complete" } }, "required": [ "data", "next_cursor" ] }, "ProofOfDelivery": { "type": "object", "properties": { "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "status": { "type": "string", "enum": [ "delivered", "completed" ], "description": "A shipment has an ePOD from `delivered` on" }, "delivered_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "consignee_signature": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sig_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "signature id" }, "signer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "company": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" } }, "required": [ "name" ], "description": "The person who signed" }, "method": { "type": "string", "enum": [ "drawn", "click_otp", "api", "photo_of_paper" ], "description": "How the signature was given (ADR 0004)" }, "trust_level": { "type": "string", "enum": [ "platform_auth", "ades", "qes" ], "description": "Trust level of the signature; platform_auth is the default, ades and qes need a QTSP" }, "kind": { "type": "string", "enum": [ "signature", "seal" ], "description": "A natural person signs; a legal person seals (OLF semantics)" }, "signed_at": { "type": "string", "format": "date-time", "description": "The moment the signer stamped, not the moment we stored" }, "geo": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 }, "accuracy_m": { "type": "number", "minimum": 0 } }, "required": [ "lat", "lng" ], "description": "Where the signature was given, when the signer shared it" }, "document_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "document_hash of the version that was signed" }, "verified": { "type": "boolean", "description": "True while the signed version is still the current version of the shipment" }, "image_url": { "type": "string", "format": "uri", "description": "Signed URL of the signature image or the photo of the paper, valid five minutes" } }, "required": [ "id", "signer", "method", "trust_level", "kind", "signed_at", "document_hash", "verified" ], "description": "The consignee signature that delivered the shipment" }, "remarks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rmk_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "remark id" }, "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "phase": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "When the remark was made" }, "type": { "type": "string", "enum": [ "damage", "shortage", "delay", "other" ], "description": "Kind of reservation" }, "text": { "type": "string", "maxLength": 2000 }, "photo_document_ids": { "type": "array", "items": { "type": "string", "pattern": "^doc_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "document id" }, "maxItems": 20, "description": "Photos stored as documents" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/Document" }, "description": "The photos of this remark, with fresh URLs" } }, "required": [ "id", "shipment_id", "phase", "type", "photo_document_ids", "created_at", "photos" ], "description": "A reservation recorded at pickup or delivery" }, "description": "Every reservation on this shipment, newest first" }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/Document" }, "description": "Every photo of every reservation, flattened, with fresh download URLs" }, "colli": { "type": "object", "properties": { "expected": { "type": "integer", "minimum": 0, "description": "Packages on the consignment note: the sum of `goods[].quantity` (CMR box 7)" }, "received": { "type": "object", "properties": { "colli": { "type": "integer", "minimum": 0, "description": "What the consignee counted" }, "notes": { "type": "string", "description": "What the consignee wrote about the count" } }, "description": "Absent until a consignee reported a count through `POST /v1/sign/:token`" }, "discrepancy": { "type": "boolean", "description": "True only when a count was reported and differs from `expected`; an absent count is not a discrepancy, it is an unanswered question" } }, "required": [ "expected", "discrepancy" ], "description": "The colli check at delivery: what the note promised against what arrived (M1-22)" }, "pdf_url": { "type": [ "string", "null" ], "format": "uri", "description": "Signed URL of the rendered ePOD PDF, valid five minutes. The PDF is the consignment note with the proof of delivery page behind it, rendered at delivery (M2-10); it is null only while an older shipment has not been re-rendered yet" }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri", "description": "This ePOD" }, "shipment": { "type": "string", "format": "uri", "description": "The delivered shipment" } }, "required": [ "self", "shipment" ], "description": "Absolute URLs of the related resources" } }, "required": [ "shipment_id", "status", "delivered_at", "consignee_signature", "remarks", "photos", "colli", "pdf_url", "links" ] }, "WebhookEndpointWithSecret": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Signing secret, shown once. Store it: Cargofollow cannot show it again.", "example": "whsec_3mK…" } }, "required": [ "secret" ] } ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "webhook endpoint id" }, "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "https URL that receives the deliveries", "example": "https://example.test/hooks/freightapi" }, "description": { "type": [ "string", "null" ], "maxLength": 200, "description": "Free-form label for the console" }, "events": { "type": "array", "items": { "type": "string", "description": "Event filter: an event name, \"shipment.*\" or \"*\"" } }, "active": { "type": "boolean", "description": "Inactive endpoints receive no deliveries" }, "mode": { "type": "string", "enum": [ "test", "live" ], "description": "Data mode; follows from the API key" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" } }, "required": [ "id", "url", "description", "events", "active", "mode", "created_at", "updated_at" ] }, "CreateWebhookEndpoint": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "https URL that receives the deliveries", "example": "https://example.test/hooks/freightapi" }, "events": { "type": "array", "items": { "type": "string", "description": "Event filter: an event name, \"shipment.*\" or \"*\"" }, "minItems": 1, "maxItems": 50, "description": "Event names, family wildcards such as \"shipment.*\", or \"*\" for everything", "example": [ "shipment.*", "signature.completed" ] }, "description": { "type": "string", "maxLength": 200, "description": "Free-form label for the console" }, "active": { "type": "boolean", "default": true, "description": "Defaults to true" } }, "required": [ "url", "events" ] }, "WebhookEndpointList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^whe_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Pass as ?cursor= for the next page" } }, "required": [ "data", "next_cursor" ] }, "UpdateWebhookEndpoint": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "https URL that receives the deliveries", "example": "https://example.test/hooks/freightapi" }, "events": { "type": "array", "items": { "type": "string", "description": "Event filter: an event name, \"shipment.*\" or \"*\"" }, "minItems": 1, "maxItems": 50, "description": "Event names, family wildcards such as \"shipment.*\", or \"*\" for everything", "example": [ "shipment.*", "signature.completed" ] }, "description": { "type": [ "string", "null" ], "maxLength": 200, "description": "null clears the description" }, "active": { "type": "boolean" } } }, "WebhookTestResult": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "succeeded", "failed" ], "description": "succeeded when the receiver answered 2xx within the timeout" }, "event_id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment event id" }, "delivery_id": { "type": "string", "pattern": "^whd_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Value of the freightapi-delivery-id header" }, "response_status": { "type": [ "integer", "null" ], "description": "null when no response arrived" }, "response_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Headers the conformance checklist reads back, currently freightapi-echo" }, "duration_ms": { "type": "integer", "minimum": 0 }, "error": { "type": [ "string", "null" ], "description": "Why the ping failed, or null on success" } }, "required": [ "status", "event_id", "delivery_id", "response_status", "response_headers", "duration_ms", "error" ] }, "WebhookDeliveryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^whd_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Pass as ?cursor= for the next page" } }, "required": [ "data", "next_cursor" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whd_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Value of the freightapi-delivery-id header" }, "endpoint_id": { "type": "string", "pattern": "^whe_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "webhook endpoint id" }, "event_id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Value of the freightapi-event-id header; a replay reuses it" }, "event_type": { "type": "string", "enum": [ "shipment.created", "shipment.issued", "shipment.updated", "shipment.cancelled", "shipment.pickup_signed", "shipment.delivered", "shipment.completed", "signature.completed", "document.created", "remark.added", "inspection.viewed", "provider.sync_failed", "efti.uil_issued", "efti.authority_access", "efti.combined_transport_stamped", "ping" ], "description": "Event name" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "dead" ], "description": "pending until a 2xx arrives, dead after the last retry" }, "attempt": { "type": "integer", "minimum": 0, "description": "Attempts made so far; 0 until the first one starts" }, "max_attempts": { "type": "integer", "exclusiveMinimum": 0, "description": "Attempts before the delivery fails for good" }, "response_status": { "type": [ "integer", "null" ], "description": "null when no response arrived" }, "duration_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "error": { "type": [ "string", "null" ], "description": "Why the last attempt failed, or null" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the next attempt is due" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a 2xx arrived" }, "mode": { "type": "string", "enum": [ "test", "live" ], "description": "Data mode; follows from the API key" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" } }, "required": [ "id", "endpoint_id", "event_id", "event_type", "status", "attempt", "max_attempts", "response_status", "duration_ms", "error", "next_attempt_at", "delivered_at", "mode", "created_at", "updated_at" ] }, "WebhookDeliveryDetail": { "allOf": [ { "$ref": "#/components/schemas/WebhookDelivery" }, { "type": "object", "properties": { "request_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Headers of every attempt. `freightapi-signature` is computed per attempt and therefore not listed." }, "request_body": { "type": [ "string", "null" ], "description": "The exact bytes that are signed and sent" }, "response_body": { "type": [ "string", "null" ], "description": "What the receiver answered, truncated to 4096 bytes" } }, "required": [ "request_headers", "request_body", "response_body" ] } ] }, "EventFeed": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentEvent" }, "description": "Newest first, by the moment Cargofollow recorded the event" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page; null on the last page" } }, "required": [ "data", "next_cursor" ] }, "RequestLogList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RequestLog" }, "description": "Newest first" }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^req_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Pass as `cursor` to get the next page; null on the last page" } }, "required": [ "data", "next_cursor" ] }, "RequestLog": { "type": "object", "properties": { "request_id": { "type": "string", "pattern": "^req_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The `freightapi-request-id` of that call" }, "method": { "type": "string" }, "path": { "type": "string", "description": "The path without the query string" }, "status": { "type": "integer", "description": "The status the caller got" }, "duration_ms": { "type": "integer", "minimum": 0 }, "error_code": { "type": [ "string", "null" ], "description": "The stable `code` of the problem response, or null on a success" }, "api_key_id": { "type": [ "string", "null" ], "pattern": "^key_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "null on a public path" }, "mode": { "type": [ "string", "null" ], "enum": [ "test", "live", null ], "description": "Data mode; follows from the API key" }, "shipment_id": { "type": [ "string", "null" ], "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The shipment the path named, if any" }, "idempotency_key": { "type": [ "string", "null" ] }, "ip_hash": { "type": [ "string", "null" ], "description": "sha256 of the UTC day and the caller IP" }, "user_agent": { "type": [ "string", "null" ] }, "bytes_in": { "type": "integer", "minimum": 0 }, "bytes_out": { "type": "integer", "minimum": 0 }, "retain_until": { "type": [ "string", "null" ], "format": "date-time", "description": "Set on audit-relevant calls that outlive the retention window" }, "warning": { "type": [ "string", "null" ], "description": "Set on a call that succeeded but leaned on something that is going away, such as `download_link_without_audience` for a link from before `aud` existed (M3-20)" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" } }, "required": [ "request_id", "method", "path", "status", "duration_ms", "error_code", "api_key_id", "mode", "shipment_id", "idempotency_key", "ip_hash", "user_agent", "bytes_in", "bytes_out", "retain_until", "warning", "created_at" ] }, "AuditLogList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEntry" }, "description": "Newest first" }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Pass as `cursor` to get the next page; null on the last page" } }, "required": [ "data", "next_cursor" ] }, "AuditEntry": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "audit entry id" }, "action": { "type": "string", "enum": [ "api_key.created", "api_key.revoked", "webhook_endpoint.created", "webhook_endpoint.updated", "webhook_endpoint.secret_rotated", "member.invited", "member.role_changed", "member.removed", "organization.updated", "export.started", "erasure.requested", "two_factor.enabled", "two_factor.disabled", "two_factor.reset", "two_factor.verification_failed", "two_factor.recovery_code_used", "two_factor.recovery_codes_regenerated", "two_factor.policy_changed", "efti_authorisation.granted", "efti_authorisation.revoked" ], "description": "What was done" }, "actor_type": { "type": "string", "enum": [ "user", "api_key", "system" ], "description": "Console user, API key, or the platform itself" }, "actor_id": { "type": [ "string", "null" ], "description": "User id or key id; null when the platform acted" }, "target_type": { "type": "string", "enum": [ "api_key", "webhook_endpoint", "member", "invitation", "organization", "export", "data_subject", "user", "efti_authorisation" ] }, "target_id": { "type": [ "string", "null" ], "description": "The thing acted on; null for the organisation" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "An allowlist per action; never personal data and never a secret" }, "ip_hash": { "type": [ "string", "null" ], "description": "sha256 of the UTC day and the caller IP" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" } }, "required": [ "id", "action", "actor_type", "actor_id", "target_type", "target_id", "metadata", "ip_hash", "created_at" ] }, "NotificationList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" }, "description": "Newest first" }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^ntf_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Pass as `cursor` to get the next page; null on the last page" } }, "required": [ "data", "next_cursor" ] }, "Notification": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ntf_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "notification id" }, "channel": { "type": "string", "enum": [ "email", "sms" ] }, "template": { "type": "string", "description": "Which message this was: `sign_request`, `otp`, `pod_delivered`, `invite`, …" }, "recipient_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the normalised recipient. The address itself is never stored; hash the one you have to find its messages" }, "locale": { "type": [ "string", "null" ], "description": "The language the message was rendered in" }, "status": { "type": "string", "enum": [ "queued", "sent", "mocked", "failed" ], "description": "`sent` left the Worker, `mocked` went to the console sender because the channel has no credentials, `failed` was refused by the provider, `queued` has not been tried yet" }, "provider_message_id": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ], "description": "What the provider said when it refused" }, "shipment_id": { "type": [ "string", "null" ], "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" } }, "required": [ "id", "channel", "template", "recipient_hash", "locale", "status", "provider_message_id", "error", "shipment_id", "sent_at", "created_at" ] }, "InspectionView": { "type": "object", "properties": { "token_id": { "type": "string", "pattern": "^ins_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "inspection token id" }, "expires_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "locale": { "type": "string", "description": "The locale resolved from `?locale=` or `Accept-Language`" }, "viewed_at": { "type": "string", "format": "date-time", "description": "This view; it is in the chain as `inspection.viewed`" }, "shipment": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 100, "description": "Client's own reference; shown on the CMR" }, "consignor": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Sender (CMR box 1)" }, "carrier": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Carrier (CMR box 16)" }, "consignee": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Consignee (CMR box 2)" }, "principal": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Principal who ordered the transport; not on the CMR form" }, "successive_carriers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Party to the contract of carriage" }, "maxItems": 10, "description": "Successive carriers (CMR box 17)" }, "goods": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Nature of the goods (CMR box 9)" }, "marks": { "type": "string", "maxLength": 200, "description": "Marks and numbers (CMR box 6)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of packages (CMR box 7)" }, "package_type": { "type": "string", "enum": [ "pallet", "box", "carton", "crate", "bag", "drum", "roll", "bundle", "container", "loose", "other" ], "description": "Method of packing (CMR box 8)" }, "gross_weight_kg": { "type": "number", "minimum": 0, "description": "Gross weight in kilograms (CMR box 11)" }, "volume_m3": { "type": "number", "minimum": 0, "description": "Volume in cubic metres (CMR box 12)" }, "hs_code": { "type": "string", "pattern": "^\\d{4,10}$", "description": "Harmonised System code (statistical number, CMR box 10)" }, "adr": { "type": "object", "properties": { "un_number": { "type": "string", "pattern": "^\\d{4}$" }, "class": { "type": "string", "maxLength": 10, "description": "ADR class, for example \"3\" or \"5.1\"" }, "packing_group": { "type": "string", "enum": [ "I", "II", "III" ], "description": "ADR packing group" }, "proper_shipping_name": { "type": "string", "maxLength": 200 }, "tunnel_code": { "type": "string", "maxLength": 10, "description": "Tunnel restriction code, for example \"(D/E)\"" }, "limited_quantity": { "type": "boolean" }, "environmentally_hazardous": { "type": "boolean" } }, "description": "Dangerous goods declaration under ADR" } }, "required": [ "description", "quantity", "package_type" ], "description": "One line of goods" }, "maxItems": 200, "description": "Goods lines; a business rule requires at least one" }, "vehicle": { "type": "object", "properties": { "plate": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Registration plate of the tractor or truck" }, "trailer_plate": { "type": "string", "maxLength": 20 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of registration" }, "equipment_category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the load unit named in trailer_plate" } }, "required": [ "plate" ], "description": "Truck and trailer performing the transport" }, "combined_transport": { "type": "object", "properties": { "sequence": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Position of this road leg in the combined transport chain, starting at 1" }, "carried_unit": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Container, swap body or trailer number of the carried unit" }, "category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the carried unit" } }, "description": "Intermodal unit carried on the load unit of this road leg" } }, "description": "Place of this road leg in a combined transport operation (EU2)" }, "charges": { "type": "object", "properties": { "carriage": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Carriage charges (CMR box 19)" }, "cash_on_delivery": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Cash on delivery (CMR box 15)" }, "payer": { "type": "string", "enum": [ "consignor", "consignee", "principal" ], "description": "Who pays the carriage" } }, "description": "Carriage charges and who pays them (CMR box 20)" }, "special_agreements": { "type": "string", "maxLength": 2000, "description": "Special agreements (CMR box 19)" }, "sender_instructions": { "type": "string", "maxLength": 2000, "description": "Sender's instructions (CMR box 13)" }, "documents_attached": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20, "description": "Documents attached (CMR box 5)" }, "waste": { "type": "object", "properties": { "notification_number": { "type": "string", "pattern": "^[A-Za-z0-9]{12,13}$", "description": "Notification number; absent for a shipment under the Annex VII procedure" }, "document_number": { "type": "string", "pattern": "^(?:[A-Za-z0-9]{12,13}\\.\\d{6}|GLW\\.[A-Za-z0-9]{12})$", "description": "Movement document or Annex VII document number the carrier confirms against" }, "ewc_code": { "type": "string", "pattern": "^\\d{2} ?\\d{2} ?\\d{2}\\*?$", "description": "What is being carried, as a List of Waste code" } }, "required": [ "ewc_code" ], "description": "Waste shipment details; present turns the consignment into a DIWASS case (schema version 2)" }, "transport_type": { "type": "string", "enum": [ "national", "international", "cabotage", "combined" ], "description": "Kind of transport; derived from the countries when not given, cabotage and combined only on explicit input" }, "id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "status": { "type": "string", "enum": [ "draft", "issued", "in_transit", "delivered", "completed", "cancelled" ], "description": "Lifecycle status" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "version_id": { "type": "string", "pattern": "^ver_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment version id" }, "document_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest, lower-case hex" }, "issued_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "delivered_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "cancelled_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "driver": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of the signing flow and documents" } }, "required": [ "name" ] }, "pickup": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" } }, "required": [ "address" ] }, "delivery": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" } }, "required": [ "address" ] } }, "required": [ "consignor", "carrier", "consignee", "goods", "transport_type", "id", "status", "version", "version_id", "document_hash", "pickup", "delivery" ], "description": "The consignment note as the current version has it" }, "signatures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sig_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "signature id" }, "role": { "type": "string", "enum": [ "consignor", "carrier", "consignee" ], "description": "Who signs: CMR boxes 22, 23 and 24" }, "kind": { "type": "string", "enum": [ "signature", "seal" ], "description": "A natural person signs; a legal person seals (OLF semantics)" }, "method": { "type": "string", "enum": [ "drawn", "click_otp", "api", "photo_of_paper" ], "description": "How the signature was given (ADR 0004)" }, "trust_level": { "type": "string", "enum": [ "platform_auth", "ades", "qes" ], "description": "Trust level of the signature; platform_auth is the default, ades and qes need a QTSP" }, "signer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "company": { "type": "string", "maxLength": 200 } }, "required": [ "name" ] }, "signed_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "version_id": { "type": "string", "pattern": "^ver_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment version id" }, "verified": { "type": "boolean", "description": "Whether the signed content still equals the current version of the shipment" }, "qtsp": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Which QTSP signed, as the register names it" }, "format": { "type": "string", "enum": [ "CAdES-B-B" ], "description": "ETSI EN 319 122-1 baseline, without a timestamp" }, "level": { "type": "string", "enum": [ "ades", "qes" ] }, "certificate_ref": { "type": "string", "maxLength": 400, "description": "Issuer distinguished name and serial" }, "signed_at": { "type": "string", "format": "date-time", "description": "The signing time in the signed attributes" }, "digest_algorithm": { "type": "string", "enum": [ "sha256" ] }, "signature_algorithm": { "type": "string", "minLength": 1, "maxLength": 60 }, "identification_reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The identification at the QTSP that authorised this signature" } }, "required": [ "provider", "format", "level", "certificate_ref", "signed_at", "digest_algorithm", "signature_algorithm", "identification_reference" ], "description": "The advanced or qualified signature behind an `ades` or `qes` trust level (M5-02): which provider signed, in which format, at which level and on which certificate. Absent on a `platform_auth` signature. The envelope itself is not handed to an inspector — `GET /v1/signatures/:id/verification` is, and that one needs an API key." } }, "required": [ "id", "role", "kind", "method", "trust_level", "signer", "signed_at", "version_id", "verified" ] }, "description": "In signing order" }, "remarks": { "type": "array", "items": { "$ref": "#/components/schemas/RemarkSummary" }, "description": "The reservations of CMR box 18, newest first, as the list endpoint orders them" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "document id" }, "kind": { "type": "string", "enum": [ "ecmr_pdf", "pod_pdf", "attachment", "signature_image", "photo", "other" ], "description": "What the file is" }, "filename": { "type": "string" }, "mime": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png", "image/webp", "application/json" ], "description": "Mime type" }, "size": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest, lower-case hex" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "url": { "type": "string", "format": "uri", "description": "Download through the same token; no API key needed" } }, "required": [ "id", "kind", "mime", "size", "sha256", "created_at", "url" ] } }, "integrity": { "type": "object", "properties": { "ok": { "type": "boolean" }, "events": { "type": "integer", "minimum": 0 }, "head_hash": { "type": "string" } }, "required": [ "ok", "events", "head_hash" ] } }, "required": [ "token_id", "expires_at", "locale", "viewed_at", "shipment", "signatures", "remarks", "documents", "integrity" ] }, "Provider": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "eCMR provider that executes the consignment" }, "implemented": { "type": "boolean", "description": "The adapter does something; a stub answers 501" }, "enabled": { "type": "boolean", "description": "This organisation may put shipments on this provider in this mode" }, "default": { "type": "boolean", "description": "This is the organisation default provider" }, "capabilities": { "type": "object", "properties": { "signatures": { "type": "boolean", "description": "The provider records signatures itself" }, "documents": { "type": "boolean", "description": "The provider renders its own consignment note PDF" }, "webhooks": { "type": "boolean", "description": "The provider pushes status changes to Cargofollow" }, "cancel": { "type": "boolean" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Countries the provider is usable in; empty means no restriction" }, "niwo_recognized": { "type": "boolean", "description": "Recognised for the Belgian eCMR" } }, "required": [ "signatures", "documents", "webhooks", "cancel", "countries" ], "description": "What a provider adapter supports" } }, "required": [ "name", "implemented", "enabled", "default", "capabilities" ], "description": "One entry of the provider catalogue" }, "ProviderRoutingRule": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "provider routing rule id" }, "priority": { "type": "integer", "description": "Lowest first; the first matching rule decides" }, "match": { "type": "object", "properties": { "origin_country": { "type": [ "string", "null" ] }, "destination_country": { "type": [ "string", "null" ] }, "carrier_country": { "type": [ "string", "null" ] }, "transport_type": { "type": [ "string", "null" ], "enum": [ "national", "international", "cabotage", "combined", null ], "description": "Kind of transport; derived from the countries when not given, cabotage and combined only on explicit input" } }, "required": [ "origin_country", "destination_country", "carrier_country", "transport_type" ] }, "provider": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "eCMR provider that executes the consignment" }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" } }, "required": [ "id", "priority", "match", "provider", "active", "created_at", "updated_at" ], "description": "A corridor rule in the provider choice (ADR 0001)" }, "Requirements": { "type": "object", "properties": { "corridor": { "$ref": "#/components/schemas/RequirementsCorridor" }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/Requirement" }, "description": "EU-wide rules first, then the country rules, in a stable order" }, "ecmr": { "$ref": "#/components/schemas/EcmrCorridorStatus" }, "recommended_trust_level": { "type": "string", "enum": [ "platform_auth", "ades", "qes" ], "description": "The highest level any matching rule argues for (M5-02, ADR 0017). Advice, not a gate: `platform_auth` is what Cargofollow delivers without a trust service provider, and a corridor without a trust-level rule stays on it. Pass the level to `POST /v1/shipments/:id/signature-requests` as `trust_level` to act on it." } }, "required": [ "corridor", "requirements", "ecmr", "recommended_trust_level" ] }, "RequirementsCorridor": { "type": "object", "properties": { "origin": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "destination": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "carrier_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "transport_type": { "type": "string", "enum": [ "national", "international", "cabotage", "combined" ], "description": "Given or derived from the lane" }, "provider": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "eCMR provider that executes the consignment" }, "adr": { "type": "boolean" }, "combined": { "type": "boolean" }, "waste": { "type": "boolean" } }, "required": [ "origin", "destination", "transport_type", "adr", "combined", "waste" ] }, "Requirement": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier of the rule, also its message key" }, "level": { "type": "string", "enum": [ "required", "recommended", "info" ], "description": "`required` can be fined, `recommended` avoids a roadside discussion, `info` is background" }, "message": { "type": "string", "description": "The rule in the negotiated locale (`Accept-Language`, `?locale=`)" }, "source": { "$ref": "#/components/schemas/RequirementSource" }, "subset": { "type": "string", "pattern": "^(EU\\d[a-c]?|[A-Z]{2}\\d{1,2})$", "description": "eFTI subset the rule takes its data from" }, "recommends": { "type": "string", "enum": [ "platform_auth", "ades", "qes" ], "description": "The signature trust level this rule argues for (M5-02). Present only on the rules that have one; `recommended_trust_level` is the highest of them." } }, "required": [ "id", "level", "message", "source" ] }, "RequirementSource": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Public URL of the legal text or of the publishing authority" }, "title": { "type": "string", "description": "How the source is cited" }, "verified_at": { "type": "string", "format": "date", "description": "Date the URL was last checked against the rule" } }, "required": [ "url", "title", "verified_at" ] }, "EcmrCorridorStatus": { "type": "object", "properties": { "origin": { "$ref": "#/components/schemas/EcmrCountryStatus" }, "destination": { "$ref": "#/components/schemas/EcmrCountryStatus" }, "carrier_country": { "$ref": "#/components/schemas/EcmrCountryStatus" }, "source": { "$ref": "#/components/schemas/RequirementSource" } }, "required": [ "origin", "destination", "source" ] }, "EcmrCountryStatus": { "type": "object", "properties": { "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "party": { "type": [ "boolean", "null" ], "description": "Party to the 2008 e-CMR Protocol; `null` when Cargofollow has not assessed it" }, "since": { "type": [ "string", "null" ], "format": "date", "description": "Date the instrument of ratification or accession was deposited" } }, "required": [ "country", "party", "since" ] }, "PublicValidationResult": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "False when at least one rule of severity `error` fired" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" }, "description": "Findings that would block the create" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" }, "description": "Findings that would ride along on the 201" }, "transport_type": { "type": "string", "enum": [ "national", "international", "cabotage", "combined" ], "description": "What the create would store, derived if omitted" }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/Requirement" }, "description": "Country rules for this lane (M3-12), in register order. Empty when the shipment names no pickup or delivery country, or a country Cargofollow has no rules for." } }, "required": [ "valid", "errors", "warnings", "transport_type", "requirements" ] }, "PublicValidateInput": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 100, "description": "Client's own reference; shown on the CMR" }, "consignor": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Sender (CMR box 1)" }, "carrier": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Carrier (CMR box 16)" }, "consignee": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Consignee (CMR box 2)" }, "principal": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Principal who ordered the transport; not on the CMR form" }, "successive_carriers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or trading name" }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Contact person" }, "vat_number": { "type": "string", "maxLength": 30, "description": "VAT identification number" }, "eori": { "type": "string", "maxLength": 20, "description": "EORI number for customs" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number, for example the Dutch KvK number" }, "reference": { "type": "string", "maxLength": 100, "description": "This party's own reference for the consignment" } }, "required": [ "name", "address" ], "description": "Party to the contract of carriage" }, "maxItems": 10, "description": "Successive carriers (CMR box 17)" }, "pickup": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Person on site" }, "instructions": { "type": "string", "maxLength": 2000, "description": "Instructions for the driver" } }, "required": [ "address" ], "description": "Place and date of taking over the goods (CMR box 4)" }, "delivery": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Preferred language for notifications" } }, "description": "Person on site" }, "instructions": { "type": "string", "maxLength": 2000, "description": "Instructions for the driver" } }, "required": [ "address" ], "description": "Place designated for delivery (CMR box 3)" }, "goods": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Nature of the goods (CMR box 9)" }, "marks": { "type": "string", "maxLength": 200, "description": "Marks and numbers (CMR box 6)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of packages (CMR box 7)" }, "package_type": { "type": "string", "enum": [ "pallet", "box", "carton", "crate", "bag", "drum", "roll", "bundle", "container", "loose", "other" ], "description": "Method of packing (CMR box 8)" }, "gross_weight_kg": { "type": "number", "minimum": 0, "description": "Gross weight in kilograms (CMR box 11)" }, "volume_m3": { "type": "number", "minimum": 0, "description": "Volume in cubic metres (CMR box 12)" }, "hs_code": { "type": "string", "pattern": "^\\d{4,10}$", "description": "Harmonised System code (statistical number, CMR box 10)" }, "adr": { "type": "object", "properties": { "un_number": { "type": "string", "pattern": "^\\d{4}$" }, "class": { "type": "string", "maxLength": 10, "description": "ADR class, for example \"3\" or \"5.1\"" }, "packing_group": { "type": "string", "enum": [ "I", "II", "III" ], "description": "ADR packing group" }, "proper_shipping_name": { "type": "string", "maxLength": 200 }, "tunnel_code": { "type": "string", "maxLength": 10, "description": "Tunnel restriction code, for example \"(D/E)\"" }, "limited_quantity": { "type": "boolean" }, "environmentally_hazardous": { "type": "boolean" } }, "description": "Dangerous goods declaration under ADR" } }, "required": [ "description", "quantity", "package_type" ], "description": "One line of goods" }, "maxItems": 200, "description": "Goods lines; a business rule requires at least one" }, "vehicle": { "type": "object", "properties": { "plate": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Registration plate of the tractor or truck" }, "trailer_plate": { "type": "string", "maxLength": 20 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of registration" }, "equipment_category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the load unit named in trailer_plate" } }, "required": [ "plate" ], "description": "Truck and trailer performing the transport" }, "combined_transport": { "type": "object", "properties": { "sequence": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Position of this road leg in the combined transport chain, starting at 1" }, "carried_unit": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Container, swap body or trailer number of the carried unit" }, "category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the carried unit" } }, "description": "Intermodal unit carried on the load unit of this road leg" } }, "description": "Place of this road leg in a combined transport operation (EU2)" }, "driver": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "description": "Used for SMS sign requests and the driver overview" }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of the signing flow and documents" } }, "required": [ "name" ], "description": "Driver who receives the sign links" }, "charges": { "type": "object", "properties": { "carriage": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Carriage charges (CMR box 19)" }, "cash_on_delivery": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "Decimal amount as a string, for example \"12.50\"" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "amount", "currency" ], "description": "Cash on delivery (CMR box 15)" }, "payer": { "type": "string", "enum": [ "consignor", "consignee", "principal" ], "description": "Who pays the carriage" } }, "description": "Carriage charges and who pays them (CMR box 20)" }, "special_agreements": { "type": "string", "maxLength": 2000, "description": "Special agreements (CMR box 19)" }, "sender_instructions": { "type": "string", "maxLength": 2000, "description": "Sender's instructions (CMR box 13)" }, "documents_attached": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20, "description": "Documents attached (CMR box 5)" }, "waste": { "type": "object", "properties": { "notification_number": { "type": "string", "pattern": "^[A-Za-z0-9]{12,13}$", "description": "Notification number; absent for a shipment under the Annex VII procedure" }, "document_number": { "type": "string", "pattern": "^(?:[A-Za-z0-9]{12,13}\\.\\d{6}|GLW\\.[A-Za-z0-9]{12})$", "description": "Movement document or Annex VII document number the carrier confirms against" }, "ewc_code": { "type": "string", "pattern": "^\\d{2} ?\\d{2} ?\\d{2}\\*?$", "description": "What is being carried, as a List of Waste code" } }, "required": [ "ewc_code" ], "description": "Waste shipment details; present turns the consignment into a DIWASS case (schema version 2)" }, "transport_type": { "type": "string", "enum": [ "national", "international", "cabotage", "combined" ], "description": "Kind of transport; derived from the countries when omitted" }, "provider": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "Overrides the organisation default and routing rules" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Free-form key/value pairs of the client" }, "turnstile_token": { "type": "string", "maxLength": 2048, "description": "The Turnstile token, when it is not sent as `cf-turnstile-response`" } }, "required": [ "consignor", "carrier", "consignee", "pickup", "delivery", "goods" ] }, "ContactMessageResult": { "type": "object", "properties": { "delivered": { "type": "boolean", "description": "True when a real sender accepted the message; false when it was only mocked" } }, "required": [ "delivered" ] }, "ContactMessageInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Who is writing; goes in the subject so a reply needs no digging" }, "email": { "type": "string", "maxLength": 254, "format": "email", "description": "Where the answer goes; set as `Reply-To` and never stored" }, "company": { "type": "string", "maxLength": 160, "description": "Optional, and only ever used as context in the message" }, "message": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "What they want to say" }, "turnstile_token": { "type": "string", "maxLength": 2048, "description": "The Turnstile token, when it is not sent as `cf-turnstile-response`" } }, "required": [ "name", "email", "message" ] }, "SimulateResult": { "type": "object", "properties": { "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "action": { "type": "string", "enum": [ "sign", "deliver", "remark", "auto" ] }, "status": { "type": "string", "enum": [ "draft", "issued", "in_transit", "delivered", "completed", "cancelled" ], "description": "The status of the shipment after the action" }, "signature_ids": { "type": "array", "items": { "type": "string", "pattern": "^sig_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "signature id" }, "description": "Signatures this call recorded, in order" }, "remark_ids": { "type": "array", "items": { "type": "string", "pattern": "^rmk_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "remark id" }, "description": "Reservations this call recorded" }, "simulation": { "$ref": "#/components/schemas/Simulation" } }, "required": [ "shipment_id", "action", "status", "signature_ids", "remark_ids", "simulation" ] }, "Simulation": { "type": [ "object", "null" ], "properties": { "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "status": { "type": "string", "enum": [ "draft", "issued", "in_transit", "delivered", "completed", "cancelled" ], "description": "Lifecycle status" }, "auto": { "type": "boolean", "description": "Whether an auto-advance run was started for this shipment" }, "instance_id": { "type": [ "string", "null" ], "description": "Id of the SANDBOX_ADVANCE workflow instance, when one was started" }, "workflow_status": { "type": [ "string", "null" ], "description": "What the Workflows engine reports about that instance" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "issue", "pickup_signature", "remark", "delivery_signature" ] }, "event": { "type": "string", "description": "The event that proves this step ran" }, "done": { "type": "boolean" }, "at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the step ran, or null while it has not" } }, "required": [ "name", "event", "done", "at" ], "description": "A step of the sandbox auto-advance run" }, "description": "The run in order, oldest step first" }, "done": { "type": "boolean", "description": "True once the shipment is delivered" } }, "required": [ "shipment_id", "status", "auto", "instance_id", "workflow_status", "steps", "done" ], "description": "The progress projection, for action `auto`; null for the other actions" }, "Simulate": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "sign", "deliver", "remark", "auto" ], "description": "What the sandbox should do to this shipment" }, "role": { "type": "string", "enum": [ "consignor", "carrier", "consignee" ], "description": "Action `sign`: who signs; defaults to the role the status expects next" }, "type": { "type": "string", "enum": [ "damage", "shortage", "delay", "other" ], "default": "damage", "description": "Action `remark`: the kind of reservation to record" } }, "required": [ "action" ] }, "Tour": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tor_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "tour id" }, "status": { "type": "string", "enum": [ "planned", "active", "completed", "cancelled" ], "description": "Status of a tour" }, "reference": { "type": [ "string", "null" ] }, "driver": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "description": "Used for SMS sign requests and the driver overview" }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of the signing flow and documents" } }, "required": [ "name" ], "description": "Who drives it; `phone` is what the driver overview matches on" }, "vehicle": { "type": [ "object", "null" ], "properties": { "plate": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Registration plate of the tractor or truck" }, "trailer_plate": { "type": "string", "maxLength": 20 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of registration" }, "equipment_category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the load unit named in trailer_plate" } }, "required": [ "plate" ], "description": "Vehicle" }, "planned_date": { "type": [ "string", "null" ] }, "stops": { "type": "array", "items": { "type": "object", "properties": { "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "type": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "Kind of stop" }, "position": { "type": "integer", "minimum": 1 }, "done": { "type": "boolean" } }, "required": [ "shipment_id", "type", "position", "done" ], "description": "One stop of a tour, as the API returns it" } }, "progress": { "type": "object", "properties": { "done": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } }, "required": [ "done", "total" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "reference", "driver", "planned_date", "stops", "progress", "created_at", "updated_at" ] }, "TourCreate": { "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Your own name for this run" }, "driver": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "description": "Used for SMS sign requests and the driver overview" }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of the signing flow and documents" } }, "required": [ "name" ], "description": "Who drives it; `phone` is what the driver overview matches on" }, "vehicle": { "type": "object", "properties": { "plate": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Registration plate of the tractor or truck" }, "trailer_plate": { "type": "string", "maxLength": 20 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of registration" }, "equipment_category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the load unit named in trailer_plate" } }, "required": [ "plate" ], "description": "Vehicle" }, "planned_date": { "type": "string", "format": "date", "description": "The day this tour is driven, as `YYYY-MM-DD`" }, "stops": { "type": "array", "items": { "type": "object", "properties": { "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "type": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "Kind of stop" } }, "required": [ "shipment_id", "type" ], "description": "One stop of a tour" }, "minItems": 1, "maxItems": 50 } }, "required": [ "driver", "stops" ], "description": "A new tour" }, "TourList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tour" } } }, "required": [ "data" ] }, "TourPatch": { "type": "object", "properties": { "reference": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100 }, "driver": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "description": "Used for SMS sign requests and the driver overview" }, "email": { "type": "string", "format": "email", "description": "E-mail address" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of the signing flow and documents" } }, "required": [ "name" ], "description": "Driver" }, "vehicle": { "type": [ "object", "null" ], "properties": { "plate": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Registration plate of the tractor or truck" }, "trailer_plate": { "type": "string", "maxLength": 20 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of registration" }, "equipment_category": { "type": "string", "enum": [ "AE", "AM", "BPO", "BPP", "BPQ", "BPR", "BPX", "BR", "BX", "CN", "DPL", "RF", "RR", "SM", "SW", "TE", "TN", "T1", "T2", "T3", "T4", "T5", "T6", "T7", "T9", "T10", "T11", "T12", "T13", "T14", "DV", "GT", "CT", "NT" ], "description": "Category of the load unit named in trailer_plate" } }, "required": [ "plate" ], "description": "Vehicle" }, "planned_date": { "type": [ "string", "null" ], "format": "date" }, "stops": { "type": "array", "items": { "type": "object", "properties": { "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "type": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "Kind of stop" } }, "required": [ "shipment_id", "type" ], "description": "One stop of a tour" }, "minItems": 1, "maxItems": 50 }, "status": { "type": "string", "enum": [ "planned", "active", "completed", "cancelled" ], "description": "Status of a tour" } }, "description": "Changes to a tour" }, "DriverOtpSent": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "sent" ], "description": "Always `sent`: an unknown number answers exactly like a known one" }, "resend_in_seconds": { "type": "integer", "exclusiveMinimum": 0, "description": "Wait at least this long before asking for another code" } }, "required": [ "status", "resend_in_seconds" ] }, "DriverPhoneBody": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 4, "maxLength": 24, "description": "The mobile number the shipments name as `driver.phone`, ideally in E.164" } }, "required": [ "phone" ] }, "DriverSession": { "type": "object", "properties": { "token": { "type": "string", "description": "The session token; send it as `Authorization: Bearer`. Shown exactly once" }, "phone": { "type": "string", "description": "The number this session is scoped to" }, "mode": { "type": "string", "enum": [ "test", "live" ], "description": "The mode this session is scoped to. It follows from the work the number does — live when it drives on a live consignment note — and never from the request" }, "expires_at": { "type": "string", "format": "date-time", "description": "Twelve hours out; the session cannot outlive it" } }, "required": [ "token", "phone", "mode", "expires_at" ] }, "DriverOtpVerifyBody": { "allOf": [ { "$ref": "#/components/schemas/DriverPhoneBody" }, { "type": "object", "properties": { "code": { "type": "string", "pattern": "^\\d{6}$", "description": "The code from the text message" } }, "required": [ "code" ] } ] }, "DriverShipmentList": { "type": "object", "properties": { "driver": { "type": "object", "properties": { "phone": { "type": "string", "description": "Phone number in E.164 format, for example +31612345678" }, "mode": { "type": "string", "enum": [ "test", "live" ], "description": "The mode of the session, and therefore of every row below. A sandbox list holds nothing real and an app should say so" } }, "required": [ "phone", "mode" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DriverShipment" }, "description": "Open shipments in this mode, earliest window first" }, "tours": { "type": "array", "items": { "$ref": "#/components/schemas/DriverTour" }, "description": "The runs the shipments above belong to, plus any run planned on this number. A shipment named by none of them is a single ride and stands on its own" } }, "required": [ "driver", "data", "tours" ] }, "DriverShipment": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "status": { "type": "string", "enum": [ "draft", "issued", "in_transit", "delivered", "completed", "cancelled" ], "description": "Lifecycle status" }, "reference": { "type": "string" }, "organization": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "description": "The Cargofollow customer whose consignment note this is: who is asking for the signature" }, "consignor": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "consignee": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "pickup": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "instructions": { "type": "string", "description": "Instructions for the driver, when the note has any" } }, "required": [ "address" ] }, "delivery": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Street and house number" }, "additional": { "type": "string", "maxLength": 200, "description": "Second address line (building, unit, c/o)" }, "department": { "type": "string", "maxLength": 120, "description": "Department or division at this address, for example \"Goods inwards\"" }, "po_box": { "type": "string", "maxLength": 20, "description": "Post office box, when post goes there instead of to the street address" }, "postal_code": { "type": "string", "maxLength": 20, "description": "Postal code; some countries have none" }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country_subdivision": { "type": "string", "maxLength": 120, "description": "Province, region or state within the country, by name and not by code" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code, upper case" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ], "description": "WGS 84 coordinates" } }, "required": [ "street", "city", "country" ], "description": "Postal address" }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window; omitted means a point in time" } }, "required": [ "from" ], "description": "Time window" }, "instructions": { "type": "string", "description": "Instructions for the driver, when the note has any" } }, "required": [ "address" ] }, "role": { "type": "string", "enum": [ "consignor", "carrier", "consignee" ], "description": "The signature this stop needs next: `carrier` at loading, `consignee` at delivery" }, "planned_at": { "type": "string", "format": "date-time", "description": "Start of the window that is next for this shipment; the list is sorted on it" }, "sign_url": { "type": "string", "format": "uri", "description": "The flow to open for this shipment, valid for the life of the session. Absent when the role has already signed" } }, "required": [ "id", "status", "organization", "consignor", "consignee", "pickup", "delivery", "role" ] }, "DriverTour": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tor_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "tour id" }, "reference": { "type": [ "string", "null" ], "description": "The planner's own name for this run" }, "status": { "type": "string", "enum": [ "planned", "active", "completed", "cancelled" ], "description": "Status of a tour" }, "planned_date": { "type": [ "string", "null" ], "description": "The day it is driven, as `YYYY-MM-DD`" }, "stops": { "type": "array", "items": { "type": "object", "properties": { "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "type": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "Kind of stop" }, "position": { "type": "integer", "minimum": 1 }, "done": { "type": "boolean" } }, "required": [ "shipment_id", "type", "position", "done" ], "description": "One stop of a tour, as the API returns it" }, "description": "Every stop of the tour, in the order the planner put them in" }, "progress": { "type": "object", "properties": { "done": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } }, "required": [ "done", "total" ] } }, "required": [ "id", "reference", "status", "planned_date", "stops", "progress" ] }, "EftiDataset": { "type": "object", "properties": { "dataset_id": { "type": "string", "pattern": "^eft_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "efti dataset id" }, "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "dataset_uuid": { "type": "string", "format": "uuid" }, "subset": { "type": [ "string", "null" ], "description": "The subset that was projected, null for the common set" }, "lifecycle": { "type": "string", "enum": [ "active", "inactive", "ready_to_archive", "archived" ], "description": "eFTI dataset lifecycle state" }, "document": { "type": "object", "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "schema_version": { "type": "string" }, "consignment": { "type": "object", "additionalProperties": {} } }, "required": [ "dataset_id", "schema_version", "consignment" ], "description": "The JSON mirror of the eFTI XML: the same element names, order and omissions as the document `Accept: application/xml` returns" }, "validation": { "$ref": "#/components/schemas/EftiValidation" }, "xml_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the XML this response represents" } }, "required": [ "dataset_id", "shipment_id", "dataset_uuid", "subset", "lifecycle", "document", "validation", "xml_hash" ] }, "EftiValidation": { "type": "object", "properties": { "ok": { "type": "boolean" }, "unmapped": { "type": "array", "items": { "$ref": "#/components/schemas/EftiUnmappedElement" } }, "missing_required": { "type": "array", "items": { "$ref": "#/components/schemas/EftiMissingElement" } } }, "required": [ "ok", "unmapped", "missing_required" ] }, "EftiUnmappedElement": { "type": "object", "properties": { "path": { "type": "string", "description": "Path in the common data set, rooted at `consignment`" }, "efti_id": { "type": "string" }, "reason": { "type": "string", "description": "Why the canonical model cannot carry it" } }, "required": [ "path", "efti_id", "reason" ] }, "EftiMissingElement": { "type": "object", "properties": { "path": { "type": "string", "description": "Path in the common data set, rooted at `consignment`" }, "efti_id": { "type": "string", "description": "Element identifier of the publication, for example `eFTI61`" }, "status": { "type": "string", "description": "Status letters of the subset publication (`M`, `C/M`)" } }, "required": [ "path", "efti_id", "status" ] }, "Uil": { "type": "object", "properties": { "dataset_id": { "type": [ "string", "null" ], "pattern": "^eft_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "efti dataset id" }, "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "dataset_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "The dataset UUID, third component of the UIL" }, "lifecycle": { "type": [ "string", "null" ], "enum": [ "active", "inactive", "ready_to_archive", "archived", null ], "description": "eFTI dataset lifecycle state" }, "uil": { "type": [ "object", "null" ], "properties": { "gate_id": { "type": "string", "minLength": 1, "maxLength": 64 }, "platform_id": { "type": "string", "minLength": 1, "maxLength": 64 }, "dataset_id": { "type": "string", "format": "uuid" } }, "required": [ "gate_id", "platform_id", "dataset_id" ], "description": "Null until the carrier signs; the UIL is issued at that signature" }, "uil_string": { "type": [ "string", "null" ], "description": "The UIL as `::`, for a log line or a QR payload" }, "xml_hash": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the CMDS XML that was rendered when the UIL was issued" }, "issued_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the UIL was issued; null while no UIL exists" } }, "required": [ "dataset_id", "shipment_id", "dataset_uuid", "lifecycle", "uil", "uil_string", "issued_at" ] }, "EftiAuthorisationList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EftiAuthorisation" } }, "dataset_uuid": { "type": [ "string", "null" ], "description": "UUID of the eFTI CMDS these rights are about, once the data set exists" } }, "required": [ "data", "dataset_uuid" ] }, "EftiAuthorisation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^atz_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "efti authorisation id" }, "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "dataset_uuid": { "type": [ "string", "null" ] }, "party": { "$ref": "#/components/schemas/EftiParty" }, "role": { "type": "string", "enum": [ "data_holder", "consignor", "carrier", "consignee", "authority", "other" ] }, "operations": { "type": "array", "items": { "type": "string", "enum": [ "create", "edit", "read", "download", "consignor_signature", "carrier_signature", "consignee_signature", "combined_transport_stamp", "archive", "waste_documents_download", "waste_carrier_confirmation" ] } }, "data_scope": { "type": "array", "items": { "type": "string" }, "description": "Coded element groups the right covers; `*` is the whole common data set" }, "valid_from": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "valid_until": { "type": [ "string", "null" ], "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "authoriser": { "type": [ "string", "null" ], "enum": [ "primary", "temporary", null ] }, "notify": { "type": "boolean" }, "source": { "type": "string", "enum": [ "baseline", "granted", "derived" ] }, "status": { "type": "string", "enum": [ "active", "scheduled", "expired", "revoked" ] }, "granted_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "granted_by": { "allOf": [ { "$ref": "#/components/schemas/EftiParty" }, { "type": [ "object", "null" ] } ] }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "revoked_by": { "allOf": [ { "$ref": "#/components/schemas/EftiParty" }, { "type": [ "object", "null" ] } ] }, "revoked_reason": { "type": [ "string", "null" ] } }, "required": [ "id", "shipment_id", "dataset_uuid", "party", "role", "operations", "data_scope", "valid_from", "valid_until", "authoriser", "notify", "source", "status", "granted_at", "granted_by", "revoked_at", "revoked_by", "revoked_reason" ] }, "EftiParty": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization", "member", "api_key", "contact", "authority" ], "description": "What kind of party holds the right" }, "ref": { "type": "string", "description": "Coded reference of the party (Art. 5(3)(a))" }, "label": { "type": [ "string", "null" ] }, "contact": { "type": [ "string", "null" ], "description": "Contact detail of a non-onboarded user (Art. 5(5)(a)(i))" } }, "required": [ "type", "ref", "label", "contact" ] }, "EftiAuthorisationGrant": { "type": "object", "properties": { "party_type": { "type": "string", "enum": [ "organization", "member", "api_key", "contact", "authority" ] }, "party_ref": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Id of the organisation, member or key; required for an onboarded party" }, "email": { "type": "string", "format": "email", "description": "Contact detail of a non-onboarded user" }, "phone": { "type": "string", "maxLength": 20, "description": "Contact detail of a non-onboarded user, E.164" }, "label": { "type": "string", "maxLength": 200 }, "role": { "type": "string", "enum": [ "data_holder", "consignor", "carrier", "consignee", "authority", "other" ] }, "operations": { "type": "array", "items": { "type": "string", "enum": [ "create", "edit", "read", "download", "consignor_signature", "carrier_signature", "consignee_signature", "combined_transport_stamp", "archive", "waste_documents_download", "waste_carrier_confirmation" ] }, "minItems": 1, "description": "Defaults to the operations the role needs" }, "data_scope": { "type": "array", "items": { "type": "string", "maxLength": 20 }, "minItems": 1, "maxItems": 40 }, "valid_from": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "valid_until": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" }, "notify": { "type": "boolean" }, "authoriser": { "type": "string", "enum": [ "primary", "temporary" ] } }, "required": [ "party_type", "role" ] }, "EftiAuthorisationRevocation": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } } }, "EftiProcessingLog": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EftiProcessingEntry" } } }, "required": [ "data" ] }, "EftiProcessingEntry": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epl_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "efti processing entry id" }, "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "dataset_uuid": { "type": [ "string", "null" ] }, "operation": { "type": "string", "enum": [ "create", "edit", "read", "download", "consignor_signature", "carrier_signature", "consignee_signature", "combined_transport_stamp", "archive", "waste_documents_download", "waste_carrier_confirmation" ] }, "party": { "$ref": "#/components/schemas/EftiParty" }, "authorisation_id": { "type": [ "string", "null" ], "pattern": "^atz_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "efti authorisation id" }, "data_scope": { "type": "array", "items": { "type": "string" } }, "outcome": { "type": "string", "enum": [ "allowed", "refused" ] }, "request_ref": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp with time zone" } }, "required": [ "id", "shipment_id", "dataset_uuid", "operation", "party", "authorisation_id", "data_scope", "outcome", "request_ref", "created_at" ] }, "CombinedTransportStamp": { "type": "object", "properties": { "leg": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "rail", "inland_waterway", "sea" ], "description": "Mode of the non-road leg the stamp confirms" }, "loading": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 17, "description": "UN/LOCODE or terminal code of the station or port" }, "name": { "type": "string", "minLength": 1, "maxLength": 35, "description": "Name of the station or port" } }, "required": [ "name" ], "description": "Where the unit left the road" }, "unloading": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 17, "description": "UN/LOCODE or terminal code of the station or port" }, "name": { "type": "string", "minLength": 1, "maxLength": 35, "description": "Name of the station or port" } }, "required": [ "name" ], "description": "Where the unit returned to the road" } }, "required": [ "mode", "loading", "unloading" ], "description": "The non-road leg of a combined transport operation (Directive 92/106/EEC Art. 3)" }, "stamped_by": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 70, "description": "Railway or port authority that affixed the stamp" }, "id": { "type": "string", "minLength": 1, "maxLength": 17, "description": "Registration number of that authority" } }, "required": [ "name" ], "description": "The authority that affixed the combined transport stamp" }, "stamped_at": { "type": "string", "format": "date-time", "description": "When the authority affixed the stamp" }, "reference": { "type": "string", "minLength": 1, "maxLength": 35, "description": "The number the authority put on the stamp, when it uses one" }, "id": { "type": "string", "pattern": "^cts_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "combined transport stamp id" }, "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "created_at": { "type": "string", "format": "date-time", "description": "When Cargofollow recorded the stamp" } }, "required": [ "leg", "stamped_by", "stamped_at", "id", "shipment_id", "created_at" ], "description": "Combined transport stamp (Directive 92/106/EEC Art. 3)" }, "CombinedTransportStampCreate": { "type": "object", "properties": { "leg": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "rail", "inland_waterway", "sea" ], "description": "Mode of the non-road leg the stamp confirms" }, "loading": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 17, "description": "UN/LOCODE or terminal code of the station or port" }, "name": { "type": "string", "minLength": 1, "maxLength": 35, "description": "Name of the station or port" } }, "required": [ "name" ], "description": "Where the unit left the road" }, "unloading": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 17, "description": "UN/LOCODE or terminal code of the station or port" }, "name": { "type": "string", "minLength": 1, "maxLength": 35, "description": "Name of the station or port" } }, "required": [ "name" ], "description": "Where the unit returned to the road" } }, "required": [ "mode", "loading", "unloading" ], "description": "The non-road leg of a combined transport operation (Directive 92/106/EEC Art. 3)" }, "stamped_by": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 70, "description": "Railway or port authority that affixed the stamp" }, "id": { "type": "string", "minLength": 1, "maxLength": 17, "description": "Registration number of that authority" } }, "required": [ "name" ], "description": "The authority that affixed the combined transport stamp" }, "stamped_at": { "type": "string", "format": "date-time", "description": "When the authority affixed the stamp" }, "reference": { "type": "string", "minLength": 1, "maxLength": 35, "description": "The number the authority put on the stamp, when it uses one" } }, "required": [ "leg", "stamped_by", "stamped_at" ], "description": "A combined transport stamp to record" }, "CombinedTransportStampList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CombinedTransportStamp" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Always null: a combined transport has a handful of legs, so the list is complete" } }, "required": [ "data", "next_cursor" ] }, "Export": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^exp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "export job id" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ], "description": "`pending` until the Workflow picks it up, then `running`" }, "mode": { "type": "string", "enum": [ "test", "live" ], "description": "Data mode; follows from the API key" }, "since": { "type": [ "string", "null" ] }, "until": { "type": [ "string", "null" ] }, "requested_at": { "type": "string" }, "completed_at": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "description": "When the zip and this status are deleted; seven days" }, "shipment_count": { "type": "integer" }, "document_count": { "type": "integer" }, "size": { "type": "integer", "description": "Size of the zip in bytes; 0 while it is being built" }, "truncated": { "type": "boolean", "description": "True when the export stopped at 10000 shipments; narrow the window with since/until" }, "download_url": { "type": [ "string", "null" ], "description": "Signed URL for the zip, valid for one hour; null until the export is completed" }, "error": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "mode", "since", "until", "requested_at", "completed_at", "expires_at", "shipment_count", "document_count", "size", "truncated", "download_url", "error" ] }, "Usage": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "test", "live" ], "description": "The mode the key belongs to; test-mode usage is free" }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "First day in the answer, inclusive" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Last day in the answer, inclusive" }, "billable": { "type": "boolean", "description": "False in test mode: the sandbox is free without a limit in time" }, "tier": { "type": "string", "enum": [ "sandbox", "starter", "scale", "enterprise" ], "description": "The tier the organisation is on" }, "totals": { "type": "object", "properties": { "shipments_issued": { "type": "integer", "minimum": 0, "description": "Shipments that were issued" }, "signatures": { "type": "integer", "minimum": 0, "description": "Signatures and seals recorded" }, "notifications": { "type": "integer", "minimum": 0, "description": "E-mails and SMS sent" }, "documents": { "type": "integer", "minimum": 0, "description": "Documents stored" }, "storage_bytes": { "type": "integer", "minimum": 0, "description": "Bytes the stored documents occupy at the end of the day" } }, "required": [ "shipments_issued", "signatures", "notifications", "documents", "storage_bytes" ], "description": "The counters of the window added up; `storage_bytes` is the level on the last day, not a sum" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDay" }, "description": "Oldest first; a day without traffic is absent" } }, "required": [ "mode", "from", "to", "billable", "tier", "totals", "days" ] }, "UsageDay": { "type": "object", "properties": { "shipments_issued": { "type": "integer", "minimum": 0, "description": "Shipments that were issued" }, "signatures": { "type": "integer", "minimum": 0, "description": "Signatures and seals recorded" }, "notifications": { "type": "integer", "minimum": 0, "description": "E-mails and SMS sent" }, "documents": { "type": "integer", "minimum": 0, "description": "Documents stored" }, "storage_bytes": { "type": "integer", "minimum": 0, "description": "Bytes the stored documents occupy at the end of the day" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC day as YYYY-MM-DD" }, "computed_at": { "type": "string", "format": "date-time", "description": "When the aggregation last rebuilt this day" } }, "required": [ "shipments_issued", "signatures", "notifications", "documents", "storage_bytes", "day", "computed_at" ] }, "BillingWebhookResult": { "type": "object", "properties": { "received": { "type": "boolean", "description": "The signature held and the body was read" }, "applied": { "type": "boolean", "description": "Whether the event changed the billing account" }, "reason": { "type": "string", "enum": [ "applied", "unknown_customer", "no_customer", "duplicate", "ignored_type" ], "description": "Why it did or did not change anything" } }, "required": [ "received", "applied", "reason" ] }, "ProviderWebhookResult": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "eCMR provider that executes the consignment" }, "received": { "type": "integer", "minimum": 0, "description": "Events the adapter read from the request" }, "applied": { "type": "array", "items": { "type": "object", "properties": { "shipment_id": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment id" }, "event_id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "shipment event id" }, "type": { "type": "string", "enum": [ "shipment.created", "shipment.issued", "shipment.updated", "shipment.cancelled", "shipment.pickup_signed", "shipment.delivered", "shipment.completed", "signature.completed", "document.created", "remark.added", "inspection.viewed", "provider.sync_failed", "efti.uil_issued", "efti.authority_access", "efti.combined_transport_stamped" ] } }, "required": [ "shipment_id", "event_id", "type" ] }, "description": "Shipment events written, in order" } }, "required": [ "provider", "received", "applied" ] } }, "parameters": {} }, "paths": { "/healthz": { "get": { "tags": [ "system" ], "summary": "Liveness and binding check", "description": "Probes D1, KV and R2. Returns 503 with the failing check when a binding is down.", "security": [], "responses": { "200": { "description": "All bindings answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "503": { "description": "A binding failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/version": { "get": { "tags": [ "system" ], "summary": "API and schema version", "security": [], "responses": { "200": { "description": "Version information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } } } } }, "/v1/shipments/validate": { "post": { "tags": [ "shipments" ], "summary": "Validate a shipment without creating it", "description": "Runs exactly the validation of `POST /v1/shipments` and writes nothing: no shipment, no version, no event. Business-rule findings come back in the 200 body; a body the canonical model itself rejects answers 422, just as it would on a create.", "requestBody": { "required": true, "content": { "application/json": { "examples": { "nl-de": { "summary": "International carriage Rotterdam → Stuttgart", "description": "Plain road consignment with a Polish carrier; `transport_type` is derived.", "value": { "reference": "ORD-2026-0917", "consignor": { "name": "Van der Berg Logistiek B.V.", "address": { "street": "Havenweg 12", "postal_code": "3089 JG", "city": "Rotterdam", "country": "NL" }, "contact": { "name": "S. Jansen", "email": "planning@vdb-logistiek.example", "phone": "+31101234567", "language": "nl" }, "vat_number": "NL001234567B01" }, "carrier": { "name": "Transport Nowak Sp. z o.o.", "address": { "street": "ul. Przemysłowa 8", "postal_code": "61-001", "city": "Poznań", "country": "PL" }, "contact": { "phone": "+48601234567" } }, "consignee": { "name": "Müller Maschinenbau GmbH", "address": { "street": "Industriestraße 4", "postal_code": "70565", "city": "Stuttgart", "country": "DE" }, "contact": { "name": "K. Müller", "email": "wareneingang@mueller-mb.example" } }, "pickup": { "address": { "street": "Havenweg 12", "postal_code": "3089 JG", "city": "Rotterdam", "country": "NL" }, "window": { "from": "2026-09-14T08:00:00+02:00", "to": "2026-09-14T12:00:00+02:00" }, "instructions": "Report at gate 3" }, "delivery": { "address": { "street": "Industriestraße 4", "postal_code": "70565", "city": "Stuttgart", "country": "DE" }, "window": { "from": "2026-09-15T07:00:00+02:00", "to": "2026-09-15T16:00:00+02:00" }, "contact": { "name": "Wareneingang", "phone": "+4971112345678" } }, "goods": [ { "description": "CNC machine parts", "marks": "MM-4471", "quantity": 12, "package_type": "pallet", "gross_weight_kg": 8400, "volume_m3": 14.2, "hs_code": "84669390" } ], "vehicle": { "plate": "PO 12345", "trailer_plate": "PO 98765", "country": "PL" }, "driver": { "name": "Marek Nowak", "phone": "+48601234568", "language": "pl" }, "charges": { "carriage": { "amount": "1250.00", "currency": "EUR" }, "payer": "consignor" }, "special_agreements": "Temperature not controlled", "metadata": { "tms_order": "4711" } } }, "adr": { "summary": "Dangerous goods under ADR", "description": "Same corridor with UN 1263; the ADR particulars are business rules, not schema.", "value": { "reference": "ORD-2026-0918", "consignor": { "name": "Van der Berg Logistiek B.V.", "address": { "street": "Havenweg 12", "postal_code": "3089 JG", "city": "Rotterdam", "country": "NL" }, "contact": { "name": "S. Jansen", "email": "planning@vdb-logistiek.example", "phone": "+31101234567", "language": "nl" }, "vat_number": "NL001234567B01" }, "carrier": { "name": "Transport Nowak Sp. z o.o.", "address": { "street": "ul. Przemysłowa 8", "postal_code": "61-001", "city": "Poznań", "country": "PL" }, "contact": { "phone": "+48601234567" } }, "consignee": { "name": "Müller Maschinenbau GmbH", "address": { "street": "Industriestraße 4", "postal_code": "70565", "city": "Stuttgart", "country": "DE" }, "contact": { "name": "K. Müller", "email": "wareneingang@mueller-mb.example" } }, "pickup": { "address": { "street": "Havenweg 12", "postal_code": "3089 JG", "city": "Rotterdam", "country": "NL" }, "window": { "from": "2026-09-14T08:00:00+02:00", "to": "2026-09-14T12:00:00+02:00" }, "instructions": "Report at gate 3" }, "delivery": { "address": { "street": "Industriestraße 4", "postal_code": "70565", "city": "Stuttgart", "country": "DE" }, "window": { "from": "2026-09-15T07:00:00+02:00", "to": "2026-09-15T16:00:00+02:00" }, "contact": { "name": "Wareneingang", "phone": "+4971112345678" } }, "goods": [ { "description": "Paint, flammable liquid", "marks": "VDB-8891", "quantity": 4, "package_type": "drum", "gross_weight_kg": 760, "adr": { "un_number": "1263", "class": "3", "packing_group": "III", "proper_shipping_name": "PAINT", "tunnel_code": "(D/E)" } } ], "vehicle": { "plate": "PO 12345", "trailer_plate": "PO 98765", "country": "PL" }, "driver": { "name": "Marek Nowak", "phone": "+48601234568", "language": "pl" }, "charges": { "carriage": { "amount": "1250.00", "currency": "EUR" }, "payer": "consignor" }, "special_agreements": "Temperature not controlled", "metadata": { "tms_order": "4711" }, "documents_attached": [ "ADR transport document" ] } } }, "schema": { "$ref": "#/components/schemas/ShipmentInput" } } } }, "responses": { "200": { "description": "The findings a create would produce", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResult" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The body does not match the canonical model", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments": { "post": { "tags": [ "shipments" ], "summary": "Create a shipment", "description": "Validates the body against the canonical model and the business-rule register, then stores the shipment as a draft with version 1 and appends `shipment.created` to its hash chain. Rules of severity `error` answer 422; rules of severity `warning` come back in `warnings[]` on the 201. `transport_type` is derived from the countries when omitted and `provider` falls back to the organisation default. With `issue: true` the shipment is issued in the same call: the `issue` rules run as well, nothing is stored when one of them blocks, and the response carries `status: issued` with `shipment.issued` as the second event. Send `Idempotency-Key` to make a retry safe. A body of `{ \"format\": \"olf\", \"import\": { … } }` imports an Open Logistics Foundation eCMR instead (M4-10); the shipment is stored canonically and the OLF document comes back from `GET /v1/shipments/{id}/documents?kind=other`.", "requestBody": { "required": true, "content": { "application/json": { "examples": { "nl-de": { "summary": "International carriage Rotterdam → Stuttgart", "description": "Plain road consignment with a Polish carrier; `transport_type` is derived.", "value": { "reference": "ORD-2026-0917", "consignor": { "name": "Van der Berg Logistiek B.V.", "address": { "street": "Havenweg 12", "postal_code": "3089 JG", "city": "Rotterdam", "country": "NL" }, "contact": { "name": "S. Jansen", "email": "planning@vdb-logistiek.example", "phone": "+31101234567", "language": "nl" }, "vat_number": "NL001234567B01" }, "carrier": { "name": "Transport Nowak Sp. z o.o.", "address": { "street": "ul. Przemysłowa 8", "postal_code": "61-001", "city": "Poznań", "country": "PL" }, "contact": { "phone": "+48601234567" } }, "consignee": { "name": "Müller Maschinenbau GmbH", "address": { "street": "Industriestraße 4", "postal_code": "70565", "city": "Stuttgart", "country": "DE" }, "contact": { "name": "K. Müller", "email": "wareneingang@mueller-mb.example" } }, "pickup": { "address": { "street": "Havenweg 12", "postal_code": "3089 JG", "city": "Rotterdam", "country": "NL" }, "window": { "from": "2026-09-14T08:00:00+02:00", "to": "2026-09-14T12:00:00+02:00" }, "instructions": "Report at gate 3" }, "delivery": { "address": { "street": "Industriestraße 4", "postal_code": "70565", "city": "Stuttgart", "country": "DE" }, "window": { "from": "2026-09-15T07:00:00+02:00", "to": "2026-09-15T16:00:00+02:00" }, "contact": { "name": "Wareneingang", "phone": "+4971112345678" } }, "goods": [ { "description": "CNC machine parts", "marks": "MM-4471", "quantity": 12, "package_type": "pallet", "gross_weight_kg": 8400, "volume_m3": 14.2, "hs_code": "84669390" } ], "vehicle": { "plate": "PO 12345", "trailer_plate": "PO 98765", "country": "PL" }, "driver": { "name": "Marek Nowak", "phone": "+48601234568", "language": "pl" }, "charges": { "carriage": { "amount": "1250.00", "currency": "EUR" }, "payer": "consignor" }, "special_agreements": "Temperature not controlled", "metadata": { "tms_order": "4711" } } }, "adr": { "summary": "Dangerous goods under ADR", "description": "Same corridor with UN 1263; the ADR particulars are business rules, not schema.", "value": { "reference": "ORD-2026-0918", "consignor": { "name": "Van der Berg Logistiek B.V.", "address": { "street": "Havenweg 12", "postal_code": "3089 JG", "city": "Rotterdam", "country": "NL" }, "contact": { "name": "S. Jansen", "email": "planning@vdb-logistiek.example", "phone": "+31101234567", "language": "nl" }, "vat_number": "NL001234567B01" }, "carrier": { "name": "Transport Nowak Sp. z o.o.", "address": { "street": "ul. Przemysłowa 8", "postal_code": "61-001", "city": "Poznań", "country": "PL" }, "contact": { "phone": "+48601234567" } }, "consignee": { "name": "Müller Maschinenbau GmbH", "address": { "street": "Industriestraße 4", "postal_code": "70565", "city": "Stuttgart", "country": "DE" }, "contact": { "name": "K. Müller", "email": "wareneingang@mueller-mb.example" } }, "pickup": { "address": { "street": "Havenweg 12", "postal_code": "3089 JG", "city": "Rotterdam", "country": "NL" }, "window": { "from": "2026-09-14T08:00:00+02:00", "to": "2026-09-14T12:00:00+02:00" }, "instructions": "Report at gate 3" }, "delivery": { "address": { "street": "Industriestraße 4", "postal_code": "70565", "city": "Stuttgart", "country": "DE" }, "window": { "from": "2026-09-15T07:00:00+02:00", "to": "2026-09-15T16:00:00+02:00" }, "contact": { "name": "Wareneingang", "phone": "+4971112345678" } }, "goods": [ { "description": "Paint, flammable liquid", "marks": "VDB-8891", "quantity": 4, "package_type": "drum", "gross_weight_kg": 760, "adr": { "un_number": "1263", "class": "3", "packing_group": "III", "proper_shipping_name": "PAINT", "tunnel_code": "(D/E)" } } ], "vehicle": { "plate": "PO 12345", "trailer_plate": "PO 98765", "country": "PL" }, "driver": { "name": "Marek Nowak", "phone": "+48601234568", "language": "pl" }, "charges": { "carriage": { "amount": "1250.00", "currency": "EUR" }, "payer": "consignor" }, "special_agreements": "Temperature not controlled", "metadata": { "tms_order": "4711" }, "documents_attached": [ "ADR transport document" ] } } }, "schema": { "$ref": "#/components/schemas/ShipmentCreateRequest" } } } }, "responses": { "201": { "description": "The created shipment", "headers": { "location": { "schema": { "type": "string", "description": "URL of the created shipment" }, "required": true, "description": "URL of the created shipment" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The body or a business rule rejects the shipment", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "get": { "tags": [ "shipments" ], "summary": "List shipments", "description": "Newest first, `limit` per page (1 to 100, default 50). Filters combine; `created_after` and `created_before` are inclusive. Follow `next_cursor` until it is null: the cursor is opaque and a page never repeats or skips a shipment created while you page. Each item is the full shipment with its current version and the warnings of its current content.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Page size, 1 to 100" }, "required": false, "description": "Page size, 1 to 100", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The `next_cursor` of the previous page; opaque" }, "required": false, "description": "The `next_cursor` of the previous page; opaque", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "draft", "issued", "in_transit", "delivered", "completed", "cancelled" ], "description": "Only shipments in this status" }, "required": false, "description": "Only shipments in this status", "name": "status", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Exact match on `reference`" }, "required": false, "description": "Exact match on `reference`", "name": "reference", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 30, "description": "Exact match on `driver.phone`" }, "required": false, "description": "Exact match on `driver.phone`", "name": "driver_phone", "in": "query" }, { "schema": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "Only shipments routed to this provider" }, "required": false, "description": "Only shipments routed to this provider", "name": "provider", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound on `created_at`" }, "required": false, "description": "Inclusive lower bound on `created_at`", "name": "created_after", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive upper bound on `created_at`" }, "required": false, "description": "Inclusive upper bound on `created_at`", "name": "created_before", "in": "query" } ], "responses": { "200": { "description": "One page of shipments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentList" } } } }, "400": { "description": "The cursor is not one this API issued", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "A query parameter is out of range", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}": { "get": { "tags": [ "shipments" ], "summary": "Retrieve a shipment", "description": "The shipment with its current version, the business-rule warnings of its current content and the links to its sub-resources. A shipment of another organisation or of the other mode is a 404, never a 403.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "patch": { "tags": [ "shipments" ], "summary": "Update a shipment", "description": "A partial update that becomes version n + 1 and appends `shipment.updated` with the paths that changed. An absent field stays, a nested object is replaced as a whole and `null` clears an optional field. In `draft` everything may change and the business rules run again (422 on `error`). In `issued` and `in_transit` only driver, vehicle, time windows, contacts, instructions and metadata may change; a frozen field answers 409 `field_frozen` naming the path. After delivery, completion or cancellation nothing may change (409 `shipment_immutable`). A patch that changes nothing returns the shipment as it is, without a new version.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "driver": { "name": "Marek Nowak", "phone": "+48601234569", "language": "pl" } }, "schema": { "$ref": "#/components/schemas/ShipmentPatch" } } } }, "responses": { "200": { "description": "The updated shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "A frozen field, a shipment that can no longer change, or a concurrent update", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The body or a business rule rejects the update", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "delete": { "tags": [ "shipments" ], "summary": "Delete a shipment and its personal data", "description": "Removes the shipment, its versions, events, signatures, remarks, documents and the document objects in R2, and leaves one entry in the deletion log with the head hash of the chain, so the audit trail survives without personal data. Irreversible; export first if you need the data (`POST /v1/export`). A test-mode shipment can always be deleted. In live mode the shipment has to be `delivered`, `completed` or `cancelled` and at least 30 days past that moment, otherwise the answer is 409 `invalid_state`. Deleting an already deleted shipment answers 404. The nightly retention job does exactly the same for everything past `retention_days`.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The shipment and its data are gone" }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The shipment is still running or was closed less than 30 days ago", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/issue": { "post": { "tags": [ "shipments" ], "summary": "Issue the consignment note", "description": "Moves a draft to `issued`. The business rules of the `issue` phase run once more against the stored content and a rule of severity `error` answers 422; then `issued_at` is set, `shipment.issued` is appended to the hash chain and the fields that freeze at issue (parties, goods, addresses, charges, agreements, transport type, provider) no longer change. Only a draft can be issued: any other status answers 409 `invalid_transition` with `from` and `to` in `errors[0].params`. Send `Idempotency-Key` to make a retry safe.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The issued shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The shipment is not a draft", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "A business rule of the `issue` phase rejects the stored content", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/cancel": { "post": { "tags": [ "shipments" ], "summary": "Cancel a shipment", "description": "Cancels a shipment in status `draft`, `issued` or `in_transit`: the status becomes `cancelled`, `cancelled_at` and `cancel_reason` are set and `shipment.cancelled` carries the reason. A delivered, completed or already cancelled shipment answers 409 `invalid_transition`. Nothing is validated, so cancelling never fails on content. Send `Idempotency-Key` to make a retry safe.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Order withdrawn by the consignor" }, "schema": { "$ref": "#/components/schemas/ShipmentCancel" } } } }, "responses": { "200": { "description": "The cancelled shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The shipment is delivered, completed or already cancelled", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "`reason` is missing, empty or longer than 500 characters", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/events": { "get": { "tags": [ "shipments" ], "summary": "List the events of a shipment", "description": "The hash chain of the shipment in `seq` order: every event exactly as it was hashed, with its `prev_hash` and `hash`, so a client can recompute the links itself (docs/api-conventions.md#integriteit). `GET /v1/shipments/{id}/integrity` does the same server-side.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Page size, 1 to 100" }, "required": false, "description": "Page size, 1 to 100", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The `next_cursor` of the previous page; opaque" }, "required": false, "description": "The `next_cursor` of the previous page; opaque", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "One page of the chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentEventList" } } } }, "400": { "description": "The path parameter is not a shipment id, or the cursor is not one this API issued", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `events:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "A query parameter is invalid", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/integrity": { "get": { "tags": [ "shipments" ], "summary": "Verify the hash chain of a shipment", "description": "Recomputes every link of the chain from the stored events: `prev_hash` has to be the `hash` of the previous event and `hash` has to be `sha256(prev_hash + canonical_json(event))` (docs/api-conventions.md#integriteit). Answers 200 even when the chain does not verify: `ok` says so, `broken_at` names the first `seq` that fails and `seq_gaps` the missing numbers.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The verification report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrityReport" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `events:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/inspection-link": { "get": { "tags": [ "shipments" ], "summary": "Get the inspection link and QR code", "description": "The current link of an issued shipment; a new one is created when there is none or the current one expired. The link lives a year, or 90 days after delivery when that comes first (`settings.inspection_ttl_days` and `settings.inspection_ttl_after_delivery_days` of the organisation override the terms). The QR code encodes `url`.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The current inspection link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectionLink" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The shipment is a draft, or its inspection window after delivery has closed", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/inspection-link/rotate": { "post": { "tags": [ "shipments" ], "summary": "Rotate the inspection link", "description": "Issues a new token and retires the current one: the old URL and QR code answer 410 `token_rotated` from now on. Use it when a printed CMR or a shared link went astray.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "201": { "description": "The new inspection link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectionLink" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The shipment is a draft, or its inspection window after delivery has closed", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/inspection-links/{token_id}/qr.png": { "get": { "tags": [ "shipments" ], "summary": "QR code of an inspection link as PNG", "description": "The QR code that encodes the URL of the token, for print and for the console. Also renders for a rotated token; the page behind it answers 410.", "parameters": [ { "schema": { "type": "string", "example": "ins_01K4Y0000000000000000DEM01", "description": "Inspection token id" }, "required": true, "description": "Inspection token id", "name": "token_id", "in": "path" } ], "responses": { "200": { "description": "The QR code", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The path parameter is not an inspection token id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such inspection token in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/inspection-links/{token_id}/qr.svg": { "get": { "tags": [ "shipments" ], "summary": "QR code of an inspection link as SVG", "description": "The QR code that encodes the URL of the token, for print and for the console. Also renders for a rotated token; the page behind it answers 410.", "parameters": [ { "schema": { "type": "string", "example": "ins_01K4Y0000000000000000DEM01", "description": "Inspection token id" }, "required": true, "description": "Inspection token id", "name": "token_id", "in": "path" } ], "responses": { "200": { "description": "The QR code", "content": { "image/svg+xml": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The path parameter is not an inspection token id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such inspection token in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/pdf": { "get": { "tags": [ "shipments" ], "summary": "Download the current eCMR PDF", "description": "Redirects (302) to the signed download URL of the newest eCMR PDF of this shipment. The link lasts five minutes and needs no API key of its own. A shipment that was never issued has no consignment note yet and answers 404.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "302": { "description": "Redirect to the signed download URL", "headers": { "location": { "schema": { "type": "string", "description": "Signed download URL of the PDF" }, "required": true, "description": "Signed download URL of the PDF" } } }, "400": { "description": "The shipment id is malformed", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `documents:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment, or it has no eCMR PDF yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/provider": { "get": { "tags": [ "shipments" ], "summary": "Provider link and sync state", "description": "What the eCMR provider holds for this shipment: the external id, the sync status, the last operation, the last error and the last step the sync workflow recorded. A shipment that was never issued has no link yet and answers 404 `provider_link_missing`; the trace of every step is also in `GET /v1/shipments/:id/events` as `shipment.updated` with `changed_paths: [\"provider_link\"]`.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The provider link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderLink" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment, or it has no provider link yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/provider/retry": { "post": { "tags": [ "shipments" ], "summary": "Retry the provider synchronisation", "description": "Starts a new run of the provider-sync workflow for the current version, repeating the last operation (`create` when there was none yet, `cancel` for a cancelled shipment). Unlike the automatic triggers this always starts a fresh instance, so it is the way back after a `provider.sync_failed`. The answer is the link as it was before the run; poll `GET /v1/shipments/:id/provider` for the result.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "202": { "description": "The workflow was started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSyncRetry" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The shipment was never issued, so there is nothing to synchronise", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/documents": { "post": { "tags": [ "documents" ], "summary": "Upload a document for a shipment", "description": "Multipart upload straight through the Worker into R2 (jurisdiction eu). The Worker hashes the bytes, derives the mime type from the content and appends a `document.created` event.", "parameters": [ { "schema": { "type": "string", "description": "Shipment id, for example shp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2" }, "required": true, "description": "Shipment id, for example shp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2", "name": "id", "in": "path" } ], "requestBody": { "required": true, "description": "The file and its metadata. At most 26214400 bytes (25 MB).", "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file itself" }, "kind": { "type": "string", "enum": [ "ecmr_pdf", "pod_pdf", "attachment", "signature_image", "photo", "other" ], "description": "What the file is" }, "filename": { "type": "string", "maxLength": 255, "description": "Name shown on download; defaults to the name of the uploaded file" }, "locale": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Language of the document, for a rendered PDF" } }, "required": [ "file", "kind" ] } } } }, "responses": { "201": { "description": "The document was stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "The shipment id is malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks the scope `documents:write`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The file is larger than 26214400 bytes", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "The content is not one of application/pdf, image/jpeg, image/png, image/webp", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "A multipart field is missing or invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "tags": [ "documents" ], "summary": "List the documents of a shipment", "description": "Newest first, optionally filtered by kind. Every item carries a fresh download URL.", "parameters": [ { "schema": { "type": "string", "description": "Shipment id, for example shp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2" }, "required": true, "description": "Shipment id, for example shp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2", "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "ecmr_pdf", "pod_pdf", "attachment", "signature_image", "photo", "other" ], "description": "Only documents of this kind" }, "required": false, "description": "Only documents of this kind", "name": "kind", "in": "query" } ], "responses": { "200": { "description": "The documents of this shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentList" } } } }, "400": { "description": "The shipment id is malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks the scope `documents:read`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/documents/{id}": { "get": { "tags": [ "documents" ], "summary": "Read the metadata of a document", "parameters": [ { "schema": { "type": "string", "description": "Document id, for example doc_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2" }, "required": true, "description": "Document id, for example doc_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "The document id is malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks the scope `documents:read`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such document in this organisation and mode", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/documents/{id}/download": { "get": { "tags": [ "documents" ], "summary": "Download the file behind a signed link", "description": "Demands no API key of its own: the `sig` query parameter is the authorisation, so a link can be handed to someone who never sees a key. Links last five minutes and name the party they were issued to in `aud`, which that party has to be holding: an `api:` link needs an `Authorization: Bearer` header of that organisation, a `sign:` link needs the sign token in the `freightapi-sign-token` header. Forwarding the URL alone gives nothing away. Some links — signature images and reservation photos — are spent by the first download.", "security": [], "parameters": [ { "schema": { "type": "string", "description": "Document id, for example doc_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2" }, "required": true, "description": "Document id, for example doc_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2", "name": "id", "in": "path" }, { "schema": { "type": "string", "pattern": "^\\d{1,15}$", "description": "Unix timestamp in seconds at which the link stops working" }, "required": true, "description": "Unix timestamp in seconds at which the link stops working", "name": "exp", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z]+:[0-9A-Za-z_]+$", "description": "Who the link was issued to: `api:` or `sign:`. Absent only on links issued before this parameter existed, which are refused after the migration window closes." }, "required": false, "description": "Who the link was issued to: `api:` or `sign:`. Absent only on links issued before this parameter existed, which are refused after the migration window closes.", "name": "aud", "in": "query" }, { "schema": { "type": "string", "enum": [ "0", "1" ], "description": "`1` when the link is spent by the first successful download" }, "required": false, "description": "`1` when the link is spent by the first successful download", "name": "once", "in": "query" }, { "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "HMAC-SHA256 of \"...\" with the download signing secret" }, "required": true, "description": "HMAC-SHA256 of \"...\" with the download signing secret", "name": "sig", "in": "query" } ], "responses": { "200": { "description": "The file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The document id is malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "An API key was presented and it is not a valid one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The signature does not match, the link was issued to someone else, or a single-use link was already used", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such document, or its object is gone from R2", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "410": { "description": "The link expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`exp` or `sig` is missing or malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/shipments/{id}/signatures": { "post": { "tags": [ "signatures" ], "summary": "Record a signature or seal", "description": "For systems that authenticate the signer themselves, for example a TMS with its own driver app: method `api` with `evidence.auth_context`, or `photo_of_paper` with the uploaded photo as `image_document_id`. The signature binds the `document_hash` of the current version (ADR 0004). Consignor and carrier may sign once the consignment note is issued, the consignee once the shipment is in transit; each role signs once. The carrier signature at pickup moves the shipment to `in_transit` and appends `shipment.pickup_signed` right after `signature.completed`. Send an `Idempotency-Key` so a retry cannot record the signature twice.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "role": "carrier", "method": "api", "trust_level": "platform_auth", "kind": "signature", "signer": { "name": "Marek Nowak", "company": "Carrier GmbH", "phone": "+48601234568" }, "evidence": { "signed_at": "2026-09-14T08:12:00+02:00", "device": "driver", "ip": "203.0.113.7", "user_agent": "DriverApp/4.2 (Android 15)", "auth_context": "driver app session, PIN verified" } }, "schema": { "$ref": "#/components/schemas/SignatureCreate" } } } }, "responses": { "201": { "description": "The recorded signature; `Location` points at it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Signature" } } } }, "400": { "description": "The path parameter is not a shipment id, or the body is not JSON", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `signatures:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The role already signed (`already_signed`), or the shipment is not in a status this role can sign (`invalid_state`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The body is invalid or incomplete for its method, kind or trust level, `signed_at` is out of range, or `image_document_id` is not an image of this shipment", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "get": { "tags": [ "signatures" ], "summary": "List the signatures of a shipment", "description": "Every signature and seal of the shipment in signing order, each with `verified`: whether its `document_hash` still equals the document hash of the current version.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The signatures", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureList" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/signatures/{id}": { "get": { "tags": [ "signatures" ], "summary": "Retrieve a signature", "description": "One signature with its evidence, the version it signed and `verified`. A signature of another organisation or of the other mode is a 404, never a 403.", "parameters": [ { "schema": { "type": "string", "example": "sig_01K4Y000000000000000DEM03A", "description": "Signature id" }, "required": true, "description": "Signature id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Signature" } } } }, "400": { "description": "The path parameter is not a signature id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such signature in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/signatures/{id}/verification": { "get": { "tags": [ "signatures" ], "summary": "Verify the QTSP signature of a signature", "description": "Checks the detached CAdES an `ades` or `qes` signature carries (M5-02, ADR 0017): the CMS is parsed, the signature value is recomputed over its signed attributes, the signed `message-digest` is compared with the `document_hash` that was bound, and the signer certificate is checked against the CA that travels with it. `document_current` says whether that hash is still the document hash of the current version. `trusted_list.checked` is always false and says why: Cargofollow does not fetch the EU List of Trusted Lists, so nothing here confirms that the issuing CA is a qualified one — the certificate claims it and this endpoint repeats the claim. The response carries the CMS and the certificate as base64 DER so an external validator can be given the same material. A `platform_auth` signature has no QTSP signature and answers 404.", "parameters": [ { "schema": { "type": "string", "example": "sig_01K4Y000000000000000DEM03A", "description": "Signature id" }, "required": true, "description": "Signature id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "What was checked, and what was not", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureVerification" } } } }, "400": { "description": "The path parameter is not a signature id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such signature, or it carries no QTSP signature", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/signature-requests": { "post": { "tags": [ "signatures" ], "summary": "Create a sign link for a role", "description": "Hands out a single-use link to the sign PWA: `SIGN_BASE_URL/s/`, with 32 random bytes as the token. This response is the only place the raw token appears; the database stores its sha256, so a copy of the data gives nobody a working link. Channels `email` and `sms` also send the link to `recipient` in their language and log the attempt in `GET /v1/notifications`; `link` and `qr` leave delivery to the caller. A message the provider refuses does not fail this call — the token is still returned — and shows up as an empty `sent_at` plus a `failed` notification.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequestCreate" } } } }, "responses": { "201": { "description": "The sign link, with the raw token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequestCreated" } } } }, "400": { "description": "The path parameter is not a shipment id, or the body is not JSON", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `signatures:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The shipment is not issued yet, or the role already signed", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The body is invalid, or the channel misses the address it needs", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "503": { "description": "`trust_level` is `ades` or `qes` and this deployment has no qualified trust service provider (`qtsp_unavailable`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "get": { "tags": [ "signatures" ], "summary": "List the sign links of a shipment", "description": "Every sign link of the shipment in creation order, each with its status: `pending`, `used` once it produced a signature, `expired` once `expires_at` passed, `revoked` once it was withdrawn. The tokens themselves are not in this list.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The sign links", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequestList" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/signature-requests/{id}": { "get": { "tags": [ "signatures" ], "summary": "Retrieve a sign link", "description": "One sign link with its status. A link of another organisation or of the other mode is a 404, never a 403.", "parameters": [ { "schema": { "type": "string", "example": "sgr_01K4Y000000000000000DEM04B", "description": "Signature request id" }, "required": true, "description": "Signature request id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The sign link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequest" } } } }, "400": { "description": "The path parameter is not a signature request id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such signature request in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/signature-requests/{id}/revoke": { "post": { "tags": [ "signatures" ], "summary": "Withdraw a sign link", "description": "Takes a link out of circulation before it was used: the wrong recipient, a cancelled appointment, a message that went to an old address. The status becomes `revoked` and `revoked_at` is stamped; from then on the public sign routes answer 410 `token_revoked` instead of 404, so a signer who opens a withdrawn link learns that it was withdrawn rather than that it never existed. Only a `pending` link can be withdrawn — a used, expired or already revoked one answers 409 `invalid_state`. The link itself cannot be brought back; create a new one for the same role.", "parameters": [ { "schema": { "type": "string", "example": "sgr_01K4Y000000000000000DEM04B", "description": "Signature request id" }, "required": true, "description": "Signature request id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The withdrawn sign link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequest" } } } }, "400": { "description": "The path parameter is not a signature request id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `signatures:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such signature request in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The link is not `pending` any more (`invalid_state`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/sign/{token}": { "get": { "tags": [ "sign" ], "summary": "Open a sign link", "description": "No API key: the token from the sign URL is the credential and names exactly one signature request. Answers the consignment note as the role of the link may see it, the signatures already given, the documents with short-lived signed download URLs and the methods this link accepts. A handoff token resolves here to the session it was made for and is burned in the process, so the response carries the original `token` once. Limited to 60 requests per minute per IP.", "parameters": [ { "schema": { "type": "string", "minLength": 20, "maxLength": 128, "description": "The token from the sign URL, or a handoff token" }, "required": true, "description": "The token from the sign URL, or a handoff token", "name": "token", "in": "path" } ], "responses": { "200": { "description": "The sign context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignContext" } } } }, "404": { "description": "Unknown token", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The link was already used (`already_signed`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "410": { "description": "The link or the handoff has expired (`token_expired`), or the link was withdrawn (`token_revoked`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Too many requests from this IP", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "post": { "tags": [ "sign" ], "summary": "Sign through a sign link", "description": "Records the signature of the role the link names. `drawn` stores the PNG as a `signature_image` document of the shipment and refers to it; `click_otp` needs a verified one-time password, which arrives with M2-02. Evidence the signer cannot choose (IP, user agent, time, the link id) is added by the API; the location is stored only with consent. `device` is the one thing the signer chooses: `driver` says the consignee signed on the driver device, and it defaults to `own`. The link is single-use: the next call answers 409. The carrier signature on an issued shipment moves it to `in_transit`, exactly as an API-side signature does.", "parameters": [ { "schema": { "type": "string", "minLength": 20, "maxLength": 128, "description": "The token from the sign URL, or a handoff token" }, "required": true, "description": "The token from the sign URL, or a handoff token", "name": "token", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignSubmit" } } } }, "responses": { "201": { "description": "The recorded signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Signature" } } } }, "404": { "description": "Unknown token", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The link was already used (`already_signed`), or the shipment is not in a status this role can sign (`invalid_state`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "410": { "description": "The link has expired (`token_expired`) or was withdrawn (`token_revoked`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The body is invalid, the image is not a PNG within the size limit, the `otp_verified_token` is unknown, used or expired (`otp_invalid`), the link asks for `ades` or `qes` and no `identification_token` was sent (`identification_required`), or the one that was sent is unknown, used or expired (`identification_invalid`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Too many requests from this IP", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "503": { "description": "The trust service provider refused or could not be reached (`qtsp_unavailable`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/sign/{token}/identification": { "post": { "tags": [ "sign" ], "summary": "Identify the signer at the trust service provider", "description": "The extra step a sign link with `trust_level` `ades` or `qes` asks for (M5-02, ADR 0017). The response names the provider in words — `provider_name` — and says what has to happen next: `pending` with a `redirect_url` to send the signer to, or `verified` with the `identification_token` that `POST /v1/sign/:token` then takes. Which provider it is and what it speaks stays behind the API. The token is single use and valid fifteen minutes. A link that signs at `platform_auth` answers 422: there is nothing to identify for. Limited to 60 requests per minute per IP.", "parameters": [ { "schema": { "type": "string", "minLength": 20, "maxLength": 128, "description": "The token from the sign URL, or a handoff token" }, "required": true, "description": "The token from the sign URL, or a handoff token", "name": "token", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignIdentificationStart" } } } }, "responses": { "201": { "description": "The identification, started or already done", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignIdentification" } } } }, "404": { "description": "Unknown token", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The link was already used (`already_signed`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "410": { "description": "The link has expired (`token_expired`) or was withdrawn (`token_revoked`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "This link signs at `platform_auth` and needs no identification", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Too many requests from this IP", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "503": { "description": "This deployment has no trust service provider (`qtsp_unavailable`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "get": { "tags": [ "sign" ], "summary": "Where the identification stands", "description": "Polled by the sign page while the signer is away at the provider. Answers the same shape as the start call; reading does not use the identification up — only the signature does.", "parameters": [ { "schema": { "type": "string", "minLength": 20, "maxLength": 128, "description": "The token from the sign URL, or a handoff token" }, "required": true, "description": "The token from the sign URL, or a handoff token", "name": "token", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The `identification_token` of the start call" }, "required": true, "description": "The `identification_token` of the start call", "name": "reference", "in": "query" } ], "responses": { "200": { "description": "The identification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignIdentification" } } } }, "404": { "description": "Unknown token", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The link was already used (`already_signed`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "410": { "description": "The link has expired (`token_expired`) or was withdrawn (`token_revoked`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "This link needs no identification, or the reference is unknown, used or expired (`identification_invalid`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Too many requests from this IP", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "503": { "description": "This deployment has no trust service provider (`qtsp_unavailable`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/sign/{token}/handoff": { "post": { "tags": [ "sign" ], "summary": "Move the sign session to another device", "description": "Answers a second, short-lived token with its QR code, so the driver can hand the phone gesture to the consignee on their own device. The handoff URL works once and expires ten minutes after the request; opening it returns the sign context plus the original token.", "parameters": [ { "schema": { "type": "string", "minLength": 20, "maxLength": 128, "description": "The token from the sign URL, or a handoff token" }, "required": true, "description": "The token from the sign URL, or a handoff token", "name": "token", "in": "path" } ], "responses": { "201": { "description": "The handoff link and its QR code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignHandoff" } } } }, "404": { "description": "Unknown token", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The link was already used (`already_signed`), or this is itself a handoff token (`conflict`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "410": { "description": "The link has expired (`token_expired`) or was withdrawn (`token_revoked`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Too many requests from this IP", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/sign/{token}/photos": { "post": { "tags": [ "sign" ], "summary": "Upload photos for a reservation", "description": "The pictures that go with a reservation, stored as `photo` documents of the shipment behind the token. They are uploaded before the reservation itself, so the ids come back here and are sent along as `photo_document_ids`. At most 5 photos per reservation and 5242880 bytes each, counted over every call that has not been attached to a reservation yet, so the ceiling holds however the client splits the upload. On top of that the sign links of one shipment store at most 20 photos together, so filing a reservation does not hand the link a fresh five. Large pictures are resampled on the way in. Limited to 60 requests per minute per IP.", "parameters": [ { "schema": { "type": "string", "minLength": 20, "maxLength": 128, "description": "The token from the sign URL, or a handoff token" }, "required": true, "description": "The token from the sign URL, or a handoff token", "name": "token", "in": "path" } ], "requestBody": { "required": true, "description": "At most 5 photos per reservation, 5242880 bytes each. The server counts the photos that are already waiting for a remark, so the ceiling holds across several calls.", "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "photo": { "type": "array", "maxItems": 5, "items": { "type": "string", "format": "binary" }, "description": "Repeat the part for every photo; image/jpeg, image/png, image/webp" } }, "required": [ "photo" ] } } } }, "responses": { "201": { "description": "The stored photos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignPhotos" } } } }, "404": { "description": "Unknown token", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The link was already used (`already_signed`), or the shipment takes no reservations yet (`invalid_state`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "410": { "description": "The link has expired (`token_expired`) or was withdrawn (`token_revoked`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "413": { "description": "A photo is larger than 5242880 bytes", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "415": { "description": "The body is not multipart, or a photo is not one of image/jpeg, image/png, image/webp", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "No photo was sent, this would be photo 6 of the reservation, or photo 21 the sign links put on this shipment", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Too many requests from this IP", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/sign/{token}/remarks": { "post": { "tags": [ "sign" ], "summary": "Record a reservation through a sign link", "description": "A reservation at pickup or delivery (CMR box 18 and 24) made by the party the link names, through the same service as `POST /v1/shipments/:id/remarks`: the same statuses take one, the same `remark.added` event is appended, and the actor is the signer instead of a key. Photos come from `POST /v1/sign/:token/photos` and are referenced by id; a photo of another shipment is refused. The link itself is not used up — a signer makes a reservation and then signs. Limited to 60 requests per minute per IP.", "parameters": [ { "schema": { "type": "string", "minLength": 20, "maxLength": 128, "description": "The token from the sign URL, or a handoff token" }, "required": true, "description": "The token from the sign URL, or a handoff token", "name": "token", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemarkCreate" } } } }, "responses": { "201": { "description": "The recorded reservation, with a download URL per photo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Remark" } } } }, "404": { "description": "Unknown token", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The link was already used (`already_signed`), or the shipment is still a draft or was cancelled (`invalid_state`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "410": { "description": "The link has expired (`token_expired`) or was withdrawn (`token_revoked`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The body is invalid, or a photo does not belong to this shipment", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Too many requests from this IP", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/sign/{token}/otp": { "post": { "tags": [ "sign" ], "summary": "Send a one-time password for this sign link", "description": "Sends six digits to the e-mail address or phone number the signature request names, so the signer can sign with `click_otp` without drawing anything. `channel` picks one of the `otp_channels` the context lists; left out, the first of them is used. The response says which channel was used and shows the destination masked, never in full: the token in the URL is enough to ask for a code, so a leaked link must not also hand over a readable address. The code lives ten minutes and takes five tries. At most five codes per recipient per ten minutes, counted per recipient rather than per IP, and 60 requests per minute per IP on top of that.", "parameters": [ { "schema": { "type": "string", "minLength": 20, "maxLength": 128, "description": "The token from the sign URL, or a handoff token" }, "required": true, "description": "The token from the sign URL, or a handoff token", "name": "token", "in": "path" }, { "schema": { "type": "string", "enum": [ "email", "sms" ], "description": "One of the `otp_channels` of the context; the first of them when left out" }, "required": false, "description": "One of the `otp_channels` of the context; the first of them when left out", "name": "channel", "in": "query" } ], "responses": { "201": { "description": "The code was sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignOtpChallenge" } } } }, "404": { "description": "Unknown token", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The link was already used (`already_signed`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "410": { "description": "The link has expired (`token_expired`) or was withdrawn (`token_revoked`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The sign link has no address to send a code to over this channel", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Too many codes for this recipient (`rate_limited`), too many requests from this IP, or the recipient is locked after five wrong codes (`otp_locked`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "503": { "description": "The channel refused the message (`service_unavailable`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/sign/{token}/otp/verify": { "post": { "tags": [ "sign" ], "summary": "Exchange a one-time password for a signing proof", "description": "Checks the six digits and answers an `otp_verified_token`: a single-use proof, valid five minutes, that `POST /v1/sign/:token` accepts as `otp_verified_token`. The code itself works once — a correct one is burnt immediately — and a wrong one costs one of five tries. `channel` has to be the one the code was asked for, since a code is bound to the address it went to. The fifth wrong code locks this recipient for the rest of the ten-minute window with 429 `otp_locked`; a new code is needed after that.", "parameters": [ { "schema": { "type": "string", "minLength": 20, "maxLength": 128, "description": "The token from the sign URL, or a handoff token" }, "required": true, "description": "The token from the sign URL, or a handoff token", "name": "token", "in": "path" }, { "schema": { "type": "string", "enum": [ "email", "sms" ], "description": "One of the `otp_channels` of the context; the first of them when left out" }, "required": false, "description": "One of the `otp_channels` of the context; the first of them when left out", "name": "channel", "in": "query" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignOtpVerify" } } } }, "responses": { "200": { "description": "The proof the signature route accepts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignOtpVerified" } } } }, "404": { "description": "Unknown token", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The link was already used (`already_signed`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "410": { "description": "The link has expired (`token_expired`) or was withdrawn (`token_revoked`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The code is wrong or expired (`otp_invalid`), or the link has no address (`validation_failed`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Five wrong codes (`otp_locked`), or too many requests from this IP", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/remarks": { "post": { "tags": [ "remarks" ], "summary": "Add a reservation to a shipment", "description": "A reservation at pickup or delivery (CMR box 18 and 24). Photos come either as `photo_document_ids` of documents uploaded earlier, or as multipart `photo` parts that are stored as documents with kind `photo` in the same request. Appends `remark.added`.", "parameters": [ { "schema": { "type": "string", "description": "Shipment id, for example shp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2" }, "required": true, "description": "Shipment id, for example shp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2", "name": "id", "in": "path" } ], "requestBody": { "required": true, "description": "Either JSON with `photo_document_ids`, or multipart with the photos themselves. At most 5 photos of 5242880 bytes each.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemarkCreate" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "phase": { "type": "string", "enum": [ "pickup", "delivery" ] }, "type": { "type": "string", "enum": [ "damage", "shortage", "delay", "other" ] }, "text": { "type": "string", "maxLength": 2000 }, "photo": { "type": "array", "maxItems": 5, "items": { "type": "string", "format": "binary" }, "description": "Repeat the part for every photo; JPEG, PNG or WebP" }, "photo_document_ids": { "type": "array", "maxItems": 5, "items": { "type": "string" }, "description": "Repeat the part for every photo that was uploaded earlier" } }, "required": [ "phase", "type" ] } } } }, "responses": { "201": { "description": "The remark was recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Remark" } } } }, "400": { "description": "The shipment id is malformed, or the body is not valid JSON", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The shipment is still a draft, or was cancelled", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "A photo is larger than 5242880 bytes", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "A photo is not one of image/jpeg, image/png, image/webp", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "A field is missing or invalid, or a photo does not belong here", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "tags": [ "remarks" ], "summary": "List the reservations of a shipment", "description": "Newest first. Every photo carries a fresh download URL.", "parameters": [ { "schema": { "type": "string", "description": "Shipment id, for example shp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2" }, "required": true, "description": "Shipment id, for example shp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The remarks of this shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemarkList" } } } }, "400": { "description": "The shipment id is malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/remarks/{id}": { "get": { "tags": [ "remarks" ], "summary": "Read one reservation", "parameters": [ { "schema": { "type": "string", "description": "Remark id, for example rmk_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2" }, "required": true, "description": "Remark id, for example rmk_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The remark", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Remark" } } } }, "400": { "description": "The remark id is malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such remark in this organisation and mode", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/shipments/{id}/pod": { "get": { "tags": [ "pod" ], "summary": "Read the proof of delivery of a shipment", "description": "The ePOD of a delivered shipment: the consignee signature with its evidence, every reservation with its photos, the colli check and the moment of delivery. `colli` puts the count on the note (`expected`) next to the count the consignee reported while signing (`received`), with `discrepancy` true only when the two are both known and differ. Available from status `delivered`; before that the answer is 404 `pod_not_available`, and a completed shipment keeps answering it. `pdf_url` is a signed link to the rendered ePOD PDF, which the delivery produced (M2-10).", "parameters": [ { "schema": { "type": "string", "description": "Shipment id, for example shp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2" }, "required": true, "description": "Shipment id, for example shp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The proof of delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofOfDelivery" } } } }, "400": { "description": "The shipment id is malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such shipment in this organisation and mode, or it is not delivered", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/shipments/{id}/complete": { "post": { "tags": [ "pod" ], "summary": "Close a delivered shipment", "description": "Accepts the proof of delivery and closes the file: `delivered` becomes `completed` and `shipment.completed` is appended to the hash chain. This is the administrative counterpart of the delivery — the carrier proved the goods arrived, this says the organisation is done with the consignment note. `completed` is final: nothing can be signed, changed or cancelled afterwards, and the ePOD stays readable. Any other status answers 409 `invalid_transition` with the statuses it does allow.", "parameters": [ { "schema": { "type": "string", "description": "Shipment id, for example shp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2" }, "required": true, "description": "Shipment id, for example shp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The completed shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "description": "The shipment id is malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The shipment is not `delivered` (`invalid_transition`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/shipments/{id}/invoice.xml": { "get": { "tags": [ "invoice" ], "summary": "Read the e-invoice of a delivered shipment as UBL", "description": "The carriage of a delivered shipment as a UBL 2.1 invoice in Peppol BIS Billing 3.0, the format the Dutch B2B e-invoicing obligation runs on (docs/regulation.md#8). The carrier is the seller, `charges.payer` is the buyer, and the ePOD sets the invoice date and the actual delivery date — an invoice follows the proof, so before `delivered` the answer is 404 `invoice_not_available`. Only `charges.carriage` becomes an invoice line: cash on delivery is money collected for the consignor, not the carrier's revenue, so it is reported as a note. The document is rendered on the spot and never stored: Cargofollow keeps no ledger, assigns no numbers and books nothing, so `number`, the VAT rate of a domestic run and the payee account come from the query. A fact that is missing is answered with 422 `invoice_incomplete` naming it, never with a document that is quietly wrong.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "example": "INV-2026-0003", "description": "BT-1, the invoice number. Defaults to the shipment reference, then its id. Refused when it carries a character XML 1.0 forbids, because the number identifies the invoice and may not be quietly rewritten to make the document parse" }, "required": false, "description": "BT-1, the invoice number. Defaults to the shipment reference, then its id. Refused when it carries a character XML 1.0 forbids, because the number identifies the invoice and may not be quietly rewritten to make the document parse", "name": "number", "in": "query" }, { "schema": { "type": "string", "enum": [ "S", "AE", "G", "Z", "E", "O" ], "description": "UNCL 5305 category of the carriage: `S` standard rated, `AE` reverse charge, `G` export outside the EU, `Z` zero rated, `E` exempt, `O` outside the scope of VAT. Derived from the lane when absent" }, "required": false, "description": "UNCL 5305 category of the carriage: `S` standard rated, `AE` reverse charge, `G` export outside the EU, `Z` zero rated, `E` exempt, `O` outside the scope of VAT. Derived from the lane when absent", "name": "vat_category", "in": "query" }, { "schema": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "example": 21, "description": "BT-119 in percent. Required for a standard-rated invoice, refused by EN 16931 at 0" }, "required": false, "description": "BT-119 in percent. Required for a standard-rated invoice, refused by EN 16931 at 0", "name": "vat_rate", "in": "query" }, { "schema": { "type": "string", "enum": [ "nl", "en", "de" ], "description": "Language of the free text Cargofollow writes into the document. Defaults to `en`" }, "required": false, "description": "Language of the free text Cargofollow writes into the document. Defaults to `en`", "name": "language", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365, "example": 30, "description": "Days between BT-2 and BT-9. Defaults to 30" }, "required": false, "description": "Days between BT-2 and BT-9. Defaults to 30", "name": "payment_terms_days", "in": "query" }, { "schema": { "type": "string", "minLength": 5, "maxLength": 34, "example": "NL02ABNA0123456789", "description": "BT-84, the account the invoice is paid into. Mandatory for a Dutch seller, which the Dutch CIUS requires to state a means of payment (NL-R-007)" }, "required": false, "description": "BT-84, the account the invoice is paid into. Mandatory for a Dutch seller, which the Dutch CIUS requires to state a means of payment (NL-R-007)", "name": "iban", "in": "query" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 11, "example": "ABNANL2A", "description": "BT-86, the bank behind `iban`" }, "required": false, "description": "BT-86, the bank behind `iban`", "name": "bic", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "BT-85, the name on the account behind `iban`" }, "required": false, "description": "BT-85, the name on the account behind `iban`", "name": "account_holder", "in": "query" } ], "responses": { "200": { "description": "The invoice, as UBL 2.1 XML", "content": { "application/xml": { "schema": { "type": "string", "format": "xml", "example": "…" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `documents:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment, or it is not delivered yet (`invoice_not_available`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The shipment or the query lacks a fact EN 16931 requires (`invoice_incomplete`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/webhook-endpoints": { "post": { "tags": [ "webhooks" ], "summary": "Create a webhook endpoint", "description": "Subscribes an https URL to a set of events. The `secret` is shown once and is never returned again: store it, or rotate it with `POST /v1/webhook-endpoints/{id}/rotate-secret`. Requires the scope `webhooks:manage`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpoint" } } } }, "responses": { "201": { "description": "The endpoint, with its signing secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } } }, "422": { "description": "The URL is not a public https URL, or an event filter is unknown", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "get": { "tags": [ "webhooks" ], "summary": "List webhook endpoints", "description": "Newest first, cursor-paginated. Requires the scope `webhooks:manage`.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^whe_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "webhook endpoint id" }, "required": false, "description": "webhook endpoint id", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "One page of endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } } } } }, "/v1/webhook-endpoints/{id}": { "get": { "tags": [ "webhooks" ], "summary": "Get a webhook endpoint", "description": "Requires the scope `webhooks:manage`.", "parameters": [ { "schema": { "type": "string", "example": "whe_01J9Z3MREBS6N1VQ0P8T4W7K2C" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "404": { "description": "No endpoint with this id in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "patch": { "tags": [ "webhooks" ], "summary": "Update a webhook endpoint", "description": "Changes the URL, the event filters, the description or whether the endpoint is active. Requires the scope `webhooks:manage`.", "parameters": [ { "schema": { "type": "string", "example": "whe_01J9Z3MREBS6N1VQ0P8T4W7K2C" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpoint" } } } }, "responses": { "200": { "description": "The updated endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "404": { "description": "No endpoint with this id in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The URL is not a public https URL, or an event filter is unknown", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "delete": { "tags": [ "webhooks" ], "summary": "Delete a webhook endpoint", "description": "Deliveries stop immediately. Requires the scope `webhooks:manage`.", "parameters": [ { "schema": { "type": "string", "example": "whe_01J9Z3MREBS6N1VQ0P8T4W7K2C" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "No endpoint with this id in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/webhook-endpoints/{id}/rotate-secret": { "post": { "tags": [ "webhooks" ], "summary": "Rotate the signing secret", "description": "Replaces the secret; deliveries in flight are signed with the new one. The `secret` is shown once and is never returned again: store it, or rotate it with `POST /v1/webhook-endpoints/{id}/rotate-secret`.", "parameters": [ { "schema": { "type": "string", "example": "whe_01J9Z3MREBS6N1VQ0P8T4W7K2C" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The endpoint, with its new signing secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } } }, "404": { "description": "No endpoint with this id in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/webhook-endpoints/{id}/test": { "post": { "tags": [ "webhooks" ], "summary": "Send a test ping", "description": "Delivers a signed `ping` event synchronously and reports what the receiver answered. A receiver may echo the `freightapi-echo` header for the conformance checklist. The call itself succeeds even when the delivery fails; read `status`.", "parameters": [ { "schema": { "type": "string", "example": "whe_01J9Z3MREBS6N1VQ0P8T4W7K2C" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The outcome of the delivery attempt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResult" } } } }, "404": { "description": "No endpoint with this id in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/webhook-deliveries": { "get": { "tags": [ "webhooks" ], "summary": "List webhook deliveries", "description": "The delivery log, newest first and cursor-paginated. Filter with `endpoint_id`, `status` and `event_type`. Requires the scope `webhooks:manage`.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^whd_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "webhook delivery id" }, "required": false, "description": "webhook delivery id", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "pattern": "^whe_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "webhook endpoint id" }, "required": false, "description": "webhook endpoint id", "name": "endpoint_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed", "dead" ], "description": "pending until a 2xx arrives, dead after the last retry" }, "required": false, "description": "pending until a 2xx arrives, dead after the last retry", "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "shipment.created", "shipment.issued", "shipment.updated", "shipment.cancelled", "shipment.pickup_signed", "shipment.delivered", "shipment.completed", "signature.completed", "document.created", "remark.added", "inspection.viewed", "provider.sync_failed", "efti.uil_issued", "efti.authority_access", "efti.combined_transport_stamped", "ping" ], "description": "Event name" }, "required": false, "description": "Event name", "name": "event_type", "in": "query" } ], "responses": { "200": { "description": "One page of deliveries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } } } } }, "/v1/webhook-deliveries/{id}": { "get": { "tags": [ "webhooks" ], "summary": "Get a webhook delivery", "description": "Everything one delivery knows: the headers and body that were sent, what the receiver answered and how many attempts it took. Requires the scope `webhooks:manage`.", "parameters": [ { "schema": { "type": "string", "example": "whd_01J9Z3MREBS6N1VQ0P8T4W7K2C" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryDetail" } } } }, "404": { "description": "No delivery with this id in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/webhook-deliveries/{id}/retry": { "post": { "tags": [ "webhooks" ], "summary": "Replay a webhook delivery", "description": "Queues the same event again for the same endpoint, right now. The replay is a new delivery with the same `freightapi-event-id` and its own `freightapi-delivery-id`, so the log keeps both. Requires the scope `webhooks:manage`.", "parameters": [ { "schema": { "type": "string", "example": "whd_01J9Z3MREBS6N1VQ0P8T4W7K2C" }, "required": true, "name": "id", "in": "path" } ], "responses": { "201": { "description": "The queued replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryDetail" } } } }, "404": { "description": "No delivery with this id in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The delivery is still pending, or its endpoint is inactive", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/events": { "get": { "tags": [ "events" ], "summary": "List the events of the organisation", "description": "Every event of every shipment in this organisation and mode, newest first, from the last 90 days. Filter by `type`, `shipment_id` and `since`; page with `cursor`. Each item is a link of the hash chain of its own shipment, so `prev_hash` and `hash` refer to that chain and not to this feed. Webhooks push the same events; this feed is the pull side, and the way to catch up after an outage.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Page size, 1 to 100" }, "required": false, "description": "Page size, 1 to 100", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The `next_cursor` of the previous page; opaque" }, "required": false, "description": "The `next_cursor` of the previous page; opaque", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "shipment.created", "shipment.issued", "shipment.updated", "shipment.cancelled", "shipment.pickup_signed", "shipment.delivered", "shipment.completed", "signature.completed", "document.created", "remark.added", "inspection.viewed", "provider.sync_failed", "efti.uil_issued", "efti.authority_access", "efti.combined_transport_stamped" ], "description": "Only events of this type" }, "required": false, "description": "Only events of this type", "name": "type", "in": "query" }, { "schema": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Only events of this shipment" }, "required": false, "description": "Only events of this shipment", "name": "shipment_id", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound on when Cargofollow recorded the event; at most 90 days ago, which is also the default" }, "required": false, "description": "Inclusive lower bound on when Cargofollow recorded the event; at most 90 days ago, which is also the default", "name": "since", "in": "query" } ], "responses": { "200": { "description": "One page of events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventFeed" } } } }, "400": { "description": "The cursor is not one this API issued", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `events:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "A query parameter is invalid, for example a `since` older than the feed keeps", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/request-logs": { "get": { "tags": [ "request-logs" ], "summary": "List the API calls of the organisation", "description": "Every call this organisation made in this mode over the last 30 days, newest first: method, path, status, duration and the error code of a failure, never a body. Filter by `status`, `path`, `request_id` and `since`; page with `cursor`. Requires the scope `events:read`.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^req_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The `next_cursor` of the previous page" }, "required": false, "description": "The `next_cursor` of the previous page", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 100, "maximum": 599, "description": "Only calls that ended in this exact status" }, "required": false, "description": "Only calls that ended in this exact status", "name": "status", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Only calls on this exact path, without the query string" }, "required": false, "description": "Only calls on this exact path, without the query string", "name": "path", "in": "query" }, { "schema": { "type": "string", "pattern": "^req_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Only the call with this request id" }, "required": false, "description": "Only the call with this request id", "name": "request_id", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound on when the call was logged; the log keeps 30 days" }, "required": false, "description": "Inclusive lower bound on when the call was logged; the log keeps 30 days", "name": "since", "in": "query" } ], "responses": { "200": { "description": "One page of request logs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestLogList" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `events:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "A query parameter is invalid", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/request-logs/{request_id}": { "get": { "tags": [ "request-logs" ], "summary": "Get one API call by its request id", "description": "The `freightapi-request-id` header of any response is the id to ask for here. Requires the scope `events:read`.", "parameters": [ { "schema": { "type": "string", "example": "req_01J9Z3MREBS6N1VQ0P8T4W7K2C" }, "required": true, "name": "request_id", "in": "path" } ], "responses": { "200": { "description": "The logged call", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestLog" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `events:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No call with this request id in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/audit-log": { "get": { "tags": [ "audit-log" ], "summary": "List the administrative acts of the organisation", "description": "Who created or revoked an API key, registered or changed a webhook endpoint, rotated its secret, invited a colleague, changed a role, removed a member, changed the organisation settings, started an export or asked for an erasure — newest first. Every entry's `metadata` is an allowlist for that action and holds no personal data and no secret; the address of an invitee and the URL of an endpoint stay in the records they belong to. Filter by `action`, `actor_id` and `since`; page with `cursor`. Requires the scope `events:read`.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The `next_cursor` of the previous page" }, "required": false, "description": "The `next_cursor` of the previous page", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "api_key.created", "api_key.revoked", "webhook_endpoint.created", "webhook_endpoint.updated", "webhook_endpoint.secret_rotated", "member.invited", "member.role_changed", "member.removed", "organization.updated", "export.started", "erasure.requested", "two_factor.enabled", "two_factor.disabled", "two_factor.reset", "two_factor.verification_failed", "two_factor.recovery_code_used", "two_factor.recovery_codes_regenerated", "two_factor.policy_changed", "efti_authorisation.granted", "efti_authorisation.revoked" ], "description": "Only entries for this action" }, "required": false, "description": "Only entries for this action", "name": "action", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Only entries written by this user or key" }, "required": false, "description": "Only entries written by this user or key", "name": "actor_id", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound on when the act happened; the log keeps 730 days" }, "required": false, "description": "Inclusive lower bound on when the act happened; the log keeps 730 days", "name": "since", "in": "query" } ], "responses": { "200": { "description": "One page of audit entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogList" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `events:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "A query parameter is invalid", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/notifications": { "get": { "tags": [ "notifications" ], "summary": "List the messages the organisation sent", "description": "Every e-mail and SMS sent for this organisation in this mode, newest first: the channel, the template, the status, the provider message id and the error of a refusal. The recipient appears only as a sha256 — pass an address as `recipient` and it is hashed here to filter, so no readable address is stored or returned. `mocked` means the channel had no credentials and the message went to the console sender. Requires the scope `events:read`.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^ntf_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The `next_cursor` of the previous page" }, "required": false, "description": "The `next_cursor` of the previous page", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "email", "sms" ] }, "required": false, "name": "channel", "in": "query" }, { "schema": { "type": "string", "enum": [ "queued", "sent", "mocked", "failed" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Only messages of this template" }, "required": false, "description": "Only messages of this template", "name": "template", "in": "query" }, { "schema": { "type": "string", "pattern": "^shp_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Only messages about this shipment" }, "required": false, "description": "Only messages about this shipment", "name": "shipment_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 320, "description": "An e-mail address or phone number; it is hashed here and compared against the stored hash, so the address never reaches the database" }, "required": false, "description": "An e-mail address or phone number; it is hashed here and compared against the stored hash, so the address never reaches the database", "name": "recipient", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound on when the message was logged" }, "required": false, "description": "Inclusive lower bound on when the message was logged", "name": "since", "in": "query" } ], "responses": { "200": { "description": "One page of notifications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationList" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `events:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "A query parameter is invalid", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/inspect/{token}": { "get": { "tags": [ "inspect" ], "summary": "View a consignment note through its inspection token", "description": "No API key: the token from the QR code is the credential and names exactly one shipment. Answers the CMR boxes of the current version, the signatures with their verification status, the documents with token-scoped download URLs and an integrity summary of the event chain. Every call appends `inspection.viewed` to that chain, with a daily hash of the client IP, the user agent and the locale. Limited to 60 requests per minute per IP.", "parameters": [ { "schema": { "type": "string", "minLength": 20, "maxLength": 128, "description": "The token from the inspection URL" }, "required": true, "description": "The token from the inspection URL", "name": "token", "in": "path" } ], "responses": { "200": { "description": "The read-only view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectionView" } } } }, "404": { "description": "Unknown token", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "410": { "description": "The token was rotated (`token_rotated`) or has expired (`token_expired`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Too many requests from this IP", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/inspect/{token}/documents/{document_id}": { "get": { "tags": [ "inspect" ], "summary": "Download a document of the inspected consignment note", "description": "The file behind a document listed in the view, through the same token. Only documents of that shipment resolve; everything else is a 404.", "parameters": [ { "schema": { "type": "string", "minLength": 20, "maxLength": 128, "description": "The token from the inspection URL" }, "required": true, "description": "The token from the inspection URL", "name": "token", "in": "path" }, { "schema": { "type": "string", "example": "doc_01K4Y0000000000000000DEM01" }, "required": true, "name": "document_id", "in": "path" } ], "responses": { "200": { "description": "The file, inline, with its stored mime type", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The document id is malformed", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "Unknown token, or no such document on this shipment", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "410": { "description": "The token was rotated (`token_rotated`) or has expired (`token_expired`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Too many requests from this IP", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/providers": { "get": { "tags": [ "providers" ], "summary": "List providers", "description": "Every eCMR provider Cargofollow knows, with what its adapter supports and whether this organisation may use it in this mode. A provider that is not `implemented` has no adapter yet and cannot be selected.", "responses": { "200": { "description": "The provider catalogue", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } }, "required": [ "data" ], "description": "The provider catalogue for this organisation and mode" } } } } } } }, "/v1/provider-routing-rules": { "get": { "tags": [ "providers" ], "summary": "List provider routing rules", "description": "Corridor rules in the order they are evaluated: lowest `priority` first, oldest first within a priority. Requires the scope `organization:manage`.", "responses": { "200": { "description": "Every rule of this organisation and mode", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderRoutingRule" } } }, "required": [ "data" ], "description": "Corridor rules, lowest priority first" } } } } } }, "post": { "tags": [ "providers" ], "summary": "Create a provider routing rule", "description": "A rule sends every shipment matching its corridor to one provider. A `match` field left out matches anything, so an empty `match` is a catch-all. Requires the scope `organization:manage`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priority": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 100 }, "match": { "type": "object", "properties": { "origin_country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Country of the place of loading" }, "destination_country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Country of the place of delivery" }, "carrier_country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Country the carrier is established in" }, "transport_type": { "type": [ "string", "null" ], "enum": [ "national", "international", "cabotage", "combined", null ], "description": "Kind of transport; derived from the countries when not given, cabotage and combined only on explicit input" } }, "default": {}, "description": "Predicate over the corridor; every field left out matches anything" }, "provider": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "eCMR provider that executes the consignment" }, "active": { "type": "boolean", "default": true } }, "required": [ "provider" ], "description": "New corridor rule" } } } }, "responses": { "201": { "description": "The rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderRoutingRule" } } } }, "422": { "description": "The provider is unknown, not enabled for this organisation, or has no adapter", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/provider-routing-rules/{id}": { "get": { "tags": [ "providers" ], "summary": "Get a provider routing rule", "description": "Requires the scope `organization:manage`.", "parameters": [ { "schema": { "type": "string", "example": "prr_01J9Z3MREBS6N1VQ0P8T4W7K2C" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderRoutingRule" } } } }, "404": { "description": "No rule with this id in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "patch": { "tags": [ "providers" ], "summary": "Update a provider routing rule", "description": "Changes the priority, the corridor, the provider or whether the rule is active. `match` is replaced as a whole. Requires the scope `organization:manage`.", "parameters": [ { "schema": { "type": "string", "example": "prr_01J9Z3MREBS6N1VQ0P8T4W7K2C" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priority": { "type": "integer", "minimum": 0, "maximum": 100000 }, "match": { "type": "object", "properties": { "origin_country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Country of the place of loading" }, "destination_country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Country of the place of delivery" }, "carrier_country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Country the carrier is established in" }, "transport_type": { "type": [ "string", "null" ], "enum": [ "national", "international", "cabotage", "combined", null ], "description": "Kind of transport; derived from the countries when not given, cabotage and combined only on explicit input" } }, "description": "Predicate over the corridor; every field left out matches anything" }, "provider": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "eCMR provider that executes the consignment" }, "active": { "type": "boolean" } }, "description": "Fields to change on a corridor rule" } } } }, "responses": { "200": { "description": "The updated rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderRoutingRule" } } } }, "404": { "description": "No rule with this id in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The provider is unknown, not enabled for this organisation, or has no adapter", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "delete": { "tags": [ "providers" ], "summary": "Delete a provider routing rule", "description": "Shipments created after this stop matching it. Requires the scope `organization:manage`.", "parameters": [ { "schema": { "type": "string", "example": "prr_01J9Z3MREBS6N1VQ0P8T4W7K2C" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "No rule with this id in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/requirements": { "get": { "tags": [ "requirements" ], "summary": "Requirements for a lane", "description": "What a corridor asks for before the truck rolls: whether an electronic consignment note is legally valid at both ends, which documents an inspector may ask for, and which eFTI subset each of those documents belongs to. Every rule carries the source it is based on and the date that source was last checked, so an answer can be verified rather than believed. The rules are data (ADR 0012) and the same set feeds the warnings on create and issue. `recommended_trust_level` is the signature level the lane argues for (M5-02): the e-CMR Protocol describes an advanced signature, and German and French law occasionally attach something to a qualified one. Informative: it is not legal advice.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of the place of taking over the goods" }, "required": true, "description": "Country of the place of taking over the goods", "name": "origin", "in": "query" }, { "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of the place of delivery" }, "required": true, "description": "Country of the place of delivery", "name": "destination", "in": "query" }, { "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country where the carrier is established; decides cabotage and posting" }, "required": false, "description": "Country where the carrier is established; decides cabotage and posting", "name": "carrier_country", "in": "query" }, { "schema": { "type": "string", "enum": [ "national", "international", "cabotage", "combined" ], "description": "Overrides the type derived from the countries and `combined`" }, "required": false, "description": "Overrides the type derived from the countries and `combined`", "name": "transport_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "native", "mock", "pionira", "transfollow", "dashdoc", "olf" ], "description": "The eCMR provider the shipment runs on; decides the Belgian recognition rule" }, "required": false, "description": "The eCMR provider the shipment runs on; decides the Belgian recognition rule", "name": "provider", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false", "description": "Dangerous goods under ADR are on board" }, "required": false, "description": "Dangerous goods under ADR are on board", "name": "adr", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false", "description": "Part of the journey runs by rail, inland waterway or sea" }, "required": false, "description": "Part of the journey runs by rail, inland waterway or sea", "name": "combined", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false", "description": "The consignment is a waste shipment under Regulation (EU) 2024/1157" }, "required": false, "description": "The consignment is a waste shipment under Regulation (EU) 2024/1157", "name": "waste", "in": "query" } ], "responses": { "200": { "description": "The rules that apply to this lane", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Requirements" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "A query parameter is invalid, for example a country the engine has no rules for", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/validate": { "post": { "tags": [ "validate" ], "summary": "Validate a shipment without an API key", "security": [], "description": "The same two validation layers as `POST /v1/shipments` — the canonical model and the business rule register — plus the country rules of `GET /v1/requirements`, for anyone without an account. Nothing is stored: not the shipment, not the body, not a version. Guarded by Cloudflare Turnstile (token in `cf-turnstile-response` or in `turnstile_token`) and limited to 10 requests per minute per IP. Messages follow `Accept-Language`.", "requestBody": { "required": true, "content": { "application/json": { "examples": { "nl-de": { "summary": "International carriage Rotterdam → Stuttgart", "description": "Plain road consignment with a Polish carrier; `transport_type` is derived.", "value": { "reference": "ORD-2026-0917", "consignor": { "name": "Van der Berg Logistiek B.V.", "address": { "street": "Havenweg 12", "postal_code": "3089 JG", "city": "Rotterdam", "country": "NL" }, "contact": { "name": "S. Jansen", "email": "planning@vdb-logistiek.example", "phone": "+31101234567", "language": "nl" }, "vat_number": "NL001234567B01" }, "carrier": { "name": "Transport Nowak Sp. z o.o.", "address": { "street": "ul. Przemysłowa 8", "postal_code": "61-001", "city": "Poznań", "country": "PL" }, "contact": { "phone": "+48601234567" } }, "consignee": { "name": "Müller Maschinenbau GmbH", "address": { "street": "Industriestraße 4", "postal_code": "70565", "city": "Stuttgart", "country": "DE" }, "contact": { "name": "K. Müller", "email": "wareneingang@mueller-mb.example" } }, "pickup": { "address": { "street": "Havenweg 12", "postal_code": "3089 JG", "city": "Rotterdam", "country": "NL" }, "window": { "from": "2026-09-14T08:00:00+02:00", "to": "2026-09-14T12:00:00+02:00" }, "instructions": "Report at gate 3" }, "delivery": { "address": { "street": "Industriestraße 4", "postal_code": "70565", "city": "Stuttgart", "country": "DE" }, "window": { "from": "2026-09-15T07:00:00+02:00", "to": "2026-09-15T16:00:00+02:00" }, "contact": { "name": "Wareneingang", "phone": "+4971112345678" } }, "goods": [ { "description": "CNC machine parts", "marks": "MM-4471", "quantity": 12, "package_type": "pallet", "gross_weight_kg": 8400, "volume_m3": 14.2, "hs_code": "84669390" } ], "vehicle": { "plate": "PO 12345", "trailer_plate": "PO 98765", "country": "PL" }, "driver": { "name": "Marek Nowak", "phone": "+48601234568", "language": "pl" }, "charges": { "carriage": { "amount": "1250.00", "currency": "EUR" }, "payer": "consignor" }, "special_agreements": "Temperature not controlled", "metadata": { "tms_order": "4711" } } }, "adr": { "summary": "Dangerous goods under ADR", "description": "Same corridor with UN 1263; the ADR particulars are business rules, not schema.", "value": { "reference": "ORD-2026-0918", "consignor": { "name": "Van der Berg Logistiek B.V.", "address": { "street": "Havenweg 12", "postal_code": "3089 JG", "city": "Rotterdam", "country": "NL" }, "contact": { "name": "S. Jansen", "email": "planning@vdb-logistiek.example", "phone": "+31101234567", "language": "nl" }, "vat_number": "NL001234567B01" }, "carrier": { "name": "Transport Nowak Sp. z o.o.", "address": { "street": "ul. Przemysłowa 8", "postal_code": "61-001", "city": "Poznań", "country": "PL" }, "contact": { "phone": "+48601234567" } }, "consignee": { "name": "Müller Maschinenbau GmbH", "address": { "street": "Industriestraße 4", "postal_code": "70565", "city": "Stuttgart", "country": "DE" }, "contact": { "name": "K. Müller", "email": "wareneingang@mueller-mb.example" } }, "pickup": { "address": { "street": "Havenweg 12", "postal_code": "3089 JG", "city": "Rotterdam", "country": "NL" }, "window": { "from": "2026-09-14T08:00:00+02:00", "to": "2026-09-14T12:00:00+02:00" }, "instructions": "Report at gate 3" }, "delivery": { "address": { "street": "Industriestraße 4", "postal_code": "70565", "city": "Stuttgart", "country": "DE" }, "window": { "from": "2026-09-15T07:00:00+02:00", "to": "2026-09-15T16:00:00+02:00" }, "contact": { "name": "Wareneingang", "phone": "+4971112345678" } }, "goods": [ { "description": "Paint, flammable liquid", "marks": "VDB-8891", "quantity": 4, "package_type": "drum", "gross_weight_kg": 760, "adr": { "un_number": "1263", "class": "3", "packing_group": "III", "proper_shipping_name": "PAINT", "tunnel_code": "(D/E)" } } ], "vehicle": { "plate": "PO 12345", "trailer_plate": "PO 98765", "country": "PL" }, "driver": { "name": "Marek Nowak", "phone": "+48601234568", "language": "pl" }, "charges": { "carriage": { "amount": "1250.00", "currency": "EUR" }, "payer": "consignor" }, "special_agreements": "Temperature not controlled", "metadata": { "tms_order": "4711" }, "documents_attached": [ "ADR transport document" ] } } }, "schema": { "$ref": "#/components/schemas/PublicValidateInput" } } } }, "responses": { "200": { "description": "The findings a create would produce, plus the rules this lane asks for", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicValidationResult" } } } }, "403": { "description": "The Turnstile token is missing, expired, reused or rejected", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The body does not match the canonical model", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "More than the per-IP limit of requests in a minute", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/contact": { "post": { "tags": [ "contact" ], "summary": "Send the marketing site a message", "security": [], "description": "Delivers one message from the contact form on cargofollow.com to Cargofollow. Nothing is stored: not the message, not the address, not a copy — the mailbox is the record. The visitor's address becomes `Reply-To` and never `From`. Guarded by Cloudflare Turnstile (token in `cf-turnstile-response` or in `turnstile_token`) and limited to 5 messages per 10 minutes per IP.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactMessageInput" } } } }, "responses": { "202": { "description": "The message was handed to the sender", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactMessageResult" } } } }, "403": { "description": "The Turnstile token is missing, expired, reused or rejected", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "A field is missing, empty or longer than this form accepts", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "More than the per-IP limit of messages in the window", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "503": { "description": "The sender rejected the message; nothing was delivered", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/test/shipments/{id}/simulate": { "post": { "tags": [ "test" ], "summary": "Drive a sandbox shipment through a lifecycle step", "description": "Test mode only; a live key answers 403 `test_mode_only`. `sign` records one API signature for the role the status expects next (or for `role`), `deliver` signs whatever is still missing until the shipment is `delivered`, `remark` adds a reservation, and `auto` hands the shipment to the `SANDBOX_ADVANCE` workflow, which issues, signs, remarks and delivers it by itself. Every step runs through the normal services, so the events and the webhooks are the ones a live shipment produces; the evidence of a simulated signature carries `simulated: true`.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y000000000000000DEM04A", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "action": "deliver", "type": "damage" }, "schema": { "$ref": "#/components/schemas/Simulate" } } } }, "responses": { "200": { "description": "What the simulation did, and the status the shipment is in now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateResult" } } } }, "400": { "description": "The path parameter is not a shipment id, or the body is not JSON", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "A live key (`test_mode_only`), the flag `auto_advance_sandbox` is off (`forbidden`), or the key lacks the scope `signatures:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The shipment is in a status this action cannot act on", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The body is not a known action", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/test/shipments/{id}/simulation": { "get": { "tags": [ "test" ], "summary": "Read the progress of an auto-advance run", "description": "The steps of the `auto` run in order, marked done by the events they left in the chain, plus the status of the workflow instance. Test mode only.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y000000000000000DEM04A", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The progress of the simulation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Simulation" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "A live key (`test_mode_only`), or the key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment in this organisation and mode", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/tours": { "post": { "tags": [ "tours" ], "summary": "Plan a tour", "description": "Groups shipments into one run. Each stop names a shipment and which half of it is being driven: `pickup` at the consignor, `delivery` at the consignee. The order of `stops` is the order the driver drives; Cargofollow never rearranges it. Routing and optimisation are deliberately not part of this API. A shipment may sit in at most one tour that is still `planned` or `active`. Appends `shipment.updated` with `changed_paths: [\"tour_id\"]` to every shipment that joined.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourCreate" } } } }, "responses": { "201": { "description": "The tour was planned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tour" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A shipment is already planned in another active tour", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "A field is missing or invalid, or a shipment is unknown or cancelled", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "tags": [ "tours" ], "summary": "List tours", "description": "Newest first. Filter by `status` to see only what is still going to be driven.", "parameters": [ { "schema": { "type": "string", "enum": [ "planned", "active", "completed", "cancelled" ], "description": "Status of a tour" }, "required": false, "description": "Status of a tour", "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "The tours of this organisation and mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourList" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "A query parameter is invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tours/{id}": { "get": { "tags": [ "tours" ], "summary": "Read one tour", "description": "The stops in driving order, each with whether its signature already exists.", "parameters": [ { "schema": { "type": "string", "example": "tor_01J9Z…" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The tour", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tour" } } } }, "400": { "description": "The tour id is malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such tour in this organisation and mode", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "tours" ], "summary": "Reorder a tour, add stops to it, or close it", "description": "`stops` replaces the whole ordered list, because reordering and adding are the same edit: a position means nothing without the other positions. The order of `stops` is the order the driver drives; Cargofollow never rearranges it. Routing and optimisation are deliberately not part of this API. A `status` that is no longer `planned` or `active` releases every shipment the tour held, so they can be planned again. Appends `shipment.updated` with `changed_paths: [\"tour_id\"]` to every shipment that joined or left.", "parameters": [ { "schema": { "type": "string", "example": "tor_01J9Z…" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourPatch" } } } }, "responses": { "200": { "description": "The tour as it now stands", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tour" } } } }, "400": { "description": "The tour id is malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such tour in this organisation and mode", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A shipment is already planned in another active tour", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "A field is invalid, or a shipment is unknown or cancelled", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/driver/otp": { "post": { "tags": [ "driver" ], "summary": "Send a driver a sign-in code", "description": "Texts a six-digit code to the number, when that number is named as `driver.phone` on a shipment of the last 30 days. A number we do not know gets the same answer and no message: this endpoint takes a phone number without a key, so a different response would turn it into a directory of everyone who drives for a customer. The code lives ten minutes and survives five wrong guesses. Limited to five codes per number per ten minutes, and to five requests per ten minutes per IP.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriverPhoneBody" } } } }, "responses": { "200": { "description": "A code is on its way, or the number is unknown — the same either way", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriverOtpSent" } } } }, "422": { "description": "`phone` is not a phone number with a country code", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Too many codes for this number, or too many requests from this IP", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/driver/otp/verify": { "post": { "tags": [ "driver" ], "summary": "Exchange a code for a driver session", "description": "Answers a session token that is scoped to this phone number and one mode, and to nothing else: no organisation and no API scopes. The mode follows from the work the number does — live as soon as it drives on a live consignment note, sandbox otherwise — so it is never something a caller can choose. It lives twelve hours, is stored hashed, and is shown exactly once — send it back as `Authorization: Bearer`. Verifying a new code replaces the previous session for the same number, so signing in on another phone signs the old one out.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriverOtpVerifyBody" } } } }, "responses": { "200": { "description": "The session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriverSession" } } } }, "401": { "description": "The code was already used", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The code is wrong or expired, or `phone` is not a phone number", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "429": { "description": "Five wrong codes; ask for a new one", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/driver/shipments": { "get": { "tags": [ "driver" ], "summary": "The driver's own open shipments", "description": "Every `issued` or `in_transit` shipment that names this session's number as `driver.phone`, whatever organisation it belongs to but only in the mode of the session, earliest time window first. Each row names the organisation whose consignment note it is, so a driver can see who is asking for the signature. Each one carries the link that opens the flow its status calls for: the pickup session at loading, the single-signer flow at delivery. Those links are created on the spot and live as long as the session; a shipment whose role has already signed carries none. Contact people and charges are not part of the overview.", "responses": { "200": { "description": "The open shipments of this driver", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriverShipmentList" } } } }, "401": { "description": "No, unknown or expired session token", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/driver/session": { "delete": { "tags": [ "driver" ], "summary": "Sign out", "description": "Burns the session token on the server, so the sign links it created stop being reachable from it. Answers 204 whether or not the token was still valid, because there is nothing to learn from the difference.", "responses": { "204": { "description": "Signed out" } } } }, "/v1/shipments/{id}/efti": { "get": { "tags": [ "efti" ], "summary": "Read the eFTI data set of a shipment, as the common data set or as a subset", "description": "The consignment of Regulation (EU) 2020/1056 as the eFTI common data set of Delegated Regulation (EU) 2024/2024, projected from the current version of the shipment. With `?subset=` the response is pruned to one legal ground (`EU2`, `EU3`, `EU5a`); without it it is the full common data set. `Accept: application/xml` returns the XML that validates against `consignment-common.xsd`, anything else the JSON mirror of that same document with the validation report next to it. The report says what the subset asks for and this shipment does not carry (`missing_required`) and what the canonical model cannot carry at all (`unmapped`); neither makes the XML invalid, because every eFTI element is optional.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "EU3", "description": "The subset to project onto (`EU2`, `EU3`, `EU5a`, in either spelling: `EU3` or `EU03`). Without it the response carries the common data set." }, "required": false, "description": "The subset to project onto (`EU2`, `EU3`, `EU5a`, in either spelling: `EU3` or `EU03`). Without it the response carries the common data set.", "name": "subset", "in": "query" } ], "responses": { "200": { "description": "The eFTI data set, as JSON with its validation report or as eFTI XML", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EftiDataset" } }, "application/xml": { "schema": { "type": "string", "format": "xml", "example": "…" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`, or the flag `efti_projection` is off", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "`subset` is not a subset Cargofollow projects (`subset_unknown`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/uil": { "get": { "tags": [ "efti" ], "summary": "Read the Unique Identifier Link of a shipment", "description": "The UIL of IR (EU) 2025/2243: the handle a control authority uses to pull this consignment from Cargofollow through the national eFTI gate. It is issued when the carrier signs a shipment of an organisation with the flag `efti_projection`, together with the event `efti.uil_issued`, and never changes afterwards. Until then `uil` and `issued_at` are null. The three components — gate, platform and dataset UUID — follow the reference implementation (`schema/xsd/edelivery.xsd`); `uil_string` is the flat rendering Cargofollow uses where one string is needed.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The eFTI data set of the shipment with its UIL, or nulls while it has none", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Uil" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`, or the flag `efti_projection` is off", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/authorisations": { "get": { "tags": [ "efti" ], "summary": "Read the eFTI authorisation register of a shipment", "description": "Who may perform which processing operation on this eFTI data set, for how long, over which part of the data — the registry of Article 5 of Implementing Regulation (EU) 2025/2243. Withdrawn rights stay in the answer with `status: \"revoked\"` and the moment they were withdrawn, because Article 5(6) keeps the register auditable for as long as the data set itself has to stay available. The first entry is always the data holder: the organisation that owns the shipment holds every operation on the whole common data set, and that right cannot be withdrawn.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The register of this data set, oldest entry first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EftiAuthorisationList" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "post": { "tags": [ "efti" ], "summary": "Grant a processing right on an eFTI data set", "description": "Records a processing right for one party on this data set. Leave `operations` out and the party gets what its `role` needs, which is the answer in almost every case: a carrier reads, downloads, signs box 23 and files a waste transfer confirmation; a consignee reads, downloads and signs box 24. A party with no Cargofollow account is named by `email` or `phone` — the non-onboarded user of Article 5(1)(b) — and such a right must end: `valid_until` is required and may not run longer than 90 days. Only a party with the `primary` designation may grant; a `temporary` authoriser may grant to non-onboarded parties only.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EftiAuthorisationGrant" } } } }, "responses": { "201": { "description": "The recorded right", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EftiAuthorisation" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:write`, or this party may not authorise", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "This party already holds a right in this role (`conflict`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The body does not describe a grantable right", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/authorisations/{authorisation_id}": { "delete": { "tags": [ "efti" ], "summary": "Withdraw a processing right", "description": "Withdraws the right and leaves the entry in the register with `status: \"revoked\"`. Nothing is deleted: Article 5(6) of Implementing Regulation (EU) 2025/2243 keeps the register available for auditing for at least as long as the data set, and the difference between \"never held it\" and \"held it until Tuesday\" is what an audit is looking for. Everything the party did while it held the right stays in `GET /v1/shipments/{id}/processing-log`. The data holder's own right cannot be withdrawn.", "parameters": [ { "schema": { "type": "string", "example": "shp_01J9ZQ8F0A0000000000000000" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "atz_01J9ZQ8F0A0000000000000000" }, "required": true, "name": "authorisation_id", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EftiAuthorisationRevocation" } } } }, "responses": { "204": { "description": "Withdrawn, or already withdrawn" }, "400": { "description": "A path parameter is not an id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:write`, or this party may not authorise", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment or no such right", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The data holder's own right cannot be withdrawn (`conflict`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/processing-log": { "get": { "tags": [ "efti" ], "summary": "Read the processing log of an eFTI data set", "description": "Every processing operation performed on this data set, newest first, as Article 9(5) of Implementing Regulation (EU) 2025/2243 requires it recorded: the UUID of the data set, a coded identification of the party, the moment and the operation. Refusals are in here too — a register that only records what it allowed cannot show that it was ever consulted. Access by a competent authority through a national eFTI gate appears with `party.type: \"authority\"` and the gate id as the reference; that access is recorded and never refused, because Article 9(4)(a) makes it automatic.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The processing log of this data set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EftiProcessingLog" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/shipments/{id}/combined-transport-stamps": { "post": { "tags": [ "efti" ], "summary": "Record a combined transport stamp", "description": "The stamp of Article 3 of Council Directive 92/106/EEC: the confirmation by a railway or port authority that a non-road leg of a combined transport operation has been completed. IR (EU) 2025/2243 Article 9(1) lists affixing it as a processing operation of its own, next to the three signatures, which is why it is not a field on the shipment. One stamp confirms one leg and names both ends of it; a shipment with a rail leg and a maritime leg carries two. Appends `efti.combined_transport_stamped` and creates no new shipment version: a terminal confirming its own leg may not move a signature. Only for `transport_type: \"combined\"`, and only once the consignment note has been issued.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CombinedTransportStampCreate" } } } }, "responses": { "201": { "description": "The stamp was recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CombinedTransportStamp" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "409": { "description": "The shipment is not a combined transport, or is still a draft, or was cancelled (`invalid_state`)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "A field is missing or invalid", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } }, "get": { "tags": [ "efti" ], "summary": "List the combined transport stamps of a shipment", "description": "Oldest leg first, by the moment the authority stamped rather than by the moment it was recorded. A shipment that is not a combined transport simply has none.", "parameters": [ { "schema": { "type": "string", "example": "shp_01K4Y0000000000000000DEM01", "description": "Shipment id" }, "required": true, "description": "Shipment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The combined transport stamps of this shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CombinedTransportStampList" } } } }, "400": { "description": "The path parameter is not a shipment id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "404": { "description": "No such shipment", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/export": { "post": { "tags": [ "export" ], "summary": "Start an export of this organisation", "description": "Starts the EXPORT Workflow, which bundles every shipment of this mode as JSON (all versions, events, signatures and remarks) together with its documents into one zip in R2. Poll `GET /v1/export/{id}` for the status and the download link. An export covers at most 10000 shipments; use `since` and `until` to page through a larger history. The zip and its status are kept for seven days.", "requestBody": { "required": false, "description": "Which shipments to export; an empty body exports the whole organisation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time", "description": "Only shipments created at or after this moment" }, "until": { "type": "string", "format": "date-time", "description": "Only shipments created at or before this moment" } } } } } }, "responses": { "202": { "description": "The export was accepted and is being built", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } }, "403": { "description": "The key lacks the scope `export:read`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`since` or `until` is not an ISO 8601 timestamp", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/export/{id}": { "get": { "tags": [ "export" ], "summary": "Read the status of an export", "description": "Once the status is `completed`, `download_url` is a signed link to the zip that lasts one hour; ask again for a fresh one. Seven days after the request the export is gone.", "parameters": [ { "schema": { "type": "string", "description": "Export id, for example exp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2" }, "required": true, "description": "Export id, for example exp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The export", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } }, "400": { "description": "The export id is malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks the scope `export:read`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such export in this organisation and mode, or it expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/export/{id}/download": { "get": { "tags": [ "export" ], "summary": "Download the zip behind a signed link", "description": "Takes no API key: the `sig` query parameter is the authorisation. Links last one hour.", "security": [], "parameters": [ { "schema": { "type": "string", "description": "Export id, for example exp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2" }, "required": true, "description": "Export id, for example exp_01J8Z3K2Q4R5S6T7V8W9X0Y1Z2", "name": "id", "in": "path" }, { "schema": { "type": "string", "pattern": "^\\d{1,15}$", "description": "Unix timestamp in seconds at which the link stops working" }, "required": true, "description": "Unix timestamp in seconds at which the link stops working", "name": "exp", "in": "query" }, { "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "HMAC-SHA256 of \"export:.\" with the download signing secret" }, "required": true, "description": "HMAC-SHA256 of \"export:.\" with the download signing secret", "name": "sig", "in": "query" } ], "responses": { "200": { "description": "The zip", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The export id is malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The signature does not match this export", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such export, or its zip is gone from R2", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "410": { "description": "The link expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`exp` or `sig` is missing or malformed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/privacy/erasure": { "post": { "tags": [ "privacy" ], "summary": "Erase a data subject from this organisation", "description": "Pseudonymises every contact, driver and signer of this organisation and mode that carries the given e-mail address or phone number: the name becomes \"verwijderd\", the contact details are cleared and drawn signature images are deleted from storage. Matching is exact on the address or number, case-insensitive. The hash chain and the version snapshots are left alone on purpose — they are the evidence of the contract of carriage and rewriting them would break every hash and signature — so the response repeats that limitation and points at `DELETE /v1/shipments/{id}` as the way to remove those too. Safe to repeat: a second call finds nothing left to change.", "requestBody": { "required": true, "content": { "application/json": { "example": { "email": "chauffeur@example.com" }, "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "E-mail address of the data subject" }, "phone": { "type": "string", "description": "Phone number of the data subject, E.164" } }, "description": "The data subject to erase from this organisation" } } } }, "responses": { "200": { "description": "What was pseudonymised or deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "shipments_scanned": { "type": "integer", "description": "Shipments that mentioned the subject" }, "shipments_updated": { "type": "integer", "description": "Shipments whose contacts were pseudonymised" }, "signatures_updated": { "type": "integer", "description": "Signatures whose signer was pseudonymised" }, "signature_images_deleted": { "type": "integer", "description": "Signature images removed from storage" }, "limitations": { "type": "array", "items": { "type": "string" }, "description": "What this operation cannot reach, and what to do instead" } }, "required": [ "shipments_scanned", "shipments_updated", "signatures_updated", "signature_images_deleted", "limitations" ], "description": "What the erasure changed" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `shipments:write`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "Neither an email nor a phone was given", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/usage": { "get": { "tags": [ "usage" ], "summary": "Usage of the organisation per day", "description": "The counters the invoice is built from: shipments issued, signatures, notifications, documents and the bytes stored, per UTC day and for the window as a whole. The window is at most 366 days and defaults to the last 30. Test-mode usage is counted and shown but never charged. Requires the scope `events:read`.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Inclusive first UTC day; defaults to 30 days before `to`", "example": "2026-09-01" }, "required": false, "description": "Inclusive first UTC day; defaults to 30 days before `to`", "name": "from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Inclusive last UTC day; defaults to today", "example": "2026-09-30" }, "required": false, "description": "Inclusive last UTC day; defaults to today", "name": "to", "in": "query" } ], "responses": { "200": { "description": "The usage of the window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "description": "No or unknown API key", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "403": { "description": "The key lacks the scope `events:read`", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The window is inverted or longer than the maximum", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/v1/billing/stripe/webhook": { "post": { "tags": [ "billing" ], "summary": "Inbound billing-provider webhook", "description": "Verifies the `stripe-signature` header against the raw body and applies what the event says: `invoice.paid` puts the organisation back on `active`, `invoice.payment_failed` puts it on `past_due`, and a subscription event carries the tier. An event about a customer this deployment does not know is accepted and ignored rather than refused, so a shared endpoint does not send the sender into a retry loop. Not part of the public API surface: no API key opens it and no SDK call belongs on it.", "security": [], "parameters": [ { "schema": { "type": "string", "description": "`t=,v1=` over \".\"" }, "required": false, "description": "`t=,v1=` over \".\"", "name": "stripe-signature", "in": "header" } ], "requestBody": { "required": true, "description": "The provider's own event body; the adapter decides what it accepts.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "The signature held; the body says what was done with it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingWebhookResult" } } } }, "401": { "description": "The signature is missing, malformed, stale or wrong", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } }, "422": { "description": "The signature held but the body is not JSON", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI of the error documentation" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path of the field, for example \"goods[0].gross_weight_kg\"" }, "code": { "type": "string", "description": "Stable code of the finding" }, "message": { "type": "string", "description": "Human-readable message in the requested language" }, "rule": { "type": "string", "description": "Business rule that produced the finding" }, "source": { "type": "string", "description": "Law or standard the rule refers to" }, "params": { "type": "object", "additionalProperties": {}, "description": "Values the message was built from" } }, "required": [ "path", "code", "message" ], "description": "Field-level error or warning" } } }, "required": [ "type", "title", "status", "code", "errors", "warnings" ], "description": "Problem details (RFC 9457)" } } } } } } }, "/providers/{name}/webhook": { "post": { "tags": [ "providers-webhook" ], "summary": "Inbound provider webhook", "description": "Hands the request to the named adapter, which verifies it and normalises it to shipment events. Each event is matched to a shipment through `provider_links.external_id` and appended to its hash chain. An unknown provider, a provider whose `capabilities.webhooks` is false and an unknown external id all answer 404. What a provider accepts is documented in packages/providers.", "security": [], "parameters": [ { "schema": { "type": "string", "description": "Provider name, one of: native, mock, pionira, transfollow, dashdoc, olf", "example": "mock" }, "required": true, "description": "Provider name, one of: native, mock, pionira, transfollow, dashdoc, olf", "name": "name", "in": "path" } ], "requestBody": { "required": true, "description": "The provider's own webhook payload; the adapter decides what it accepts.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "The webhook was accepted and every event it carried was applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderWebhookResult" } } } }, "401": { "description": "The adapter rejected the request's signature", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Unknown provider, no webhooks for this provider, or unknown external id", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The external id is linked to more than one shipment", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The event does not match its schema in the catalogue", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "The adapter for this provider is not implemented yet", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The adapter failed for a reason of its own", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "webhooks": {} }