{ "openapi": "3.1.1", "info": { "title": "API DeCA", "version": "1.0.0", "description": "API per emetre, rectificar, consultar i descarregar documents espanyols de control administratiu del transport de mercaderies. Per obtenir un token, contacta amb el suport de SERTEC PESAGE. Els tokens sk_test_ utilitzen desenvolupament i els sk_live_ producció, amb dades separades. La restricció per IP és opcional.\n\nCada credencial permet consultar i descarregar els seus documents durant les 24 hores següents a la creació. La descàrrega per QR té una vigència independent. Les rectificacions conserven el document original.\n\nL'esborrament lògic només es permet durant les primeres 2 hores per corregir errors de generació. La integració ha de confirmar que el document no s'ha lliurat al transportista ni utilitzat en el transport. Es conserven l'arxiu i la traçabilitat, però se'n bloqueja l'accés.\n\nPots sol·licitar un token `sk_demo_` sense compte ni alta d’una organització. Dura **24 hores des de l’emissió** i només funciona des de la **IP pública que l’ha sol·licitat**. Si canvies de xarxa o d’IP, cal sol·licitar un altre token. Utilitza només **dades fictícies**. Cada pàgina del PDF mostra **SENSE VALIDESA** al costat del logo i una marca diagonal **DEMO**. Estos documents no servixen per a transportar mercaderies ni com a documents administratius vàlids. La demo afig demo: true, expires_at, qr_url (àlies de url) i pdf_url (àlies de pdf_download_url). document_locale és l’idioma triat en sol·licitar el token (es per defecte). Les dades i PDF temporals estan separats de l’arxiu real i no es xifren com els documents reals. La demo admet cossos de fins a 32 KiB i deu documents per sessió. L’emissió de tokens admet tres per minut i deu per hora des d’una mateixa IP; la creació, cinc per minut i vint per hora des d’una mateixa IP. Els límits compartits per xarxa, regió i càrrega global es poden aplicar abans. Estes xifres corresponen a la configuració predeterminada." }, "servers": [ { "url": "https://deca.sertecpesage.com", "description": "Producció" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Documents", "description": "Emissió, rectificació i accés als documents propis recents." }, { "name": "Descàrrega per QR", "description": "Descàrrega directa del PDF mitjançant el secret d'un document." }, { "name": "Demostració de l’API", "description": "Obtin un token públic temporal i genera documents de demostració amb dades fictícies." } ], "paths": { "/api/v1/documents": { "post": { "operationId": "createDocument", "tags": [ "Documents" ], "summary": "Crear document", "description": "Envia totes les dades del transport. La resposta es lliura després de generar i emmagatzemar el PDF xifrat.\n\nUna referència no nul·la és única per organització i entorn. Repetir la referència amb les mateixes dades normalitzades i metadata retorna el resultat original dins de 24 hores (200), sense emetre un altre PDF. Una creació nova retorna 201. Dades diferents o una referència d'una altra credencial produeixen 409 sense divulgar documents. Sense referència no es garanteix la deduplicació.\n\nUna referència amb el resultat vençut retorna 409 DOCUMENT_WINDOW_EXPIRED. Si el document està eliminat, no se'n retorna el contingut ni es reutilitza la referència; el reintent retorna 404. Per rectificar, utilitza els endpoints PUT.\n\nPots sol·licitar un token `sk_demo_` sense compte ni alta d’una organització. Dura **24 hores des de l’emissió** i només funciona des de la **IP pública que l’ha sol·licitat**. Si canvies de xarxa o d’IP, cal sol·licitar un altre token. La demo afig demo: true, expires_at, qr_url (àlies de url) i pdf_url (àlies de pdf_download_url). document_locale és l’idioma triat en sol·licitar el token (es per defecte). Les dades i PDF temporals estan separats de l’arxiu real i no es xifren com els documents reals.", "requestBody": { "required": true, "description": "Dades completes del document que es vol crear.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentRequest" }, "examples": { "create": { "summary": "Emissió amb pes i remolc", "value": { "reference": "EXP-2026-004587", "transport_date": "2026-10-05", "shipper": { "name": "Distribuciones Demo, S. L.", "tax_country": "ES", "tax_id": "B12345674", "address": { "street": "Carrer de la Logística, 18", "postal_code": "08040", "city": "Barcelona", "country": "ES" } }, "carrier": { "name": "Transportes Demo, S. L.", "tax_country": "ES", "tax_id": "B87654323" }, "origin": { "place": "Almacén Barcelona", "city": "Barcelona", "country": "ES" }, "destination": { "place": "Almacén Zaragoza", "city": "Zaragoza", "country": "ES" }, "goods": { "description": "Vino embotellado", "weight_kg": "1850.000" }, "vehicle": { "country": "ES", "registration": "4827 MNL", "trailer_country": "ES", "trailer_registration": "R 5832 BCD" }, "special_authorization": null, "observations": null, "metadata": { "order_id": "4587", "terminal": "POS-02" } } }, "alternativeMeasure": { "summary": "Magnitud alternativa quan és difícil determinar el pes", "value": { "transport_date": "2026-10-05", "shipper": { "name": "Distribuciones Demo, S. L.", "tax_country": "ES", "tax_id": "B12345674", "address": { "street": "Carrer de la Logística, 18", "postal_code": "08040", "city": "Barcelona", "country": "ES" } }, "carrier": { "name": "Transportes Demo, S. L.", "tax_country": "ES", "tax_id": "B87654323" }, "origin": { "place": "Almacén Barcelona", "city": "Barcelona", "country": "ES" }, "destination": { "place": "Almacén Zaragoza", "city": "Zaragoza", "country": "ES" }, "goods": { "description": "Carga cuyo peso es de difícil determinación.", "alternative_measure": { "value": "12", "unit": "palés" } }, "vehicle": { "country": "ES", "registration": "4827 MNL" } } } } } } }, "responses": { "200": { "description": "Reintent idempotent; retorna el resultat original sense generar un altre PDF.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DocumentResult" }, { "$ref": "#/components/schemas/DemoDocumentResult" } ] }, "examples": { "original": { "$ref": "#/components/examples/DocumentResult" } } } } }, "201": { "description": "Document nou generat i emmagatzemat.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DocumentResult" }, { "$ref": "#/components/schemas/DemoDocumentResult" } ] }, "examples": { "created": { "$ref": "#/components/examples/DocumentResult" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Referència en conflicte o resultat del reintent vençut.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "referenceConflict": { "value": { "errors": [ { "field": "reference", "code": "REFERENCE_CONFLICT", "message": "Reference conflicts with an existing request." } ] } }, "expiredReplay": { "value": { "errors": [ { "field": "reference", "code": "DOCUMENT_WINDOW_EXPIRED", "message": "Original result is no longer available through the API." } ] } } } } } }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-deca-order": 10 }, "get": { "operationId": "listDocuments", "tags": [ "Documents" ], "summary": "Llistar documents recents", "description": "Retorna resums, sense PDF, secret QR ni metadata. El servidor aplica sempre la finestra de 24 hores i l'aïllament de la credencial. Ordre descendent per data de creació i UUID com a desempat, paginació per pàgina i filtres inclusius de data de transport. La finestra s'avalua a cada petició; no constitueix una instantània estable entre pàgines. No permet consultar l'històric.\n\nEls documents eliminats no apareixen a la llista.", "parameters": [ { "name": "page", "in": "query", "description": "Pàgina sol·licitada, a partir d'1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Documents per pàgina, entre 1 i 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "from", "in": "query", "description": "Data de transport mínima, inclosa. No amplia la finestra de lectura.", "schema": { "type": "string", "format": "date" }, "examples": { "default": { "value": "2026-10-05" } } }, { "name": "to", "in": "query", "description": "Data de transport màxima, inclosa; igual o posterior a from.", "schema": { "type": "string", "format": "date" }, "examples": { "default": { "value": "2026-10-05" } } } ], "responses": { "200": { "description": "Pàgina de documents recents. Una pàgina sense resultats té data buit.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentList" }, "examples": { "default": { "value": { "data": [ { "uuid": "75b10a04-1a2d-4f9e-9277-5f3c270f476e", "reference": "EXP-2026-004587", "created_at": "2026-10-05T14:43:00Z", "transport_date": "2026-10-05", "rectifies_uuid": null } ], "meta": { "current_page": 1, "limit": 25, "total": 1, "last_page": 1 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-deca-order": 50 } }, "/api/v1/documents/{uuid}": { "parameters": [ { "$ref": "#/components/parameters/DocumentUuidWithReferenceAlternative" } ], "put": { "operationId": "rectifyDocument", "tags": [ "Documents" ], "summary": "Rectificar document", "x-deca-order": 20, "description": "Identifica el document anterior amb el UUID i envia totes les dades corregides, sense actualitzacions parcials. Només es pot rectificar l'última versió de la mateixa credencial. Es permet rectificar un document de més de 24 hores sense retornar-ne el contingut anterior. Un document eliminat retorna 404 i no es pot rectificar.\n\nEs genera un document rectificatiu amb UUID, PDF i QR nous; es conserven l'original i el seu QR. Lliura el nou PDF al conductor. El camp reference del cos correspon a la nova versió, no al document de la URL.\n\nRepetir el mateix PUT amb les mateixes dades normalitzades i metadata retorna la rectificació ja emesa durant les 24 hores següents a la seua creació, sense generar una altra versió. Esta comprovació es fa abans de rebutjar un document ja rectificat i també funciona si el reintent identifica el mateix document per referència. Canviar dades d'un document ja rectificat retorna 409. Un resultat de reintent vençut retorna 409 DOCUMENT_WINDOW_EXPIRED. Si la rectificació retornada està eliminada, el reintent retorna 404. Per a una altra rectificació, utilitza el UUID o la referència de l'última versió.", "requestBody": { "required": true, "description": "Dades completes corregides del transport.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RectifyDocumentRequest" }, "examples": { "rectify": { "summary": "Rectificació completa amb una referència nova", "value": { "reference": "EXP-2026-004587-R1", "transport_date": "2026-10-05", "shipper": { "name": "Distribuciones Demo, S. L.", "tax_country": "ES", "tax_id": "B12345674", "address": { "street": "Carrer de la Logística, 18", "postal_code": "08040", "city": "Barcelona", "country": "ES" } }, "carrier": { "name": "Transportes Demo, S. L.", "tax_country": "ES", "tax_id": "B87654323" }, "origin": { "place": "Almacén Barcelona", "city": "Barcelona", "country": "ES" }, "destination": { "place": "Almacén Zaragoza", "city": "Zaragoza", "country": "ES" }, "goods": { "description": "Vino embotellado", "weight_kg": "1900.000" }, "vehicle": { "country": "ES", "registration": "4827 MNL", "trailer_country": "ES", "trailer_registration": "R 5832 BCD" }, "special_authorization": null, "observations": "Corrección del peso de la mercancía.", "metadata": { "order_id": "4587", "terminal": "POS-02" } } } } } } }, "responses": { "200": { "description": "Document rectificatiu emès, o resultat d'un reintent idèntic sense crear una altra versió.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DocumentResult" }, { "$ref": "#/components/schemas/DemoDocumentResult" } ] }, "examples": { "rectified": { "$ref": "#/components/examples/RectifiedDocumentResult" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Document ja rectificat, referència nova en conflicte o resultat del reintent vençut.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "alreadyRectified": { "value": { "errors": [ { "field": null, "code": "DOCUMENT_ALREADY_RECTIFIED", "message": "Document has already been rectified." } ] } }, "referenceConflict": { "value": { "errors": [ { "field": "reference", "code": "REFERENCE_CONFLICT", "message": "Reference conflicts with an existing request." } ] } }, "expiredReplay": { "value": { "errors": [ { "field": null, "code": "DOCUMENT_WINDOW_EXPIRED", "message": "Original result is no longer available through the API." } ] } } } } } }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-deca-alternative-path": "/api/v1/documents/ref/{reference}" }, "delete": { "operationId": "deleteDocument", "tags": [ "Documents" ], "summary": "Eliminar document", "x-deca-order": 40, "description": "Esborrament lògic per corregir errors detectats en generar un document, exclusivament **abans de lliurar-lo al transportista o al conductor i abans d'utilitzar-lo en un transport**. La integració ha de confirmar totes dues condicions; no n'hi ha prou amb estar dins del termini. Si el document ja s'ha lliurat o utilitzat, cal rectificar-lo mitjançant PUT.\n\nNomés es permet mentre l'hora del servidor siga anterior a created_at + **2 hores**; a les 2 hores exactes ja no es permet. Ni una consulta ni un reintent reinicien el termini. Cada versió utilitza la seua pròpia data de creació. Només es pot eliminar l'última versió de la credencial autenticada.\n\nEs conserven el PDF, les dades i la traçabilitat, però el document deixa d'aparèixer a la llista. Les consultes per UUID o referència, la descàrrega autenticada, el QR i els reintents que retornarien el contingut responen 404. La consulta d'estat respon només amb status: deleted durant la finestra de consulta de 24 hores. La referència continua reservada. No hi ha endpoint de reactivació; l'esborrament conserva l'arxiu per permetre una recuperació futura.\n\nRepetir DELETE dins de les mateixes 2 hores retorna 204 sense canviar la data d'eliminació. Passat el termini retorna 409.\n\nEl primer accés correcte a l'enllaç QR també bloqueja l'esborrament amb 409 DOCUMENT_ALREADY_ACCESSED. Este accés no prova per si sol que s'haja fet el transport.", "requestBody": { "required": true, "description": "Motiu i confirmació que el document encara no s'ha lliurat ni utilitzat.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDocumentRequest" }, "examples": { "generationError": { "value": { "reason": "Peso incorrecto detectado antes de enviar el documento al transportista.", "confirm_not_delivered": true, "confirm_not_used": true } } } } } }, "responses": { "204": { "description": "Document marcat com a eliminat. Sense cos de resposta.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Termini de 2 hores vençut, document lliurat o utilitzat, o versió ja rectificada. El primer accés correcte a l'enllaç QR també bloqueja l'esborrament amb 409 DOCUMENT_ALREADY_ACCESSED. Este accés no prova per si sol que s'haja fet el transport.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "expired": { "value": { "errors": [ { "field": null, "code": "DELETE_WINDOW_EXPIRED", "message": "The two-hour deletion window has expired." } ] } }, "delivered": { "value": { "errors": [ { "field": null, "code": "DOCUMENT_ALREADY_DELIVERED", "message": "A delivered document cannot be deleted." } ] } }, "used": { "value": { "errors": [ { "field": null, "code": "DOCUMENT_ALREADY_USED", "message": "A document used in transport cannot be deleted." } ] } }, "rectified": { "value": { "errors": [ { "field": null, "code": "DOCUMENT_ALREADY_RECTIFIED", "message": "Document has already been rectified." } ] } }, "accessed": { "value": { "errors": [ { "field": null, "code": "DOCUMENT_ALREADY_ACCESSED", "message": "A document accessed through its QR link cannot be deleted." } ] } } } } } }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-deca-alternative-path": "/api/v1/documents/ref/{reference}" }, "get": { "operationId": "getDocument", "tags": [ "Documents" ], "summary": "Consultar document", "description": "Recupera el resultat original dins de 24 hores, només per a la credencial que va emetre el document. Inclou tots els camps acceptats i normalitzats i la metadata sense modificació semàntica.\n\nUn UUID o una referència inexistent, d'una altra credencial o fora de la finestra retorna el mateix `404`, sense confirmar-ne l'existència ni el propietari. Cada referència identifica la seua pròpia versió i no redirigeix a una rectificació posterior.\n\nUn document eliminat retorna 404. Per saber si està eliminat, utilitza la consulta d'estat.", "responses": { "200": { "description": "Resultat original del document.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DocumentResult" }, { "$ref": "#/components/schemas/DemoDocumentResult" } ] }, "examples": { "document": { "$ref": "#/components/examples/DocumentResult" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-deca-order": 60, "x-deca-alternative-path": "/api/v1/documents/ref/{reference}" } }, "/api/v1/documents/{uuid}/status": { "parameters": [ { "$ref": "#/components/parameters/DocumentStatusUuidWithReferenceAlternative" } ], "get": { "operationId": "getDocumentStatus", "tags": [ "Documents" ], "summary": "Consultar estat", "x-deca-order": 80, "description": "Retorna únicament l'estat d'un document de la credencial autenticada, durant les 24 hores següents a la creació. Un document eliminat respon 200 amb {\"status\":\"deleted\"}; no retorna dades del transport, PDF, enllaç QR ni metadata. Un document actiu respon amb {\"status\":\"active\"}.\n\nUn UUID inexistent, d'una altra credencial o fora de les 24 hores retorna el mateix 404. L'eliminació no amplia esta finestra.", "responses": { "200": { "description": "Estat del document sense dades del contingut.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentStatus" }, "examples": { "deleted": { "summary": "Document eliminat", "value": { "status": "deleted" } }, "active": { "summary": "Document actiu", "value": { "status": "active" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-deca-alternative-path": "/api/v1/documents/ref/{reference}/status" } }, "/api/v1/documents/{uuid}/pdf": { "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID públic del document. Alternativament, utilitza `GET /api/v1/documents/ref/{reference}/pdf`. Exemple: `/api/v1/documents/ref/EXP-2026-004587/pdf`.", "schema": { "type": "string", "format": "uuid" }, "examples": { "default": { "value": "75b10a04-1a2d-4f9e-9277-5f3c270f476e" } } } ], "get": { "operationId": "downloadDocumentPdf", "tags": [ "Documents" ], "summary": "Descarregar PDF", "description": "Retorna exactament els bytes del PDF emmagatzemat, sense regenerar-lo. Exigeix la credencial propietària i una antiguitat inferior a 24 hores. Esta limitació no altera la conservació legal ni la vigència del QR.\n\nUn document eliminat retorna 404 sense lliurar el PDF.", "responses": { "200": { "$ref": "#/components/responses/PdfDownload" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-deca-order": 90, "x-deca-alternative-path": "/api/v1/documents/ref/{reference}/pdf" } }, "/d/{uuid}": { "parameters": [ { "$ref": "#/components/parameters/DocumentUuid" } ], "get": { "operationId": "downloadDocumentByQr", "tags": [ "Descàrrega per QR" ], "summary": "Descarregar PDF per QR", "description": "Enllaç inclòs al QR. El secret k autoritza únicament este document. No requereix Bearer, sessió, CAPTCHA ni pàgina intermèdia. Qui coneix l'enllaç el pot descarregar. No registris la URL completa en logs, analítica ni traces.\n\nLa descàrrega no venç a les 24 hores ni es revoca automàticament en rotar o revocar el Bearer. El QR anterior conserva el seu PDF després d'una rectificació; no redirigeix a la nova versió.\n\nEl PDF es lliura amb `Content-Disposition: inline` per obrir-lo al visor del navegador.\n\nUn document eliminat retorna 404, encara que el secret siga correcte.", "security": [ { "qrSecret": [] } ], "responses": { "200": { "$ref": "#/components/responses/PdfPreview" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-deca-order": 100 } }, "/api/v1/demo/tokens": { "post": { "operationId": "createDemoToken", "tags": [ "Demostració de l’API" ], "summary": "Sol·licitar un token demo", "description": "Envia un objecte JSON buit a este endpoint públic. No necessita cap capçalera Bearer. La resposta `201` conté `token` i `expires_at`; la data de caducitat s’expressa en UTC.\n\nPots sol·licitar un token `sk_demo_` sense compte ni alta d’una organització. Dura **24 hores des de l’emissió** i només funciona des de la **IP pública que l’ha sol·licitat**. Si canvies de xarxa o d’IP, cal sol·licitar un altre token.\n\nUtilitza només **dades fictícies**. Cada pàgina del PDF mostra **SENSE VALIDESA** al costat del logo i una marca diagonal **DEMO**. Estos documents no servixen per a transportar mercaderies ni com a documents administratius vàlids.\n\nLa demo admet cossos de fins a 32 KiB i deu documents per sessió. L’emissió de tokens admet tres per minut i deu per hora des d’una mateixa IP; la creació, cinc per minut i vint per hora des d’una mateixa IP. Els límits compartits per xarxa, regió i càrrega global es poden aplicar abans. Estes xifres corresponen a la configuració predeterminada. Pots enviar document_locale per triar l’idioma de tots els PDF del token: es, ca, gl, ca-valencia, eu, en, pt-pt o fr. Si s’omet, s’utilitza es. La resposta també inclou document_locale; canviar-lo requerix un token nou.", "security": [], "requestBody": { "required": true, "description": "Envia un objecte JSON buit a este endpoint públic. No necessita cap capçalera Bearer. La resposta `201` conté `token` i `expires_at`; la data de caducitat s’expressa en UTC. Pots enviar document_locale per triar l’idioma de tots els PDF del token: es, ca, gl, ca-valencia, eu, en, pt-pt o fr. Si s’omet, s’utilitza es. La resposta també inclou document_locale; canviar-lo requerix un token nou.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "document_locale": { "type": "string", "enum": [ "es", "ca", "gl", "ca-valencia", "eu", "en", "pt-pt", "fr" ], "default": "es", "description": "Idioma dels PDF d’este token. Castellà per defecte." } } }, "examples": { "default": { "value": {} } } } } }, "responses": { "201": { "description": "Token demo emés; vàlid durant 24 hores i vinculat a la IP sol·licitant.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoTokenResult" }, "examples": { "default": { "value": { "token": "sk_demo_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "expires_at": "2026-10-07T11:00:00Z", "document_locale": "es" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/DemoRateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/DemoUnavailable" } }, "x-deca-order": 5 } }, "/demo/d/{uuid}": { "parameters": [ { "$ref": "#/components/parameters/DocumentUuid" } ], "get": { "operationId": "downloadDemoDocumentByQr", "tags": [ "Demostració de l’API" ], "summary": "Obrir el PDF demo per QR", "description": "El QR obri el PDF directament en el navegador mitjançant `/demo/d/{uuid}?k=...`, sense Bearer. Tant el document com els enllaços caduquen amb la sessió demo; crear o rectificar un document no allarga la durada del token.\n\nUtilitza només **dades fictícies**. Cada pàgina del PDF mostra **SENSE VALIDESA** al costat del logo i una marca diagonal **DEMO**. Estos documents no servixen per a transportar mercaderies ni com a documents administratius vàlids.", "security": [ { "qrSecret": [] } ], "responses": { "200": { "$ref": "#/components/responses/PdfPreview" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/DemoRateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/DemoUnavailable" } }, "x-deca-order": 110 } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Token d'integració facilitat pel suport de SERTEC PESAGE. Envia'l a Authorization: Bearer, exclusivament mitjançant HTTPS. sk_test_ selecciona desenvolupament i sk_live_ producció. Si el token té una llista d'IP autoritzades, la petició ha de procedir d'una d'estes; una llista buida permet qualsevol IP. No enviïs el token a la URL ni l'exposis en aplicacions client.\n\nPots sol·licitar un token `sk_demo_` sense compte ni alta d’una organització. Dura **24 hores des de l’emissió** i només funciona des de la **IP pública que l’ha sol·licitat**. Si canvies de xarxa o d’IP, cal sol·licitar un altre token. Utilitza només **dades fictícies**. Cada pàgina del PDF mostra **SENSE VALIDESA** al costat del logo i una marca diagonal **DEMO**. Estos documents no servixen per a transportar mercaderies ni com a documents administratius vàlids." }, "qrSecret": { "type": "apiKey", "in": "query", "name": "k", "description": "Secret opac de l'enllaç QR; copia exactament el valor retornat a url." } }, "parameters": { "DocumentUuid": { "name": "uuid", "in": "path", "required": true, "description": "UUID públic del document; conèixer-lo no concedeix accés.", "schema": { "type": "string", "format": "uuid" }, "examples": { "default": { "value": "75b10a04-1a2d-4f9e-9277-5f3c270f476e" } } }, "DocumentUuidWithReferenceAlternative": { "name": "uuid", "in": "path", "required": true, "description": "UUID públic del document. Alternativament, utilitza `/api/v1/documents/ref/{reference}` amb el mateix mètode. Exemple: `/api/v1/documents/ref/EXP-2026-004587`.", "schema": { "type": "string", "format": "uuid" }, "examples": { "default": { "value": "75b10a04-1a2d-4f9e-9277-5f3c270f476e" } } }, "DocumentStatusUuidWithReferenceAlternative": { "name": "uuid", "in": "path", "required": true, "description": "UUID públic del document. Alternativament, utilitza `GET /api/v1/documents/ref/{reference}/status`. Exemple: `/api/v1/documents/ref/EXP-2026-004587/status`.", "schema": { "type": "string", "format": "uuid" }, "examples": { "default": { "value": "75b10a04-1a2d-4f9e-9277-5f3c270f476e" } } } }, "headers": { "NoStore": { "description": "La resposta conté informació sensible i no s'ha d'emmagatzemar en memòria cau.", "schema": { "type": "string", "examples": [ "no-store, private" ] } } }, "schemas": { "CountryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Codi del país de dues lletres; es normalitza a majúscules. El format no comprova la pertinença al catàleg ISO 3166-1.", "examples": [ "ES" ] }, "PositiveDecimal": { "type": "string", "pattern": "^(?!0+(?:\\.0+)?$)(?:0|[1-9][0-9]{0,14})(?:\\.[0-9]{1,6})?$", "description": "Decimal positiu com a string, amb punt, sense coma ni notació científica. Fins a 15 xifres enteres i 6 decimals. La resposta elimina els zeros decimals finals.", "examples": [ "1850.000" ] }, "WeightKilograms": { "oneOf": [ { "$ref": "#/components/schemas/PositiveDecimal" }, { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1000000000000000, "multipleOf": 0.000001 } ], "description": "Pes positiu en kg, com a número JSON o text decimal. Fins a 15 xifres enteres i 6 decimals. La resposta normalitza a text i conserva la precisió; el PDF mostra fins a 3 decimals, amb coma decimal i punts de milers. Utilitza text decimal per a evitar pèrdua de precisió en valors grans.", "examples": [ 1850.5 ] }, "Address": { "type": "object", "additionalProperties": false, "required": [ "street", "postal_code", "city", "country" ], "properties": { "street": { "type": "string", "minLength": 1, "description": "Via i número del domicili.", "maxLength": 255 }, "postal_code": { "type": "string", "minLength": 1, "description": "Codi postal com a text per conservar els zeros inicials.", "maxLength": 255 }, "city": { "type": "string", "minLength": 1, "description": "Localitat del domicili.", "maxLength": 255 }, "country": { "$ref": "#/components/schemas/CountryCode" } } }, "Shipper": { "type": "object", "additionalProperties": false, "required": [ "name", "tax_country", "tax_id", "address" ], "description": "Carregador contractual; pot ser diferent del magatzem d'origen i del client de DeCA.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Nom o raó social.", "maxLength": 255 }, "tax_country": { "$ref": "#/components/schemas/CountryCode" }, "tax_id": { "type": "string", "minLength": 1, "description": "Identificador fiscal normalitzat a majúscules i sense espais ni guions; la longitud es comprova després de normalitzar. A Espanya es validen el format i el caràcter de control de DNI, NIE i NIF d'entitats (CIF). Els NIF especials K, L i M es comproven només pel format: prefix, set caràcters alfanumèrics i lletra final. Per a altres països s'exigeix format alfanumèric sense verificar-ne el control fiscal. Esta validació no acredita existència ni alta censal.", "maxLength": 32 }, "address": { "$ref": "#/components/schemas/Address" } } }, "Carrier": { "type": "object", "additionalProperties": false, "required": [ "name", "tax_country", "tax_id" ], "description": "Transportista que fa efectivament el transport, inclòs el subcontractat.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Nom o raó social.", "maxLength": 255 }, "tax_country": { "$ref": "#/components/schemas/CountryCode" }, "tax_id": { "type": "string", "minLength": 1, "description": "Identificador fiscal normalitzat a majúscules i sense espais ni guions; la longitud es comprova després de normalitzar. A Espanya es validen el format i el caràcter de control de DNI, NIE i NIF d'entitats (CIF). Els NIF especials K, L i M es comproven només pel format: prefix, set caràcters alfanumèrics i lletra final. Per a altres països s'exigeix format alfanumèric sense verificar-ne el control fiscal. Esta validació no acredita existència ni alta censal.", "maxLength": 32 }, "address": { "description": "Domicili opcional del transportista. Si s'envia, cal incloure tots els camps d'Address; l'article 6 no l'exigeix com a dada mínima.", "type": "object", "additionalProperties": false, "required": [ "street", "postal_code", "city", "country" ], "properties": { "street": { "type": "string", "minLength": 1, "description": "Via i número del domicili.", "maxLength": 255 }, "postal_code": { "type": "string", "minLength": 1, "description": "Codi postal com a text per conservar els zeros inicials.", "maxLength": 255 }, "city": { "type": "string", "minLength": 1, "description": "Localitat del domicili.", "maxLength": 255 }, "country": { "$ref": "#/components/schemas/CountryCode" } } } } }, "TransportLocation": { "type": "object", "additionalProperties": false, "required": [ "place", "city", "country" ], "properties": { "place": { "type": "string", "minLength": 1, "description": "Lloc real de càrrega o descàrrega, identificable pel nom de la instal·lació o l'adreça. Amb city i country ha de permetre identificar-lo clarament; street i postal_code són opcionals. La identificació de l'empresa destinatària no és una dada mínima obligatòria.", "maxLength": 255 }, "city": { "type": "string", "minLength": 1, "description": "Localitat.", "maxLength": 255 }, "country": { "type": "string", "enum": [ "ES" ], "description": "L'abast inicial cobreix transports interiors a Espanya; no substitueix el CMR internacional." }, "street": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Via i número opcionals del lloc de càrrega o descàrrega per precisar-ne la ubicació." }, "postal_code": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Codi postal opcional del lloc de càrrega o descàrrega, com a text per conservar zeros inicials." } } }, "AlternativeMeasure": { "type": "object", "additionalProperties": false, "required": [ "value", "unit" ], "description": "Una altra magnitud quan siga difícil determinar el pes. Envia esta magnitud o el pes, mai tots dos.", "properties": { "value": { "$ref": "#/components/schemas/PositiveDecimal" }, "unit": { "type": "string", "minLength": 1, "description": "Unitat explícita de la magnitud, fins a 255 caràcters.", "maxLength": 255, "examples": [ "palés" ] } } }, "Goods": { "type": "object", "additionalProperties": false, "required": [ "description" ], "description": "Naturalesa i pes de la mercaderia, o magnitud alternativa quan pertoqui. Envia exactament una mesura.", "properties": { "description": { "type": "string", "minLength": 1, "description": "Descripció de la naturalesa de la mercaderia.", "maxLength": 2000 }, "weight_kg": { "$ref": "#/components/schemas/WeightKilograms" }, "alternative_measure": { "$ref": "#/components/schemas/AlternativeMeasure" } }, "oneOf": [ { "required": [ "weight_kg" ] }, { "required": [ "alternative_measure" ] } ] }, "Vehicle": { "type": "object", "additionalProperties": false, "required": [ "country", "registration" ], "description": "Vehicle efectiu; si hi ha remolc o semiremolc, informa els seus dos camps junts.", "properties": { "country": { "$ref": "#/components/schemas/CountryCode" }, "registration": { "type": "string", "minLength": 1, "description": "Matrícula normalitzada a majúscules i sense espais ni guions. A Espanya s'admet la matrícula ordinària vigent, les provincials anteriors i la sèrie especial E. Per a altres països, entre 3 i 20 caràcters alfanumèrics.", "maxLength": 20, "examples": [ "4827 MNL" ] }, "trailer_country": { "$ref": "#/components/schemas/CountryCode" }, "trailer_registration": { "type": "string", "minLength": 1, "description": "Matrícula del remolc o semiremolc, normalitzada com la del tractor. A Espanya s'exigeix la sèrie R. Per a altres països, entre 3 i 20 caràcters alfanumèrics.", "maxLength": 20, "examples": [ "R 5832 BCD" ] } }, "oneOf": [ { "required": [ "trailer_country", "trailer_registration" ] }, { "not": { "anyOf": [ { "properties": { "trailer_country": {} }, "required": [ "trailer_country" ] }, { "properties": { "trailer_registration": {} }, "required": [ "trailer_registration" ] } ] } } ] }, "SpecialAuthorization": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "number" ], "description": "Autorització especial de circulació quan calgui. Omet-la o envia null si no correspon.", "properties": { "number": { "type": "string", "minLength": 1, "description": "Número o referència de l'autorització.", "maxLength": 255 }, "issuer": { "type": "string", "minLength": 1, "description": "Organisme emissor, si s'informa.", "maxLength": 255 } } }, "CreateDocumentRequest": { "type": "object", "additionalProperties": false, "required": [ "transport_date", "shipper", "carrier", "origin", "destination", "goods", "vehicle" ], "properties": { "reference": { "type": [ "string", "null" ], "minLength": 1, "description": "Referència pròpia opcional, única per organització i entorn i impresa al PDF. Identifica els reintents i permet consultar per referència. No s'allibera en eliminar el document.", "pattern": "^[A-Za-z0-9-]+(?![\\s\\S])", "maxLength": 120 }, "transport_date": { "type": "string", "format": "date", "description": "Data real del transport en format YYYY-MM-DD; no és l'instant de creació del PDF." }, "shipper": { "$ref": "#/components/schemas/Shipper" }, "carrier": { "$ref": "#/components/schemas/Carrier" }, "origin": { "$ref": "#/components/schemas/TransportLocation" }, "destination": { "$ref": "#/components/schemas/TransportLocation" }, "goods": { "$ref": "#/components/schemas/Goods" }, "vehicle": { "$ref": "#/components/schemas/Vehicle" }, "special_authorization": { "$ref": "#/components/schemas/SpecialAuthorization" }, "observations": { "type": [ "string", "null" ], "description": "Observacions que els intervinents sol·licitin fer constar al document.", "maxLength": 4000 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Objecte JSON opcional, conservat i retornat sense modificació semàntica. No s'imprimeix al PDF. Màxim 16 KiB en serialitzar-lo i 8 nivells de profunditat." } } }, "DocumentResult": { "type": "object", "additionalProperties": false, "required": [ "uuid", "reference", "created_at", "url", "qr", "pdf_download_url", "rectifies_uuid", "normalized_data", "metadata", "document_locale" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID del document emès." }, "reference": { "type": [ "string", "null" ], "description": "Referència del client o null.", "pattern": "^[A-Za-z0-9-]+(?![\\s\\S])" }, "created_at": { "type": "string", "format": "date-time", "description": "Instant original de creació, en UTC." }, "url": { "type": "string", "format": "uri", "description": "URL HTTPS completa de descàrrega per QR, amb el seu secret. No la registris ni publiquis." }, "qr": { "type": "object", "additionalProperties": false, "required": [ "mime_type", "encoding", "data" ], "properties": { "mime_type": { "type": "string", "enum": [ "image/png" ] }, "encoding": { "type": "string", "enum": [ "base64" ] }, "data": { "type": "string", "description": "Bytes de la imatge PNG en Base64, sense prefix data URI.", "contentEncoding": "base64" } } }, "pdf_download_url": { "type": "string", "format": "uri", "description": "URL de descàrrega autenticada; requereix el Bearer de la credencial propietària dins de 24 hores." }, "rectifies_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "UUID rectificat o null en una emissió inicial." }, "normalized_data": { "$ref": "#/components/schemas/CreateDocumentRequest" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "La mateixa metadata de la petició; null si no s'ha proporcionat." }, "document_locale": { "type": "string", "enum": [ "es", "ca", "gl", "ca-valencia", "eu", "en", "pt-pt", "fr" ], "description": "Idioma del PDF triat en emetre'l segons l'organització. Es conserva al resultat; canviar l'idioma de l'organització no modifica documents existents. No canvia camps JSON ni missatges d'error de l'API." } } }, "DocumentSummary": { "type": "object", "additionalProperties": false, "required": [ "uuid", "reference", "created_at", "transport_date", "rectifies_uuid" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "reference": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9-]+(?![\\s\\S])" }, "created_at": { "type": "string", "format": "date-time" }, "transport_date": { "type": "string", "format": "date" }, "rectifies_uuid": { "type": [ "string", "null" ], "format": "uuid" } } }, "DocumentList": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentSummary" } }, "meta": { "type": "object", "additionalProperties": false, "required": [ "current_page", "limit", "total", "last_page" ], "properties": { "current_page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 }, "last_page": { "type": "integer", "minimum": 1 } } } } }, "ErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "errors" ], "properties": { "errors": { "type": "array", "minItems": 1, "description": "Tots els errors independents detectats; sense dades de la petició, secrets ni traces.", "items": { "type": "object", "additionalProperties": false, "required": [ "field", "code", "message" ], "properties": { "field": { "type": [ "string", "null" ], "description": "Ruta del camp amb punts; null per a un error general." }, "code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "description": "Codi estable per a la lògica d'integració." }, "message": { "type": "string", "description": "Missatge breu en anglès. No l'utilitzis com a identificador de l'error." } } } } } }, "RectifyDocumentRequest": { "type": "object", "additionalProperties": false, "required": [ "transport_date", "shipper", "carrier", "origin", "destination", "goods", "vehicle" ], "properties": { "reference": { "type": [ "string", "null" ], "minLength": 1, "description": "Referència nova del document rectificatiu, opcional i única per organització i entorn. No reutilitzis la referència del document identificat a la URL.", "pattern": "^[A-Za-z0-9-]+(?![\\s\\S])", "maxLength": 120 }, "transport_date": { "type": "string", "format": "date", "description": "Data real del transport en format YYYY-MM-DD; no és l'instant de creació del PDF." }, "shipper": { "$ref": "#/components/schemas/Shipper" }, "carrier": { "$ref": "#/components/schemas/Carrier" }, "origin": { "$ref": "#/components/schemas/TransportLocation" }, "destination": { "$ref": "#/components/schemas/TransportLocation" }, "goods": { "$ref": "#/components/schemas/Goods" }, "vehicle": { "$ref": "#/components/schemas/Vehicle" }, "special_authorization": { "$ref": "#/components/schemas/SpecialAuthorization" }, "observations": { "type": [ "string", "null" ], "description": "Observacions que els intervinents sol·licitin fer constar al document.", "maxLength": 4000 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Objecte JSON opcional, conservat i retornat sense modificació semàntica. No s'imprimeix al PDF. Màxim 16 KiB en serialitzar-lo i 8 nivells de profunditat." } }, "description": "Totes les dades corregides del transport. El document anterior s'identifica a la URL. Si s'inclou reference, ha de ser una referència nova per al document rectificatiu." }, "DeleteDocumentRequest": { "type": "object", "additionalProperties": false, "required": [ "reason", "confirm_not_delivered", "confirm_not_used" ], "properties": { "reason": { "type": "string", "minLength": 1, "description": "Motiu de l'error detectat en generar el document.", "maxLength": 2000 }, "confirm_not_delivered": { "type": "boolean", "description": "Ha de ser true per eliminar: confirma que no s'ha lliurat al transportista ni al conductor. false retorna 409 DOCUMENT_ALREADY_DELIVERED." }, "confirm_not_used": { "type": "boolean", "description": "Ha de ser true per eliminar: confirma que no s'ha utilitzat en un transport. false retorna 409 DOCUMENT_ALREADY_USED." } } }, "DocumentStatus": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "active", "deleted" ], "description": "Estat del document. No inclou informació del transport, PDF, QR, metadata ni dates." } } }, "DemoTokenResult": { "type": "object", "additionalProperties": false, "required": [ "token", "expires_at", "document_locale" ], "properties": { "token": { "type": "string", "pattern": "^sk_demo_[0-9a-f]{64}(_(ca|gl|ca-valencia|eu|en|pt-pt|fr))?$", "description": "Pots sol·licitar un token `sk_demo_` sense compte ni alta d’una organització. Dura **24 hores des de l’emissió** i només funciona des de la **IP pública que l’ha sol·licitat**. Si canvies de xarxa o d’IP, cal sol·licitar un altre token." }, "expires_at": { "type": "string", "format": "date-time", "description": "Caducitat del token en UTC. Tots els seus documents i enllaços vencen en este instant." }, "document_locale": { "type": "string", "enum": [ "es", "ca", "gl", "ca-valencia", "eu", "en", "pt-pt", "fr" ], "description": "Idioma dels PDF d’este token. Castellà per defecte." } } }, "DemoDocumentResult": { "type": "object", "additionalProperties": false, "required": [ "uuid", "reference", "created_at", "url", "qr", "pdf_download_url", "rectifies_uuid", "normalized_data", "metadata", "document_locale", "demo", "expires_at", "qr_url", "pdf_url" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID del document emès." }, "reference": { "type": [ "string", "null" ], "description": "Referència del client o null.", "pattern": "^[A-Za-z0-9-]+(?![\\s\\S])" }, "created_at": { "type": "string", "format": "date-time", "description": "Instant original de creació, en UTC." }, "url": { "type": "string", "format": "uri", "description": "URL HTTPS completa de descàrrega per QR, amb el seu secret. No la registris ni publiquis." }, "qr": { "type": "object", "additionalProperties": false, "required": [ "mime_type", "encoding", "data" ], "properties": { "mime_type": { "type": "string", "enum": [ "image/png" ] }, "encoding": { "type": "string", "enum": [ "base64" ] }, "data": { "type": "string", "description": "Bytes de la imatge PNG en Base64, sense prefix data URI.", "contentEncoding": "base64" } } }, "pdf_download_url": { "type": "string", "format": "uri", "description": "Pots sol·licitar un token `sk_demo_` sense compte ni alta d’una organització. Dura **24 hores des de l’emissió** i només funciona des de la **IP pública que l’ha sol·licitat**. Si canvies de xarxa o d’IP, cal sol·licitar un altre token." }, "rectifies_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "UUID rectificat o null en una emissió inicial." }, "normalized_data": { "$ref": "#/components/schemas/CreateDocumentRequest" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "La mateixa metadata de la petició; null si no s'ha proporcionat." }, "document_locale": { "type": "string", "enum": [ "es", "ca", "gl", "ca-valencia", "eu", "en", "pt-pt", "fr" ], "description": "Idioma dels PDF d’este token. Castellà per defecte." }, "demo": { "type": "boolean", "enum": [ true ], "description": "Només en la demo; sempre true. No apareix en resultats de desenvolupament o producció." }, "expires_at": { "type": "string", "format": "date-time", "description": "Caducitat del token en UTC. Tots els seus documents i enllaços vencen en este instant." }, "qr_url": { "type": "string", "format": "uri", "description": "Només en la demo; àlies de url." }, "pdf_url": { "type": "string", "format": "uri", "description": "Només en la demo; àlies de pdf_download_url. Requerix el token demo i la seua IP." } }, "description": "La demo afig demo: true, expires_at, qr_url (àlies de url) i pdf_url (àlies de pdf_download_url). document_locale és l’idioma triat en sol·licitar el token (es per defecte). Les dades i PDF temporals estan separats de l’arxiu real i no es xifren com els documents reals." } }, "examples": { "DocumentResult": { "summary": "Resultat complet amb dades fictícies i QR il·lustratiu", "value": { "uuid": "75b10a04-1a2d-4f9e-9277-5f3c270f476e", "reference": "EXP-2026-004587", "created_at": "2026-10-05T14:43:00Z", "url": "https://deca.sertecpesage.com/d/75b10a04-1a2d-4f9e-9277-5f3c270f476e?k=EXAMPLE_SECRET", "qr": { "mime_type": "image/png", "encoding": "base64", "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=" }, "pdf_download_url": "https://deca.sertecpesage.com/api/v1/documents/75b10a04-1a2d-4f9e-9277-5f3c270f476e/pdf", "rectifies_uuid": null, "normalized_data": { "reference": "EXP-2026-004587", "transport_date": "2026-10-05", "shipper": { "name": "Distribuciones Demo, S. L.", "tax_country": "ES", "tax_id": "B12345674", "address": { "street": "Carrer de la Logística, 18", "postal_code": "08040", "city": "Barcelona", "country": "ES" } }, "carrier": { "name": "Transportes Demo, S. L.", "tax_country": "ES", "tax_id": "B87654323" }, "origin": { "place": "Almacén Barcelona", "city": "Barcelona", "country": "ES" }, "destination": { "place": "Almacén Zaragoza", "city": "Zaragoza", "country": "ES" }, "goods": { "description": "Vino embotellado", "weight_kg": "1850" }, "vehicle": { "country": "ES", "registration": "4827MNL", "trailer_country": "ES", "trailer_registration": "R5832BCD" }, "special_authorization": null, "observations": null, "metadata": { "order_id": "4587", "terminal": "POS-02" } }, "metadata": { "order_id": "4587", "terminal": "POS-02" }, "document_locale": "es" } }, "RectifiedDocumentResult": { "summary": "Document rectificatiu amb UUID, PDF i QR nous", "value": { "uuid": "dbf53b0c-e0ec-49a4-952d-ed59d9b1b0d1", "reference": "EXP-2026-004587-R1", "created_at": "2026-10-05T15:00:00Z", "url": "https://deca.sertecpesage.com/d/dbf53b0c-e0ec-49a4-952d-ed59d9b1b0d1?k=EXAMPLE_RECTIFICATION_SECRET", "qr": { "mime_type": "image/png", "encoding": "base64", "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=" }, "pdf_download_url": "https://deca.sertecpesage.com/api/v1/documents/dbf53b0c-e0ec-49a4-952d-ed59d9b1b0d1/pdf", "rectifies_uuid": "75b10a04-1a2d-4f9e-9277-5f3c270f476e", "normalized_data": { "reference": "EXP-2026-004587-R1", "transport_date": "2026-10-05", "shipper": { "name": "Distribuciones Demo, S. L.", "tax_country": "ES", "tax_id": "B12345674", "address": { "street": "Carrer de la Logística, 18", "postal_code": "08040", "city": "Barcelona", "country": "ES" } }, "carrier": { "name": "Transportes Demo, S. L.", "tax_country": "ES", "tax_id": "B87654323" }, "origin": { "place": "Almacén Barcelona", "city": "Barcelona", "country": "ES" }, "destination": { "place": "Almacén Zaragoza", "city": "Zaragoza", "country": "ES" }, "goods": { "description": "Vino embotellado", "weight_kg": "1900" }, "vehicle": { "country": "ES", "registration": "4827MNL", "trailer_country": "ES", "trailer_registration": "R5832BCD" }, "special_authorization": null, "observations": "Corrección del peso de la mercancía.", "metadata": { "order_id": "4587", "terminal": "POS-02" } }, "metadata": { "order_id": "4587", "terminal": "POS-02" }, "document_locale": "es" } } }, "responses": { "PdfDownload": { "description": "PDF original natiu, de fins a 5 MB. Descàrrega directa sense regeneració.", "headers": { "Content-Disposition": { "description": "Nom segur que no incorpora dades del client.", "schema": { "type": "string" }, "examples": { "default": { "value": "attachment; filename=\"deca-75b10a04-1a2d-4f9e-9277-5f3c270f476e.pdf\"" } } }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "Referrer-Policy": { "schema": { "type": "string", "enum": [ "no-referrer" ] }, "description": "Evitar la propagació de la URL secreta." }, "X-Content-Type-Options": { "schema": { "type": "string", "enum": [ "nosniff" ] }, "description": "Impedir la interpretació del contingut com un altre tipus." } }, "content": { "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "PdfPreview": { "description": "PDF original natiu, de fins a 5 MB. Visualització al navegador sense regeneració.", "headers": { "Content-Disposition": { "description": "Nom segur que no incorpora dades del client.", "schema": { "type": "string" }, "examples": { "default": { "value": "inline; filename=\"deca-75b10a04-1a2d-4f9e-9277-5f3c270f476e.pdf\"" } } }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "Referrer-Policy": { "schema": { "type": "string", "enum": [ "no-referrer" ] }, "description": "Evitar la propagació de la URL secreta." }, "X-Content-Type-Options": { "schema": { "type": "string", "enum": [ "nosniff" ] }, "description": "Impedir la interpretació del contingut com un altre tipus." } }, "content": { "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "BadRequest": { "description": "JSON malformat; no es processa la sol·licitud.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "INVALID_JSON", "message": "Request body must contain valid JSON." } ] } } } } } }, "Unauthorized": { "description": "Bearer absent, invàlid o revocat.\n\nUn token demo caducat o enviat des d’una altra IP retorna `401`. Un QR demo caducat retorna `404`. Si la demo està desactivada, retorna `503 DEMO_UNAVAILABLE`. El primer accés al QR o una rectificació impedixen eliminar el document; es mantenen les confirmacions d’esborrament del contracte habitual.", "headers": { "WWW-Authenticate": { "schema": { "type": "string", "examples": [ "Bearer" ] }, "description": "Esquema d'autenticació requerit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "UNAUTHORIZED", "message": "Valid API credentials are required." } ] } } } } } }, "Forbidden": { "description": "IP no autoritzada o acció no permesa per a la credencial.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "FORBIDDEN", "message": "This request is not allowed." } ] } } } } } }, "NotFound": { "description": "Document no disponible per a este accés; no en revela l'existència, el propietari ni el motiu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "DOCUMENT_NOT_AVAILABLE", "message": "Document is not available." } ] } } } } } }, "UnsupportedMediaType": { "description": "Les peticions POST, PUT i DELETE amb cos exigeixen Content-Type application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Content-Type must be application/json." } ] } } } } } }, "ValidationError": { "description": "Camps invàlids; retorna tots els errors independents detectats. Els vuit idiomes tradueixen els títols i les etiquetes del PDF, no els noms, les adreces, les observacions ni altres dades enviades per la integració. Els textos impresos admeten caràcters llatins, grecs i ciríl·lics compatibles amb les fonts; emoji, CJK i escriptures de dreta a esquerra retornen 422 UNSUPPORTED_CHARACTERS al camp afectat. metadata conserva Unicode arbitrari i no s'imprimeix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": "shipper.tax_id", "code": "INVALID_CHECKSUM", "message": "Invalid tax ID checksum." }, { "field": "vehicle.registration", "code": "INVALID_REGISTRATION", "message": "Invalid vehicle registration." }, { "field": "goods.weight_kg", "code": "INVALID_WEIGHT", "message": "Weight must be greater than zero." }, { "field": "goods.description", "code": "UNSUPPORTED_CHARACTERS", "message": "Printable text must use supported Latin, Greek or Cyrillic characters." } ] } } } } } }, "TooManyRequests": { "description": "Límit assolit: 60 peticions per minut i token per a /api/v1, o 30 peticions per minut per a la mateixa IP i document en la descàrrega per QR.\n\nS’ha assolit un límit contra abusos o de capacitat temporal de la demostració; respecta Retry-After. La demo admet cossos de fins a 32 KiB i deu documents per sessió. L’emissió de tokens admet tres per minut i deu per hora des d’una mateixa IP; la creació, cinc per minut i vint per hora des d’una mateixa IP. Els límits compartits per xarxa, regió i càrrega global es poden aplicar abans. Estes xifres corresponen a la configuració predeterminada.", "headers": { "Retry-After": { "description": "Segons que han de transcórrer abans del següent intent.", "schema": { "type": "integer", "minimum": 1, "examples": [ 60 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests." } ] } } } } } }, "InternalError": { "description": "Error intern sense detalls sensibles. Una emissió fallida no deixa un document parcial.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "INTERNAL_ERROR", "message": "An internal error occurred." } ] } } } } } }, "RequestTooLarge": { "description": "El cos supera el límit de 128 KiB.\n\nLa demo admet cossos de fins a 32 KiB i deu documents per sessió. L’emissió de tokens admet tres per minut i deu per hora des d’una mateixa IP; la creació, cinc per minut i vint per hora des d’una mateixa IP. Els límits compartits per xarxa, regió i càrrega global es poden aplicar abans. Estes xifres corresponen a la configuració predeterminada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "REQUEST_TOO_LARGE", "message": "Request body exceeds the 128 KiB limit." } ] } } } } } }, "ServiceUnavailable": { "description": "Servei no disponible per una configuració incorrecta de la URL pública HTTPS. Una emissió fallida no persisteix un document parcial.\n\nLa demostració està desactivada o no està disponible. DEMO_UNAVAILABLE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "SERVICE_UNAVAILABLE", "message": "The document service requires a configured HTTPS public URL." } ] } } } } } }, "DemoUnavailable": { "description": "La demostració està desactivada o no està disponible.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "DEMO_UNAVAILABLE", "message": "The demo is temporarily unavailable." } ] } } } } } }, "DemoRateLimited": { "description": "S’ha assolit un límit contra abusos o de capacitat temporal de la demostració; respecta Retry-After.", "headers": { "Retry-After": { "description": "Segons que han de transcórrer abans del següent intent.", "schema": { "type": "integer", "minimum": 1, "examples": [ 60 ] } }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rateLimit": { "value": { "errors": [ { "field": null, "code": "RATE_LIMIT_EXCEEDED", "message": "Too many demo requests. Try again later." } ] } }, "capacity": { "value": { "errors": [ { "field": null, "code": "DEMO_CAPACITY_REACHED", "message": "The demo has reached its temporary capacity. Try again later." } ] } } } } } } } } }