{ "openapi": "3.1.1", "info": { "title": "API DeCA", "version": "1.0.0", "description": "Espainiako salgaien garraioko administrazio-kontrolerako dokumentuak jaulki, zuzendu, kontsultatu eta deskargatzeko APIa. Token bat lortzeko, jarri harremanetan SERTEC PESAGEren laguntza-zerbitzuarekin. sk_test_ tokenek garapen-ingurunea erabiltzen dute eta sk_live_ tokenek produkzioa, datuak bereizita. IP murrizketa aukerakoa da.\n\nKredentzial bakoitzak bere dokumentuak kontsultatu eta deskargatu ditzake sortu ondorengo 24 orduetan. QR bidezko deskargak bere iraunaldia du. Zuzenketek jatorrizko dokumentua gordetzen dute.\n\nEzabatze logikoa lehenengo 2 orduetan soilik onartzen da, sorrera-akatsak zuzentzeko. Integrazioak baieztatu behar du dokumentua ez zaiola garraiolariari entregatu eta ez dela garraioan erabili. Fitxategia eta trazabilitatea gordetzen dira, baina sarbidea blokeatzen da.\n\n`sk_demo_` token bat eska dezakezu konturik edo erakunderik erregistratu gabe. **Jaulkitzen denetik 24 ordu** irauten du eta **eskatu duen IP publikotik** bakarrik funtzionatzen du. Sarea edo IPa aldatuz gero, beste token bat eskatu behar da. Erabili **fikziozko datuak soilik**. PDFaren orrialde guztietan **BALIORIK GABE** agertzen da logoaren ondoan, eta **DEMO** marka diagonal bat ere bai. Dokumentu hauek ez dute balio salgaiak garraiatzeko edo baliozko administrazio-dokumentu gisa erabiltzeko. Demoak demo: true, expires_at, qr_url (url eremuaren aliasa) eta pdf_url (pdf_download_url eremuaren aliasa) gehitzen ditu. document_locale tokena eskatzean aukeratutako hizkuntza da (es lehenespenez). Aldi baterako datuak eta PDFak benetako artxibotik bereizita daude eta ez dira benetako dokumentuak bezala zifratzen. Demoak gehienez 32 KiB-ko gorputzak eta saioko hamar dokumentu onartzen ditu. IP beretik minutuko hiru eta orduko hamar token jaulki daitezke; dokumentuak sortzeko, minutuko bost eta orduko hogei. Sarearen, eskualdearen eta karga globalaren muga partekatuak lehenago aplika daitezke. Kopuru hauek konfigurazio lehenetsiari dagozkio." }, "servers": [ { "url": "https://deca.sertecpesage.com", "description": "Produkzioa" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Dokumentuak", "description": "Norberaren azken dokumentuak jaulkitzea, zuzentzea eta atzitzea." }, { "name": "QR bidezko deskarga", "description": "PDFa zuzenean deskargatzea dokumentuaren sekretuaren bidez." }, { "name": "APIaren demoa", "description": "Eskuratu aldi baterako token publikoa eta sortu demo-dokumentuak fikziozko datuekin." } ], "paths": { "/api/v1/documents": { "post": { "operationId": "createDocument", "tags": [ "Dokumentuak" ], "summary": "Sortu dokumentua", "description": "Bidali garraioaren datu guztiak. PDF zifratua sortu eta gorde ondoren itzultzen da erantzuna.\n\nNull ez den erreferentzia bakarra da erakunde eta ingurune bakoitzeko. Erreferentzia bera datu normalizatu eta metadata berberekin berriz bidaltzeak jatorrizko emaitza itzultzen du 24 orduko epean (200), beste PDFrik jaulki gabe. Sorrera berri batek 201 itzultzen du. Datu desberdinek edo beste kredentzial baten erreferentziak 409 eragiten dute, dokumentuak zabaldu gabe. Erreferentziarik gabe ez da bikoiztuen ezabaketa bermatzen.\n\nEmaitza iraungita duen erreferentziak 409 DOCUMENT_WINDOW_EXPIRED itzultzen du. Dokumentua ezabatuta badago, ez da edukia itzultzen eta ezin da erreferentzia berrerabili; berriz saiatzeak 404 itzultzen du. Zuzentzeko, erabili PUT endpointak.\n\n`sk_demo_` token bat eska dezakezu konturik edo erakunderik erregistratu gabe. **Jaulkitzen denetik 24 ordu** irauten du eta **eskatu duen IP publikotik** bakarrik funtzionatzen du. Sarea edo IPa aldatuz gero, beste token bat eskatu behar da. Demoak demo: true, expires_at, qr_url (url eremuaren aliasa) eta pdf_url (pdf_download_url eremuaren aliasa) gehitzen ditu. document_locale tokena eskatzean aukeratutako hizkuntza da (es lehenespenez). Aldi baterako datuak eta PDFak benetako artxibotik bereizita daude eta ez dira benetako dokumentuak bezala zifratzen.", "requestBody": { "required": true, "description": "Sortu nahi den dokumentuaren datu guztiak.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentRequest" }, "examples": { "create": { "summary": "Jaulkipena pisuarekin eta atoiarekin", "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": "Ordezko magnitudea pisua zehaztea zaila denean", "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": "Berriz saiatze idempotentea; jatorrizko emaitza itzultzen du beste PDFrik sortu gabe.", "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": "Dokumentu berria sortu eta gorde da.", "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": "Erreferentzia-gatazka edo berriz saiatzearen emaitza iraungia.", "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": [ "Dokumentuak" ], "summary": "Zerrendatu azken dokumentuak", "description": "Laburpenak itzultzen ditu, PDFrik, QR sekreturik eta metadatarik gabe. Zerbitzariak beti aplikatzen ditu 24 orduko epea eta kredentzialen isolamendua. Sorrera-dataren arabera beherantz ordenatzen da, eta berdinketak UUIDarekin ebazten dira; orrialdekako paginazioa eta garraio-dataren iragazki inklusiboak erabiltzen dira. Epea eskaera bakoitzean ebaluatzen da; ez da orrialdeen arteko argazki egonkorra. Ez du historia kontsultatzeko aukerarik ematen.\n\nEzabatutako dokumentuak ez dira zerrendan agertzen.", "parameters": [ { "name": "page", "in": "query", "description": "Eskatutako orrialdea, 1etik hasita.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Dokumentuak orrialdeko, 1etik 100era.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "from", "in": "query", "description": "Garraio-data txikiena, barne. Ez du irakurketa-epea luzatzen.", "schema": { "type": "string", "format": "date" }, "examples": { "default": { "value": "2026-10-05" } } }, { "name": "to", "in": "query", "description": "Garraio-data handiena, barne; from egun berekoa edo ondorengoa.", "schema": { "type": "string", "format": "date" }, "examples": { "default": { "value": "2026-10-05" } } } ], "responses": { "200": { "description": "Azken dokumentuen orrialdea. Emaitzarik gabeko orrialdeak data hutsik du.", "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": [ "Dokumentuak" ], "summary": "Zuzendu dokumentua", "x-deca-order": 20, "description": "Identifikatu aurreko dokumentua UUID bidez eta bidali zuzendutako datu guztiak, aldaketa partzialik gabe. Kredentzial beraren azken bertsioa soilik zuzendu daiteke. 24 ordu baino gehiago duen dokumentua zuzendu daiteke aurreko edukia itzuli gabe. Ezabatutako dokumentuak 404 itzultzen du eta ezin da zuzendu.\n\nDokumentu zuzentzailea sortzen da UUID, PDF eta QR berriekin; jatorrizkoa eta haren QRa gordetzen dira. Eman PDF berria gidariari. Gorputzeko reference eremua bertsio berriari dagokio, ez URLko dokumentuari.\n\nPUT bera datu normalizatu eta metadata berberekin errepikatzeak dagoeneko jaulkitako zuzenketa itzultzen du sortu ondorengo 24 orduetan, beste bertsiorik sortu gabe. Egiaztapen hori dagoeneko zuzendutako dokumentua baztertu aurretik egiten da, eta berriz saiatzeak dokumentu bera erreferentzia bidez identifikatzen badu ere funtzionatzen du. Zuzendutako dokumentu baten datuak aldatzeak 409 itzultzen du. Iraungitako emaitzak 409 DOCUMENT_WINDOW_EXPIRED itzultzen du. Itzulitako zuzenketa ezabatuta badago, berriz saiatzeak 404 itzultzen du. Beste zuzenketa baterako, erabili azken bertsioaren UUIDa edo erreferentzia.", "requestBody": { "required": true, "description": "Garraioaren zuzendutako datu guztiak.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RectifyDocumentRequest" }, "examples": { "rectify": { "summary": "Zuzenketa osoa erreferentzia berriarekin", "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": "Dokumentu zuzentzailea jaulki da, edo berriz saiatze berdinaren emaitza itzuli da beste bertsiorik sortu gabe.", "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": "Dokumentua zuzenduta dago, erreferentzia berriak gatazka du edo emaitza iraungi da.", "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": [ "Dokumentuak" ], "summary": "Ezabatu dokumentua", "x-deca-order": 40, "description": "Dokumentua sortzean aurkitutako akatsak zuzentzeko ezabatze logikoa, soilik **garraiolariari edo gidariari entregatu aurretik eta garraio batean erabili aurretik**. Integrazioak bi baldintzak baieztatu behar ditu; epearen barruan egotea ez da nahikoa. Dokumentua entregatu edo erabili bada, PUT bidez zuzendu behar da.\n\nZerbitzariaren ordua created_at + **2 ordu** baino lehenagokoa den bitartean soilik onartzen da; 2 ordu zehatzetan ez da onartzen. Kontsultek eta berriz saiatzeek ez dute epea berrabiarazten. Bertsio bakoitzak bere sorrera-data erabiltzen du. Autentifikatutako kredentzialaren azken bertsioa soilik ezabatu daiteke.\n\nPDFa, datuak eta trazabilitatea gordetzen dira, baina dokumentua zerrendatik desagertzen da. UUID edo erreferentzia bidezko kontsultek, deskarga autentifikatuak, QRak eta edukia itzuliko luketen berriz saiatzeek 404 erantzuten dute. Egoera-kontsultak status: deleted soilik itzultzen du 24 orduko kontsulta-epean. Erreferentzia erreserbatuta geratzen da. Ez dago berraktibatzeko endpointik; fitxategia gordetzen da etorkizunean berreskuratu ahal izateko.\n\nDELETE 2 ordu berberen barruan errepikatzeak 204 itzultzen du ezabatze-data aldatu gabe. Epea igarota, 409 itzultzen du.\n\nQR estekaren bidezko lehen sarbide zuzenak ere ezabatzea blokeatzen du 409 DOCUMENT_ALREADY_ACCESSED errorearekin. Sarbide horrek, berez, ez du garraioa egin dela frogatzen.", "requestBody": { "required": true, "description": "Arrazoia eta dokumentua oraindik entregatu edo erabili ez dela baieztatzea.", "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": "Dokumentua ezabatutzat markatu da. Erantzun-gorputzik gabe.", "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": "2 orduko epea igaro da, dokumentua entregatu edo erabili da, edo bertsioa zuzenduta dago. QR estekaren bidezko lehen sarbide zuzenak ere ezabatzea blokeatzen du 409 DOCUMENT_ALREADY_ACCESSED errorearekin. Sarbide horrek, berez, ez du garraioa egin dela frogatzen.", "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": [ "Dokumentuak" ], "summary": "Kontsultatu dokumentua", "description": "Jatorrizko emaitza berreskuratzen du 24 orduko epean, dokumentua jaulki zuen kredentzialarentzat soilik. Onartutako eta normalizatutako eremu guztiak eta aldaketa semantikorik gabeko metadata biltzen ditu.\n\nExistitzen ez den, beste kredentzial bati dagokion edo epetik kanpoko UUID edo erreferentzia batek `404` bera itzultzen du, existentzia edo jabea baieztatu gabe. Erreferentzia bakoitzak bere bertsioa identifikatzen du eta ez du ondorengo zuzenketa batera birbideratzen.\n\nEzabatutako dokumentuak 404 itzultzen du. Ezabatuta dagoen jakiteko, erabili egoera-kontsulta.", "responses": { "200": { "description": "Dokumentuaren jatorrizko emaitza.", "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": [ "Dokumentuak" ], "summary": "Kontsultatu egoera", "x-deca-order": 80, "description": "Autentifikatutako kredentzialaren dokumentu baten egoera soilik itzultzen du, sortu ondorengo 24 orduetan. Ezabatutako dokumentuak 200 erantzuten du {\"status\":\"deleted\"} balioarekin; ez du garraio-daturik, PDFrik, QR estekarik edo metadatarik itzultzen. Dokumentu aktiboak {\"status\":\"active\"} erantzuten du.\n\nExistitzen ez den, beste kredentzial bati dagokion edo 24 orduko epetik kanpoko UUID batek 404 bera itzultzen du. Ezabatzeak ez du epea luzatzen.", "responses": { "200": { "description": "Dokumentuaren egoera, edukiko daturik gabe.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentStatus" }, "examples": { "deleted": { "summary": "Ezabatutako dokumentua", "value": { "status": "deleted" } }, "active": { "summary": "Dokumentu aktiboa", "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": "Dokumentuaren UUID publikoa. Bestela, erabili `GET /api/v1/documents/ref/{reference}/pdf`. Adibidea: `/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": [ "Dokumentuak" ], "summary": "Deskargatu PDFa", "description": "Gordetako PDFaren byte zehatzak itzultzen ditu, berriz sortu gabe. Kredentzial jabea eta 24 ordu baino gutxiagoko dokumentua behar dira. Muga horrek ez du legezko kontserbazioa edo QRaren iraunaldia aldatzen.\n\nEzabatutako dokumentuak 404 itzultzen du PDFa entregatu gabe.", "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": [ "QR bidezko deskarga" ], "summary": "Deskargatu PDFa QR bidez", "description": "QRan sartutako esteka. k sekretuak dokumentu hau soilik baimentzen du. Ez da Bearer, saio, CAPTCHA edo tarteko orririk behar. Esteka ezagutzen duen edonork deskargatu dezake. Ez erregistratu URL osoa logetan, analitikan edo aztarnetan.\n\nDeskarga ez da 24 ordura iraungitzen eta ez da automatikoki baliogabetzen Bearerra biratzean edo baliogabetzean. Aurreko QRak bere PDFa mantentzen du zuzenketa baten ondoren; ez du bertsio berrira birbideratzen.\n\nPDFa `Content-Disposition: inline` bidez entregatzen da, nabigatzailearen ikustailean irekitzeko.\n\nEzabatutako dokumentuak 404 itzultzen du, sekretua zuzena izan arren.", "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": [ "APIaren demoa" ], "summary": "Eskatu demo-tokena", "description": "Bidali JSON objektu huts bat endpoint publiko honetara. Ez du Bearer goibururik behar. `201` erantzunak `token` eta `expires_at` ditu; iraungitze-data UTCn adierazten da.\n\n`sk_demo_` token bat eska dezakezu konturik edo erakunderik erregistratu gabe. **Jaulkitzen denetik 24 ordu** irauten du eta **eskatu duen IP publikotik** bakarrik funtzionatzen du. Sarea edo IPa aldatuz gero, beste token bat eskatu behar da.\n\nErabili **fikziozko datuak soilik**. PDFaren orrialde guztietan **BALIORIK GABE** agertzen da logoaren ondoan, eta **DEMO** marka diagonal bat ere bai. Dokumentu hauek ez dute balio salgaiak garraiatzeko edo baliozko administrazio-dokumentu gisa erabiltzeko.\n\nDemoak gehienez 32 KiB-ko gorputzak eta saioko hamar dokumentu onartzen ditu. IP beretik minutuko hiru eta orduko hamar token jaulki daitezke; dokumentuak sortzeko, minutuko bost eta orduko hogei. Sarearen, eskualdearen eta karga globalaren muga partekatuak lehenago aplika daitezke. Kopuru hauek konfigurazio lehenetsiari dagozkio. document_locale bidal dezakezu tokenaren PDF guztien hizkuntza aukeratzeko: es, ca, gl, ca-valencia, eu, en, pt-pt edo fr. Eremua bidaltzen ez bada, es erabiltzen da. Erantzunak document_locale ere badu; aldatzeko token berri bat eskatu behar da.", "security": [], "requestBody": { "required": true, "description": "Bidali JSON objektu huts bat endpoint publiko honetara. Ez du Bearer goibururik behar. `201` erantzunak `token` eta `expires_at` ditu; iraungitze-data UTCn adierazten da. document_locale bidal dezakezu tokenaren PDF guztien hizkuntza aukeratzeko: es, ca, gl, ca-valencia, eu, en, pt-pt edo fr. Eremua bidaltzen ez bada, es erabiltzen da. Erantzunak document_locale ere badu; aldatzeko token berri bat eskatu behar da.", "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": "Token honen PDFen hizkuntza. Gaztelania lehenespenez." } } }, "examples": { "default": { "value": {} } } } } }, "responses": { "201": { "description": "Demo-tokena jaulki da; 24 orduz balio du eta eskatzailearen IPari lotuta dago.", "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": [ "APIaren demoa" ], "summary": "Ireki demo-PDFa QR bidez", "description": "QRak PDFa zuzenean irekitzen du nabigatzailean `/demo/d/{uuid}?k=...` bidez, Bearerrik gabe. Dokumentua eta haren estekak demo-saioarekin batera iraungitzen dira; dokumentua sortzeak edo zuzentzeak ez du tokenaren iraupena luzatzen.\n\nErabili **fikziozko datuak soilik**. PDFaren orrialde guztietan **BALIORIK GABE** agertzen da logoaren ondoan, eta **DEMO** marka diagonal bat ere bai. Dokumentu hauek ez dute balio salgaiak garraiatzeko edo baliozko administrazio-dokumentu gisa erabiltzeko.", "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": "SERTEC PESAGEren laguntza-zerbitzuak emandako integrazio-tokena. Bidali Authorization: Bearer goiburuan, HTTPS bidez soilik. sk_test_ garapen-ingurunea da eta sk_live_ produkzioa. Tokenak baimendutako IPen zerrenda badu, eskaerak haietako batetik etorri behar du; zerrenda hutsak edozein IP baimentzen du. Ez bidali tokena URLan eta ez erakutsi bezero-aplikazioetan.\n\n`sk_demo_` token bat eska dezakezu konturik edo erakunderik erregistratu gabe. **Jaulkitzen denetik 24 ordu** irauten du eta **eskatu duen IP publikotik** bakarrik funtzionatzen du. Sarea edo IPa aldatuz gero, beste token bat eskatu behar da. Erabili **fikziozko datuak soilik**. PDFaren orrialde guztietan **BALIORIK GABE** agertzen da logoaren ondoan, eta **DEMO** marka diagonal bat ere bai. Dokumentu hauek ez dute balio salgaiak garraiatzeko edo baliozko administrazio-dokumentu gisa erabiltzeko." }, "qrSecret": { "type": "apiKey", "in": "query", "name": "k", "description": "QR estekaren sekretu opakua; kopiatu url eremuan itzulitako balioa zehazki." } }, "parameters": { "DocumentUuid": { "name": "uuid", "in": "path", "required": true, "description": "Dokumentuaren UUID publikoa; hura ezagutzeak ez du sarbiderik ematen.", "schema": { "type": "string", "format": "uuid" }, "examples": { "default": { "value": "75b10a04-1a2d-4f9e-9277-5f3c270f476e" } } }, "DocumentUuidWithReferenceAlternative": { "name": "uuid", "in": "path", "required": true, "description": "Dokumentuaren UUID publikoa. Bestela, erabili `/api/v1/documents/ref/{reference}` metodo berarekin. Adibidea: `/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": "Dokumentuaren UUID publikoa. Bestela, erabili `GET /api/v1/documents/ref/{reference}/status`. Adibidea: `/api/v1/documents/ref/EXP-2026-004587/status`.", "schema": { "type": "string", "format": "uuid" }, "examples": { "default": { "value": "75b10a04-1a2d-4f9e-9277-5f3c270f476e" } } } }, "headers": { "NoStore": { "description": "Erantzunak informazio sentikorra dauka eta ez da cachean gorde behar.", "schema": { "type": "string", "examples": [ "no-store, private" ] } } }, "schemas": { "CountryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Bi letrako herrialde-kodea; maiuskulaz normalizatzen da. Formatuak ez du ISO 3166-1 katalogoko kidetza egiaztatzen.", "examples": [ "ES" ] }, "PositiveDecimal": { "type": "string", "pattern": "^(?!0+(?:\\.0+)?$)(?:0|[1-9][0-9]{0,14})(?:\\.[0-9]{1,6})?$", "description": "Hamartar positiboa string gisa, puntuarekin, komarik eta notazio zientifikorik gabe. Gehienez 15 digitu oso eta 6 hamartar. Erantzunak amaierako zero hamartarrak kentzen ditu.", "examples": [ "1850.000" ] }, "WeightKilograms": { "oneOf": [ { "$ref": "#/components/schemas/PositiveDecimal" }, { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1000000000000000, "multipleOf": 0.000001 } ], "description": "Pisu positiboa kg-tan, JSON zenbaki edo testu hamartar gisa. Gehienez 15 digitu oso eta 6 hamartar. Erantzunak testu gisa normalizatzen du eta zehaztasuna gordetzen du; PDFak gehienez 3 hamartar erakusten ditu, koma hamartarrarekin eta milakoak puntuz bereizita. Balio handietan zehaztasuna ez galtzeko, erabili testu hamartarra.", "examples": [ 1850.5 ] }, "Address": { "type": "object", "additionalProperties": false, "required": [ "street", "postal_code", "city", "country" ], "properties": { "street": { "type": "string", "minLength": 1, "description": "Helbideko kalea eta zenbakia.", "maxLength": 255 }, "postal_code": { "type": "string", "minLength": 1, "description": "Posta-kodea testu gisa, hasierako zeroak gordetzeko.", "maxLength": 255 }, "city": { "type": "string", "minLength": 1, "description": "Helbideko herria.", "maxLength": 255 }, "country": { "$ref": "#/components/schemas/CountryCode" } } }, "Shipper": { "type": "object", "additionalProperties": false, "required": [ "name", "tax_country", "tax_id", "address" ], "description": "Kontratuzko kargatzailea; jatorriko biltegitik eta DeCA bezeroarengandik desberdina izan daiteke.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Izena edo sozietate-izena.", "maxLength": 255 }, "tax_country": { "$ref": "#/components/schemas/CountryCode" }, "tax_id": { "type": "string", "minLength": 1, "description": "Identifikatzaile fiskala maiuskulaz normalizatzen da, zuriunerik eta marratxorik gabe; luzera normalizatu ondoren egiaztatzen da. Espainian DNI, NIE eta erakundeen IFZen (CIF) formatua eta kontrol-karakterea baliozkotzen dira. K, L eta M IFZ berezien formatua soilik egiaztatzen da: aurrizkia, zazpi karaktere alfanumeriko eta azken letra. Beste herrialdeetarako formatu alfanumerikoa eskatzen da, kontrol fiskala egiaztatu gabe. Baliozkotzeak ez du existentzia edo erroldako alta frogatzen.", "maxLength": 32 }, "address": { "$ref": "#/components/schemas/Address" } } }, "Carrier": { "type": "object", "additionalProperties": false, "required": [ "name", "tax_country", "tax_id" ], "description": "Garraioa benetan egiten duen garraiolaria, azpikontratatua barne.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Izena edo sozietate-izena.", "maxLength": 255 }, "tax_country": { "$ref": "#/components/schemas/CountryCode" }, "tax_id": { "type": "string", "minLength": 1, "description": "Identifikatzaile fiskala maiuskulaz normalizatzen da, zuriunerik eta marratxorik gabe; luzera normalizatu ondoren egiaztatzen da. Espainian DNI, NIE eta erakundeen IFZen (CIF) formatua eta kontrol-karakterea baliozkotzen dira. K, L eta M IFZ berezien formatua soilik egiaztatzen da: aurrizkia, zazpi karaktere alfanumeriko eta azken letra. Beste herrialdeetarako formatu alfanumerikoa eskatzen da, kontrol fiskala egiaztatu gabe. Baliozkotzeak ez du existentzia edo erroldako alta frogatzen.", "maxLength": 32 }, "address": { "description": "Garraiolariaren aukerako helbidea. Bidaltzen bada, Address eremu guztiak behar dira; 6. artikuluak ez du gutxieneko datu gisa eskatzen.", "type": "object", "additionalProperties": false, "required": [ "street", "postal_code", "city", "country" ], "properties": { "street": { "type": "string", "minLength": 1, "description": "Helbideko kalea eta zenbakia.", "maxLength": 255 }, "postal_code": { "type": "string", "minLength": 1, "description": "Posta-kodea testu gisa, hasierako zeroak gordetzeko.", "maxLength": 255 }, "city": { "type": "string", "minLength": 1, "description": "Helbideko herria.", "maxLength": 255 }, "country": { "$ref": "#/components/schemas/CountryCode" } } } } }, "TransportLocation": { "type": "object", "additionalProperties": false, "required": [ "place", "city", "country" ], "properties": { "place": { "type": "string", "minLength": 1, "description": "Benetako karga- edo deskarga-lekua, instalazioaren izenaren edo helbidearen bidez identifikagarria. city eta country eremuekin lekua argi identifikatu behar du; street eta postal_code aukerakoak dira. Enpresa hartzailearen identitatea ez da nahitaezko gutxieneko datua.", "maxLength": 255 }, "city": { "type": "string", "minLength": 1, "description": "Herria.", "maxLength": 255 }, "country": { "type": "string", "enum": [ "ES" ], "description": "Hasierako esparruak Espainia barruko garraioak hartzen ditu; ez du nazioarteko CMRa ordezkatzen." }, "street": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Karga- edo deskarga-lekuko aukerako kalea eta zenbakia, kokalekua zehazteko." }, "postal_code": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Karga- edo deskarga-lekuko aukerako posta-kodea, testu gisa hasierako zeroak gordetzeko." } } }, "AlternativeMeasure": { "type": "object", "additionalProperties": false, "required": [ "value", "unit" ], "description": "Beste magnitude bat pisua zehaztea zaila denean. Bidali magnitude hau edo pisua, inoiz ez biak.", "properties": { "value": { "$ref": "#/components/schemas/PositiveDecimal" }, "unit": { "type": "string", "minLength": 1, "description": "Magnitudearen unitate esplizitua, gehienez 255 karaktere.", "maxLength": 255, "examples": [ "palés" ] } } }, "Goods": { "type": "object", "additionalProperties": false, "required": [ "description" ], "description": "Salgaien izaera eta pisua, edo ordezko magnitudea dagokionean. Bidali neurri bakarra.", "properties": { "description": { "type": "string", "minLength": 1, "description": "Salgaien izaeraren deskribapena.", "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": "Benetako ibilgailua; atoia edo erdiatoia badago, bete haren bi eremuak batera.", "properties": { "country": { "$ref": "#/components/schemas/CountryCode" }, "registration": { "type": "string", "minLength": 1, "description": "Matrikula maiuskulaz normalizatzen da, zuriunerik eta marratxorik gabe. Espainian egungo ohiko matrikulak, lehengo probintzia-matrikulak eta E serie berezia onartzen dira. Beste herrialdeetarako, 3 eta 20 karaktere alfanumeriko artean.", "maxLength": 20, "examples": [ "4827 MNL" ] }, "trailer_country": { "$ref": "#/components/schemas/CountryCode" }, "trailer_registration": { "type": "string", "minLength": 1, "description": "Atoiaren edo erdiatoiaren matrikula, traktorearena bezala normalizatua. Espainian R seriea eskatzen da. Beste herrialdeetarako, 3 eta 20 karaktere alfanumeriko artean.", "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": "Zirkulazio-baimen berezia beharrezkoa denean. Ez bidali edo bidali null ez badagokio.", "properties": { "number": { "type": "string", "minLength": 1, "description": "Baimenaren zenbakia edo erreferentzia.", "maxLength": 255 }, "issuer": { "type": "string", "minLength": 1, "description": "Erakunde igorlea, adierazten bada.", "maxLength": 255 } } }, "CreateDocumentRequest": { "type": "object", "additionalProperties": false, "required": [ "transport_date", "shipper", "carrier", "origin", "destination", "goods", "vehicle" ], "properties": { "reference": { "type": [ "string", "null" ], "minLength": 1, "description": "Norberaren aukerako erreferentzia, erakunde eta ingurune bakoitzeko bakarra eta PDFan inprimatua. Berriz saiatzeak identifikatzen ditu eta erreferentzia bidez kontsultatzeko aukera ematen du. Ez da askatzen dokumentua ezabatzean.", "pattern": "^[A-Za-z0-9-]+(?![\\s\\S])", "maxLength": 120 }, "transport_date": { "type": "string", "format": "date", "description": "Benetako garraio-data YYYY-MM-DD formatuan; ez da PDFaren sorrera-unea." }, "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": "Parte-hartzaileek dokumentuan jasotzeko eskatzen dituzten oharrak.", "maxLength": 4000 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Aukerako JSON objektua, aldaketa semantikorik gabe gorde eta itzultzen dena. Ez da PDFan inprimatzen. Gehienez 16 KiB serializatzean eta 8 sakonera-maila." } } }, "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": "Jaulkitako dokumentuaren UUIDa." }, "reference": { "type": [ "string", "null" ], "description": "Bezeroaren erreferentzia edo null.", "pattern": "^[A-Za-z0-9-]+(?![\\s\\S])" }, "created_at": { "type": "string", "format": "date-time", "description": "Jatorrizko sorrera-unea, UTCn." }, "url": { "type": "string", "format": "uri", "description": "QR bidez deskargatzeko HTTPS URL osoa, sekretua barne. Ez erregistratu edo argitaratu." }, "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": "PNG irudiaren byteak Base64 formatuan, data URI aurrizkirik gabe.", "contentEncoding": "base64" } } }, "pdf_download_url": { "type": "string", "format": "uri", "description": "Deskarga autentifikatuaren URLa; kredentzial jabearen Bearerra behar du 24 orduko epean." }, "rectifies_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "Zuzendutako UUIDa edo null hasierako jaulkipenean." }, "normalized_data": { "$ref": "#/components/schemas/CreateDocumentRequest" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Eskaeraren metadata bera; null eman ez bada." }, "document_locale": { "type": "string", "enum": [ "es", "ca", "gl", "ca-valencia", "eu", "en", "pt-pt", "fr" ], "description": "Jaulkitzean erakundearen arabera hautatutako PDFaren hizkuntza. Emaitzan gordetzen da; erakundearen hizkuntza aldatzeak ez ditu lehendik dauden dokumentuak aldatzen. Ez ditu JSON eremuak edo APIaren errore-mezuak aldatzen." } } }, "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": "Detektatutako errore independente guztiak; eskaera-daturik, sekreturik edo aztarnarik gabe.", "items": { "type": "object", "additionalProperties": false, "required": [ "field", "code", "message" ], "properties": { "field": { "type": [ "string", "null" ], "description": "Puntuz bereizitako eremu-bidea; null errore orokor baterako." }, "code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "description": "Integrazio-logikarako kode egonkorra." }, "message": { "type": "string", "description": "Mezu laburra ingelesez. Ez erabili errorearen identifikatzaile gisa." } } } } } }, "RectifyDocumentRequest": { "type": "object", "additionalProperties": false, "required": [ "transport_date", "shipper", "carrier", "origin", "destination", "goods", "vehicle" ], "properties": { "reference": { "type": [ "string", "null" ], "minLength": 1, "description": "Dokumentu zuzentzailearen erreferentzia berria, aukerakoa eta erakunde eta ingurune bakoitzeko bakarra. Ez berrerabili URLan identifikatutako dokumentuaren erreferentzia.", "pattern": "^[A-Za-z0-9-]+(?![\\s\\S])", "maxLength": 120 }, "transport_date": { "type": "string", "format": "date", "description": "Benetako garraio-data YYYY-MM-DD formatuan; ez da PDFaren sorrera-unea." }, "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": "Parte-hartzaileek dokumentuan jasotzeko eskatzen dituzten oharrak.", "maxLength": 4000 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Aukerako JSON objektua, aldaketa semantikorik gabe gorde eta itzultzen dena. Ez da PDFan inprimatzen. Gehienez 16 KiB serializatzean eta 8 sakonera-maila." } }, "description": "Garraioaren zuzendutako datu guztiak. Aurreko dokumentua URLan identifikatzen da. reference sartzen bada, dokumentu zuzentzailearen erreferentzia berria izan behar du." }, "DeleteDocumentRequest": { "type": "object", "additionalProperties": false, "required": [ "reason", "confirm_not_delivered", "confirm_not_used" ], "properties": { "reason": { "type": "string", "minLength": 1, "description": "Dokumentua sortzean detektatutako akatsaren arrazoia.", "maxLength": 2000 }, "confirm_not_delivered": { "type": "boolean", "description": "Ezabatzeko true izan behar du: garraiolariari edo gidariari entregatu ez zaiola baieztatzen du. false balioak 409 DOCUMENT_ALREADY_DELIVERED itzultzen du." }, "confirm_not_used": { "type": "boolean", "description": "Ezabatzeko true izan behar du: garraio batean erabili ez dela baieztatzen du. false balioak 409 DOCUMENT_ALREADY_USED itzultzen du." } } }, "DocumentStatus": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "active", "deleted" ], "description": "Dokumentuaren egoera. Ez du garraio-informaziorik, PDFrik, QRrik, metadatarik edo datarik." } } }, "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": "`sk_demo_` token bat eska dezakezu konturik edo erakunderik erregistratu gabe. **Jaulkitzen denetik 24 ordu** irauten du eta **eskatu duen IP publikotik** bakarrik funtzionatzen du. Sarea edo IPa aldatuz gero, beste token bat eskatu behar da." }, "expires_at": { "type": "string", "format": "date-time", "description": "Tokenaren iraungitze-unea UTCn. Haren dokumentu eta esteka guztiak une honetan iraungitzen dira." }, "document_locale": { "type": "string", "enum": [ "es", "ca", "gl", "ca-valencia", "eu", "en", "pt-pt", "fr" ], "description": "Token honen PDFen hizkuntza. Gaztelania lehenespenez." } } }, "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": "Jaulkitako dokumentuaren UUIDa." }, "reference": { "type": [ "string", "null" ], "description": "Bezeroaren erreferentzia edo null.", "pattern": "^[A-Za-z0-9-]+(?![\\s\\S])" }, "created_at": { "type": "string", "format": "date-time", "description": "Jatorrizko sorrera-unea, UTCn." }, "url": { "type": "string", "format": "uri", "description": "QR bidez deskargatzeko HTTPS URL osoa, sekretua barne. Ez erregistratu edo argitaratu." }, "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": "PNG irudiaren byteak Base64 formatuan, data URI aurrizkirik gabe.", "contentEncoding": "base64" } } }, "pdf_download_url": { "type": "string", "format": "uri", "description": "`sk_demo_` token bat eska dezakezu konturik edo erakunderik erregistratu gabe. **Jaulkitzen denetik 24 ordu** irauten du eta **eskatu duen IP publikotik** bakarrik funtzionatzen du. Sarea edo IPa aldatuz gero, beste token bat eskatu behar da." }, "rectifies_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "Zuzendutako UUIDa edo null hasierako jaulkipenean." }, "normalized_data": { "$ref": "#/components/schemas/CreateDocumentRequest" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Eskaeraren metadata bera; null eman ez bada." }, "document_locale": { "type": "string", "enum": [ "es", "ca", "gl", "ca-valencia", "eu", "en", "pt-pt", "fr" ], "description": "Token honen PDFen hizkuntza. Gaztelania lehenespenez." }, "demo": { "type": "boolean", "enum": [ true ], "description": "Demoan soilik; beti true da. Ez da garapeneko edo produkzioko emaitzetan agertzen." }, "expires_at": { "type": "string", "format": "date-time", "description": "Tokenaren iraungitze-unea UTCn. Haren dokumentu eta esteka guztiak une honetan iraungitzen dira." }, "qr_url": { "type": "string", "format": "uri", "description": "Demoan soilik; url eremuaren aliasa." }, "pdf_url": { "type": "string", "format": "uri", "description": "Demoan soilik; pdf_download_url eremuaren aliasa. Demo-tokena eta haren IPa behar ditu." } }, "description": "Demoak demo: true, expires_at, qr_url (url eremuaren aliasa) eta pdf_url (pdf_download_url eremuaren aliasa) gehitzen ditu. document_locale tokena eskatzean aukeratutako hizkuntza da (es lehenespenez). Aldi baterako datuak eta PDFak benetako artxibotik bereizita daude eta ez dira benetako dokumentuak bezala zifratzen." } }, "examples": { "DocumentResult": { "summary": "Emaitza osoa fikziozko datuekin eta erakusgarri den QRarekin", "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": "Dokumentu zuzentzailea UUID, PDF eta QR berriekin", "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": "Jatorrizko PDF natiboa, gehienez 5 MB. Deskarga zuzena, berriz sortu gabe.", "headers": { "Content-Disposition": { "description": "Bezeroaren daturik ez duen izen segurua.", "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": "URL sekretuaren hedapena saihestu." }, "X-Content-Type-Options": { "schema": { "type": "string", "enum": [ "nosniff" ] }, "description": "Edukia beste mota bat bezala interpretatzea eragotzi." } }, "content": { "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "PdfPreview": { "description": "Jatorrizko PDF natiboa, gehienez 5 MB. Nabigatzailean bistaratzea, berriz sortu gabe.", "headers": { "Content-Disposition": { "description": "Bezeroaren daturik ez duen izen segurua.", "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": "URL sekretuaren hedapena saihestu." }, "X-Content-Type-Options": { "schema": { "type": "string", "enum": [ "nosniff" ] }, "description": "Edukia beste mota bat bezala interpretatzea eragotzi." } }, "content": { "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "BadRequest": { "description": "JSON gaizki eratua; eskaera ez da prozesatzen.", "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 falta da, baliogabea da edo baliogabetu da.\n\nIraungitako edo beste IP batetik bidalitako demo-tokenak `401` itzultzen du. Iraungitako demo-QRak `404` itzultzen du. Demoa desgaituta badago, `503 DEMO_UNAVAILABLE` itzultzen du. QRrako lehen sarbideak edo zuzenketa batek dokumentua ezabatzea eragozten dute; ohiko kontratuaren ezabatze-baieztapenak mantentzen dira.", "headers": { "WWW-Authenticate": { "schema": { "type": "string", "examples": [ "Bearer" ] }, "description": "Beharrezko autentifikazio-eskema." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "UNAUTHORIZED", "message": "Valid API credentials are required." } ] } } } } } }, "Forbidden": { "description": "Baimendu gabeko IPa edo kredentzialarentzat onartu gabeko ekintza.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "FORBIDDEN", "message": "This request is not allowed." } ] } } } } } }, "NotFound": { "description": "Dokumentua ez dago eskuragarri sarbide honetarako; ez du existentzia, jabea edo arrazoia erakusten.", "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": "Gorputza duten POST, PUT eta DELETE eskaerek Content-Type application/json behar dute.", "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": "Eremu baliogabeak; detektatutako errore independente guztiak itzultzen ditu. Zortzi hizkuntzek PDFaren izenburuak eta etiketak itzultzen dituzte, ez integrazioak bidalitako izenak, helbideak, oharrak edo beste datuak. Inprimatutako testuek letra-tipoek onartutako karaktere latindarrak, grekoak eta zirilikoak onartzen dituzte; emojiek, CJK karaktereek eta eskuinetik ezkerrerako idazkerek 422 UNSUPPORTED_CHARACTERS itzultzen dute dagokion eremuan. metadata eremuak edozein Unicode gordetzen du eta ez da inprimatzen.", "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": "Muga lortu da: /api/v1-erako 60 eskaera minutuko eta tokeneko, edo QR deskargarako 30 eskaera minutuko IP eta dokumentu bererako.\n\nGehiegizko erabileraren aurkako muga edo demoaren aldi baterako edukiera gainditu da; bete Retry-After. Demoak gehienez 32 KiB-ko gorputzak eta saioko hamar dokumentu onartzen ditu. IP beretik minutuko hiru eta orduko hamar token jaulki daitezke; dokumentuak sortzeko, minutuko bost eta orduko hogei. Sarearen, eskualdearen eta karga globalaren muga partekatuak lehenago aplika daitezke. Kopuru hauek konfigurazio lehenetsiari dagozkio.", "headers": { "Retry-After": { "description": "Hurrengo saiakeraren aurretik itxaron beharreko segundoak.", "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": "Barne-errorea, xehetasun sentikorrik gabe. Huts egindako jaulkipenak ez du dokumentu partzialik uzten.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "errors": [ { "field": null, "code": "INTERNAL_ERROR", "message": "An internal error occurred." } ] } } } } } }, "RequestTooLarge": { "description": "Gorputzak 128 KiB-ko muga gainditzen du.\n\nDemoak gehienez 32 KiB-ko gorputzak eta saioko hamar dokumentu onartzen ditu. IP beretik minutuko hiru eta orduko hamar token jaulki daitezke; dokumentuak sortzeko, minutuko bost eta orduko hogei. Sarearen, eskualdearen eta karga globalaren muga partekatuak lehenago aplika daitezke. Kopuru hauek konfigurazio lehenetsiari dagozkio.", "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": "Zerbitzua ez dago erabilgarri HTTPS URL publikoa gaizki konfiguratuta dagoelako. Huts egindako jaulkipenak ez du dokumentu partzialik gordetzen.\n\nDemoa desgaituta dago edo ez dago erabilgarri. 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": "Demoa desgaituta dago edo ez dago erabilgarri.", "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": "Gehiegizko erabileraren aurkako muga edo demoaren aldi baterako edukiera gainditu da; bete Retry-After.", "headers": { "Retry-After": { "description": "Hurrengo saiakeraren aurretik itxaron beharreko segundoak.", "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." } ] } } } } } } } } }