{ "info": { "_postman_id": "e6347a5b-e2c8-4d47-865b-5889e9115c0b", "name": "Docuten eCMR API 2.0", "description": "Public API of the Docuten eCMR microservice: lots, shipments and parties.\n\nGenerated from `src/main/resources/openapi/openapi.yaml` (spec version 1.0.0) with\n`scripts/generate-postman-collection.mjs`. Regenerate it instead of editing requests by hand.\n\n## Getting started\n\n1. Import one of the environments under `postman/environments/` and select it.\n2. Set `apiKey` in the environment (header `X-API-KEY`, issued by Docuten per client).\n3. Set `documentBase64` to the Base64 of a PDF, and point the `*Email` variables at mailboxes\n you own — the API sends real notifications to the parties.\n4. Run *Create a Lot* (asynchronous) or *Create a Shipment* (synchronous). Both store the ids\n they return in the collection variables `lotId`, `shipmentId` and `partyId`, so the detail,\n attachment, cancel, resend-notification and reassign requests work with no copy-pasting.\n\nAll timestamps are UTC (ISO-8601). Docuten calls back into the microservice on its own\nendpoints, which are not part of this collection.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_exporter_id": "4266556", "_collection_link": "https://go.postman.co/collection/4266556-e6347a5b-e2c8-4d47-865b-5889e9115c0b?source=collection_link" }, "item": [ { "name": "lot", "item": [ { "name": "Create a Lot", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"201 Created\", () => pm.response.to.have.status(201));", "", "const lot = pm.response.json();", "pm.collectionVariables.set(\"lotId\", lot.lot_id);", "", "const shipment = (lot.shipments || [])[0];", "if (shipment) {", " pm.collectionVariables.set(\"shipmentId\", shipment.shipment_id);", " const pending = (shipment.parties || []).find((party) => party.status === \"pending\");", " if (pending) {", " pm.collectionVariables.set(\"partyId\", pending.party_id);", " }", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"lot_reference\": \"L-2026-000001\",\n \"lot_name\": \"Expedición Madrid-Barcelona\",\n \"callback_url\": \"{{callbackUrl}}\",\n \"shipments\": [\n {\n \"shipment_reference\": \"SHP-0001\",\n \"shipment_name\": \"Porte 1: Palets alimentación\",\n \"origin\": {\n \"address\": \"C/ Almacenes 12\",\n \"post_code\": \"28050\",\n \"city\": \"Madrid\",\n \"country_code\": \"ES\"\n },\n \"destination\": {\n \"address\": \"Pol. Ind. La Marina, C/ Delta 9\",\n \"post_code\": \"08020\",\n \"city\": \"Barcelona\",\n \"country_code\": \"ES\"\n },\n \"parties\": {\n \"consignors\": [\n {\n \"name\": \"ACME Logistics SL\",\n \"tax_id\": \"99999972C\",\n \"order\": 1,\n \"signing_role\": \"signer\",\n \"signature_type\": \"biometric\",\n \"channel\": \"email\",\n \"email\": \"{{consignorEmail}}\",\n \"language\": \"es\"\n }\n ],\n \"drivers\": [\n {\n \"name\": \"Juan Pérez\",\n \"tax_id\": \"99999972C\",\n \"order\": 2,\n \"signing_role\": \"signer\",\n \"signature_type\": \"biometric\",\n \"channel\": \"email\",\n \"email\": \"{{driverEmail}}\",\n \"language\": \"es\",\n \"license_plate\": \"1234ABC\"\n }\n ],\n \"consignees\": [\n {\n \"name\": \"Receptor SA\",\n \"tax_id\": \"99999972C\",\n \"order\": 3,\n \"signing_role\": \"signer\",\n \"signature_type\": \"biometric\",\n \"channel\": \"email\",\n \"email\": \"{{consigneeEmail}}\",\n \"language\": \"es\"\n }\n ]\n },\n \"goods\": [\n {\n \"good_description\": \"Palets yogur\",\n \"cargo_type\": \"paletizado\",\n \"good_gross_mass\": 3500.5,\n \"dangerous_goods\": false\n }\n ],\n \"documents\": [\n {\n \"document_type\": \"ecmr\",\n \"document_name\": \"eCMR-0001.pdf\",\n \"external_id\": \"EXT-ECMR-0001\",\n \"content\": \"{{documentBase64}}\",\n \"signable\": true,\n \"signers\": [\n {\n \"order\": 1,\n \"coordinate\": {\n \"sig_page\": 0,\n \"top_left_corner_x\": 120,\n \"top_left_corner_y\": 650,\n \"width\": 180,\n \"height\": 60\n }\n },\n {\n \"order\": 2,\n \"coordinate\": {\n \"sig_page\": 0,\n \"top_left_corner_x\": 120,\n \"top_left_corner_y\": 560,\n \"width\": 180,\n \"height\": 60\n }\n },\n {\n \"order\": 3,\n \"coordinate\": {\n \"sig_page\": 0,\n \"top_left_corner_x\": 120,\n \"top_left_corner_y\": 470,\n \"width\": 180,\n \"height\": 60\n }\n }\n ]\n }\n ],\n \"language\": \"es\"\n }\n ]\n}\n", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/lots", "host": [ "{{baseUrl}}" ], "path": [ "lots" ] } }, "response": [] }, { "name": "Get a lot details", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"200 OK\", () => pm.response.to.have.status(200));" ] } } ], "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/lots/:id", "host": [ "{{baseUrl}}" ], "path": [ "lots", ":id" ], "variable": [ { "key": "id", "value": "{{lotId}}", "description": "(Required) " } ] } }, "response": [] } ], "description": "Everything about Lots" }, { "name": "shipment", "item": [ { "name": "Create a Shipment", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"201 Created\", () => pm.response.to.have.status(201));", "", "const shipment = pm.response.json();", "pm.collectionVariables.set(\"shipmentId\", shipment.shipment_id);", "", "// The party holding the signing turn: the one to resend a notification to or reassign.", "const pending = (shipment.parties || []).find((party) => party.status === \"pending\");", "if (pending) {", " pm.collectionVariables.set(\"partyId\", pending.party_id);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"shipment_reference\": \"SHP-STANDALONE-0001\",\n \"shipment_name\": \"Porte directo sin lote\",\n \"origin\": {\n \"address\": \"C/ Almacenes 12\",\n \"post_code\": \"28050\",\n \"city\": \"Madrid\",\n \"country_code\": \"ES\"\n },\n \"destination\": {\n \"address\": \"Pol. Ind. La Marina, C/ Delta 9\",\n \"post_code\": \"08020\",\n \"city\": \"Barcelona\",\n \"country_code\": \"ES\"\n },\n \"parties\": {\n \"consignors\": [\n {\n \"name\": \"ACME Logistics SL\",\n \"tax_id\": \"99999972C\",\n \"order\": 1,\n \"signing_role\": \"signer\",\n \"signature_type\": \"biometric\",\n \"channel\": \"email\",\n \"email\": \"{{consignorEmail}}\",\n \"language\": \"es\"\n }\n ],\n \"drivers\": [\n {\n \"name\": \"Juan Pérez\",\n \"tax_id\": \"99999972C\",\n \"order\": 2,\n \"signing_role\": \"signer\",\n \"signature_type\": \"biometric\",\n \"channel\": \"email\",\n \"email\": \"{{driverEmail}}\",\n \"language\": \"es\",\n \"license_plate\": \"1234ABC\"\n }\n ],\n \"consignees\": [\n {\n \"name\": \"Receptor SA\",\n \"tax_id\": \"99999972C\",\n \"order\": 3,\n \"signing_role\": \"signer\",\n \"signature_type\": \"biometric\",\n \"channel\": \"email\",\n \"email\": \"{{consigneeEmail}}\",\n \"language\": \"es\"\n }\n ]\n },\n \"goods\": [\n {\n \"good_description\": \"Palets yogur\",\n \"cargo_type\": \"paletizado\",\n \"good_gross_mass\": 3500.5,\n \"dangerous_goods\": false\n }\n ],\n \"documents\": [\n {\n \"document_type\": \"ecmr\",\n \"document_name\": \"eCMR-standalone.pdf\",\n \"external_id\": \"EXT-ECMR-0001\",\n \"content\": \"{{documentBase64}}\",\n \"signable\": true,\n \"signers\": [\n {\n \"order\": 1,\n \"coordinate\": {\n \"sig_page\": 0,\n \"top_left_corner_x\": 120,\n \"top_left_corner_y\": 650,\n \"width\": 180,\n \"height\": 60\n }\n },\n {\n \"order\": 2,\n \"coordinate\": {\n \"sig_page\": 0,\n \"top_left_corner_x\": 120,\n \"top_left_corner_y\": 560,\n \"width\": 180,\n \"height\": 60\n }\n },\n {\n \"order\": 3,\n \"coordinate\": {\n \"sig_page\": 0,\n \"top_left_corner_x\": 120,\n \"top_left_corner_y\": 470,\n \"width\": 180,\n \"height\": 60\n }\n }\n ]\n }\n ],\n \"language\": \"es\"\n}\n", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/shipments", "host": [ "{{baseUrl}}" ], "path": [ "shipments" ] } }, "response": [] }, { "name": "List shipments", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"200 OK\", () => pm.response.to.have.status(200));", "", "const page = pm.response.json();", "const first = (page.items || [])[0];", "if (first) {", " pm.collectionVariables.set(\"shipmentId\", first.shipment_id);", "}" ] } } ], "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/shipments?page=0&page_size=20", "host": [ "{{baseUrl}}" ], "path": [ "shipments" ], "query": [ { "key": "page", "value": "0" }, { "key": "page_size", "value": "20" }, { "key": "lot_id", "value": "", "disabled": true }, { "key": "shipment_status", "value": "created", "description": " (This can only be one of pending,created,ready_for_pickup,pending_delivery,delivered,completed,error,cancelled)", "disabled": true }, { "key": "shipment_signature_status", "value": "pending", "description": " (This can only be one of pending,validation_pending,ended,canceled,delegated)", "disabled": true }, { "key": "created_from", "value": "", "disabled": true }, { "key": "created_to", "value": "", "disabled": true }, { "key": "consignor_tax_id", "value": "", "disabled": true }, { "key": "consignee_tax_id", "value": "", "disabled": true }, { "key": "carrier_tax_id", "value": "", "disabled": true }, { "key": "driver_tax_id", "value": "", "disabled": true }, { "key": "document_type", "value": "ecmr", "description": " (This can only be one of transport_control_document,ecmr,consignment_note,invoice,contract,delivery_note,order,adr_certificate,pod_doc,other)", "disabled": true } ] } }, "response": [] }, { "name": "Get a shipment details", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"200 OK\", () => pm.response.to.have.status(200));", "", "// Refresh partyId with whoever holds the signing turn right now.", "const pending = (pm.response.json().parties || []).find((party) => party.status === \"pending\");", "if (pending) {", " pm.collectionVariables.set(\"partyId\", pending.party_id);", "}" ] } } ], "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/shipments/:id?include=parties,proof_of_delivery", "host": [ "{{baseUrl}}" ], "path": [ "shipments", ":id" ], "query": [ { "key": "include", "value": "parties,proof_of_delivery", "description": "Related data to include in the response" } ], "variable": [ { "key": "id", "value": "{{shipmentId}}", "description": "(Required) " } ] } }, "response": [] }, { "name": "Add an attachment to a Shipment", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"201 Created\", () => pm.response.to.have.status(201));", "", "pm.collectionVariables.set(\"documentId\", pm.response.json().document_id);" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"document_type\": \"invoice\",\n \"document_name\": \"factura-001.pdf\",\n \"external_id\": \"EXT-INV-0001\",\n \"content\": \"{{documentBase64}}\"\n}\n", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/shipments/:id/attachments", "host": [ "{{baseUrl}}" ], "path": [ "shipments", ":id", "attachments" ], "variable": [ { "key": "id", "value": "{{shipmentId}}", "description": "(Required) " } ] }, "description": "Adds an attachment to an existing shipment synchronously.\n\nThe shipment must exist and have a status other than `pending`, `error` or `cancelled`\n(i.e. it must have already been accepted by Docuten and not yet cancelled).\n\nAttachments added via this endpoint are not the main document of the shipment.\nTemplates are not supported: content must always be provided as Base64. Document\ntypes that can only be a main document (`transport_control_document`, `ecmr`,\n`consignment_note`) are rejected.\n\n**Notifications:** no automatic notification is sent to any party when an\nattachment is added.\n" }, "response": [] }, { "name": "Cancel a Shipment", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"200 OK\", () => pm.response.to.have.status(200));" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"reason\": \"Cancelled by integrator: wrong consignee on the order\"\n}\n", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/shipments/:id/cancel", "host": [ "{{baseUrl}}" ], "path": [ "shipments", ":id", "cancel" ], "variable": [ { "key": "id", "value": "{{shipmentId}}", "description": "(Required) " } ] }, "description": "Cancels an existing shipment, acting as a synchronous gateway to Docuten.\n\nA non-empty `reason` is mandatory: it is propagated to Docuten and recorded in the\nshipment status history.\n\nThe cancellation is propagated to Docuten; if Docuten confirms, the shipment is marked\n`cancelled`, the transition is recorded, and the parties that already took part in the\nflow are notified through their configured channel (email/SMS/WhatsApp).\n\nAllowed states: `created`, `ready_for_pickup`, `pending_delivery` (normal cancellation),\nand `delivered`/`completed` (attempted; Docuten decides and may reject with `409`).\nCancelling an already `cancelled` shipment returns `200` with no side effects (idempotent).\nShipments in `pending` or `error` cannot be cancelled (`409`).\n" }, "response": [] }, { "name": "Download shipment documents", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"200 OK\", () => pm.response.to.have.status(200));" ] } } ], "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/shipments/:id/documents/download?include=all", "host": [ "{{baseUrl}}" ], "path": [ "shipments", ":id", "documents", "download" ], "query": [ { "key": "include", "value": "all", "description": " (This can only be one of main,attachments,all)" }, { "key": "document_type", "value": "ecmr", "description": "Filter documents by type. If not specified, all types are returned.", "disabled": true } ], "variable": [ { "key": "id", "value": "{{shipmentId}}", "description": "(Required) " } ] } }, "response": [] } ], "description": "Everything about Shipments" }, { "name": "party", "item": [ { "name": "Resend a notification to a party", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"204 No Content\", () => pm.response.to.have.status(204));" ] } } ], "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/parties/:id/resend-notification", "host": [ "{{baseUrl}}" ], "path": [ "parties", ":id", "resend-notification" ], "variable": [ { "key": "id", "value": "{{partyId}}", "description": "(Required) UUID of the party whose last notification should be resent." } ] }, "description": "Resends a notification to the identified party for the shipment they belong to.\n\nUseful to nudge a specific recipient — signer, approver, or party in copy —\nindependently of the shipment-level workflow.\n\nNo request body is required. The notification is dispatched through the channel\n**currently configured** for the party (email/SMS/WhatsApp) and matches the\n**type** of the last notification recorded for them (signature request →\nsignature request, end-of-flow → end-of-flow, etc.).\n\n**Resend scoped to the targeted shipment.** The endpoint always acts on the\nshipment that the given `party_id` belongs to and the message covers only that\nshipment. If the party had previously been notified as part of a lot-level grouped\nmessage covering several shipments, the resend is **not** a replay of that grouped\nmessage — it is delivered as an individual notification for this shipment. To\nnudge the party about another shipment in the lot, call the endpoint with the\n`party_id` that belongs to that shipment.\n\nEach party is capped at a maximum of **5 resends** over the lifetime of the\nshipment. Once that limit is reached the API responds with\n`429 RESEND_LIMIT_REACHED`.\n\nThe endpoint rejects the resend only when the action it would convey is no longer\napplicable to the party (already-signed signers/approvers). Resending end-of-flow\nnotifications or notifications to parties in copy is allowed even after the\nshipment has completed.\n" }, "response": [] }, { "name": "Reassign the active party (signer/approver) of a shipment", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"202 Accepted\", () => pm.response.to.have.status(202));" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Nueva Persona Reasignada\",\n \"email\": \"{{reassignEmail}}\",\n \"notification_channel\": \"email\"\n}\n", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/parties/:id/reassign", "host": [ "{{baseUrl}}" ], "path": [ "parties", ":id", "reassign" ], "variable": [ { "key": "id", "value": "{{partyId}}", "description": "(Required) UUID of the party to reassign (must be the current holder of the signing flow)." } ] }, "description": "Reassigns the party that currently holds the pending turn in a shipment's\nsigning flow to a new recipient, delegating the signature in Docuten instead of\ncancelling and recreating the shipment. Preserves the `shipment_id`, any\nsignatures already completed, and the full audit trail.\n\n**Only the party that currently holds the turn is reassignable.** The Docuten\ndelegation always targets the current holder of the flow, so eCMR validates\nlocally that the party identified by `id` is that holder before delegating. A\nfuture party (turn not yet reached) or one that has already acted is rejected\nwith `409 PARTY_NOT_CURRENT_SIGNER`.\n\n**Parties in copy (`cc`) are never reassignable**: a `cc` never holds the flow —\nit only receives an informational copy — so delegation does not apply to it.\n\nThe reassignment is **asynchronous**: on success the endpoint returns\n`202 Accepted`; the new party (with its own `party_id` and `signing_url`) is\npersisted later via the Docuten `DELEGATION` callback and can be retrieved\nthrough the shipment endpoint. The new recipient is notified immediately by the\nexisting delegation flow.\n" }, "response": [] } ], "description": "Everything about Parties" } ], "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-KEY", "type": "string" }, { "key": "value", "value": "{{apiKey}}", "type": "string" }, { "key": "in", "value": "header", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "http://localhost:8080/api/v1", "description": "Base URL of the environment, context path included." }, { "key": "apiKey", "value": "", "description": "Docuten API key sent as X-API-KEY. Set it in the environment, never here." }, { "key": "documentBase64", "value": "", "description": "Base64 of the PDF to send (no data: prefix). Required by the create and attachment requests." }, { "key": "consignorEmail", "value": "consignor@example.com", "description": "Consignor signer address. Point it at a mailbox you own: the API sends real notifications." }, { "key": "driverEmail", "value": "driver@example.com", "description": "Driver signer address." }, { "key": "consigneeEmail", "value": "consignee@example.com", "description": "Consignee signer address." }, { "key": "reassignEmail", "value": "reassigned@example.com", "description": "Address of the party taking over in \"Reassign the active party\"." }, { "key": "callbackUrl", "value": "", "description": "Optional URL notified when every shipment in the lot has been processed. Leave empty to skip it." }, { "key": "lotId", "value": "", "description": "Captured by \"Create a Lot\"." }, { "key": "shipmentId", "value": "", "description": "Captured by \"Create a Shipment\", \"Create a Lot\" and \"List shipments\"." }, { "key": "partyId", "value": "", "description": "Party holding the signing turn. Captured by the create and detail requests." }, { "key": "documentId", "value": "", "description": "Captured by \"Add an attachment to a Shipment\"." } ] }