{ "swagger": "2.0", "info": { "title": "DeCA Profesional", "version": "1", "description": "Custom connector for the DeCA Profesional API (Business + API add-on)." }, "host": "decaprofesional.es", "basePath": "/", "schemes": [ "https" ], "securityDefinitions": { "apiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Type: Bearer " } }, "security": [ { "apiKey": [] } ], "definitions": { "Party": { "type": "object", "additionalProperties": false, "required": [ "name", "taxId", "address" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "taxId": { "type": "string", "maxLength": 40, "description": "Tax identification number (Spanish NIF / VAT number)." }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "Country (ISO alpha-2). Defaults to Spain (ES)." }, "address": { "type": "string", "maxLength": 300 }, "postalCode": { "type": "string", "maxLength": 12 }, "city": { "type": "string", "maxLength": 120 } } }, "Location": { "type": "object", "additionalProperties": false, "required": [ "name", "address", "postalCode", "city", "country" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "address": { "type": "string", "maxLength": 300 }, "postalCode": { "type": "string", "maxLength": 12 }, "city": { "type": "string", "maxLength": 120 }, "province": { "type": "string", "maxLength": 120 }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2 code (ES, FR, PT…)." } } }, "Shipment": { "type": "object", "additionalProperties": false, "required": [ "loadLocation", "unloadLocation" ], "properties": { "loadLocation": { "$ref": "#/definitions/Location" }, "unloadLocation": { "$ref": "#/definitions/Location" }, "goods": { "type": "string", "maxLength": 300, "description": "Nature of the goods." }, "weight": { "description": "Weight or measure: a number (kg) or a text (e.g. \"12.000 kg\").", "oneOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 10000000 }, { "type": "string", "maxLength": 60 } ] }, "recipient": { "type": "string", "maxLength": 200 }, "loadDate": { "type": "string", "pattern": "^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$", "description": "Date DD-MM-YYYY (YYYY-MM-DD is also accepted).", "examples": [ "06-10-2026" ] }, "unloadDate": { "type": "string", "pattern": "^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$", "description": "Date DD-MM-YYYY (YYYY-MM-DD is also accepted).", "examples": [ "06-10-2026" ] }, "tractorPlate": { "type": "string", "maxLength": 20 }, "trailerPlate": { "type": "string", "maxLength": 20 }, "notes": { "type": "string", "maxLength": 1000, "description": "Special information for the shipment. Multiple lines are allowed (line breaks)." } } }, "CompletionRequest": { "type": "object", "additionalProperties": false, "required": [ "recipientEmail", "fields" ], "properties": { "recipientEmail": { "type": "string", "format": "email", "maxLength": 200 }, "recipientName": { "type": "string", "maxLength": 200 }, "recipientType": { "type": "string", "enum": [ "shipper", "carrier", "authorized_person" ] }, "fields": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "maxLength": 80 }, "description": "Fields the third party completes, e.g. vehicle.tractorPlate, shipments[0].unloadLocation.city." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 48 } } }, "DecaCreate": { "type": "object", "additionalProperties": false, "required": [ "loadDate", "unloadDate", "vehicle", "shipper", "carrier", "shipments" ], "properties": { "externalId": { "type": "string", "pattern": "^[A-Za-z0-9._\\-/]{1,100}$", "description": "Your identifier (order, consignment). Prevents duplicates: a second active DeCA with the same externalId answers 409." }, "groupageRef": { "type": "string", "pattern": "^[Gg]-[A-Za-z0-9]{6,16}$", "description": "Optional: operational reference shared by the independent DeCA of a groupage (one DeCA per shipper). Filterable with GET /decas?groupageRef=…" }, "serviceType": { "type": "string", "enum": [ "goods", "passenger" ], "default": "goods" }, "reference": { "type": "string", "maxLength": 120, "description": "DeCA reference / notes." }, "notes": { "type": "string", "maxLength": 1000, "description": "Special information (default for every shipment). Multiple lines are allowed (line breaks)." }, "loadDate": { "type": "string", "pattern": "^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$", "description": "Date DD-MM-YYYY (YYYY-MM-DD is also accepted).", "examples": [ "06-10-2026" ] }, "unloadDate": { "type": "string", "pattern": "^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$", "description": "Date DD-MM-YYYY (YYYY-MM-DD is also accepted).", "examples": [ "06-10-2026" ] }, "vehicle": { "type": "object", "additionalProperties": false, "required": [ "tractorPlate" ], "properties": { "tractorPlate": { "type": "string", "maxLength": 20 }, "trailerPlate": { "type": "string", "maxLength": 20 }, "secondTrailerPlate": { "type": "string", "maxLength": 20, "description": "Optional: second trailer/semi-trailer (double-trailer combinations). Requires trailerPlate and must differ from it." } } }, "shipper": { "description": "Contractual shipper: \"self\" (your company) or its details.", "oneOf": [ { "const": "self" }, { "$ref": "#/definitions/Party" } ] }, "carrier": { "description": "Actual carrier: \"self\" (your company) or its details.", "oneOf": [ { "const": "self" }, { "$ref": "#/definitions/Party" } ] }, "shipments": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/definitions/Shipment" } }, "completionRequest": { "$ref": "#/definitions/CompletionRequest" }, "draft": { "type": "boolean", "description": "true: saves a draft instead of issuing the DeCA." }, "loadOrder": { "type": "object", "description": "Issues a load order WITH this DeCA (same rules as the web app): only if your company is the contractual shipper and the plan includes load orders.", "properties": { "format": { "type": "string", "enum": [ "joint", "separate" ] }, "price": { "type": "string", "description": "Amount, e.g. \"850,00\" (empty = no price)." }, "currency": { "type": "string", "enum": [ "EUR", "USD", "GBP", "CHF" ] }, "taxNote": { "type": "string" }, "conditions": { "type": "string" }, "paymentTerms": { "type": "string" }, "billingInstructions": { "type": "string" } }, "required": [ "format" ] } } }, "Correction": { "type": "object", "required": [ "changeReason", "deca" ], "properties": { "changeReason": { "type": "string", "minLength": 3, "maxLength": 500 }, "baseVersionNo": { "type": "integer", "minimum": 1, "description": "The version you are correcting (prevents concurrent corrections: 409)." }, "deca": { "$ref": "#/definitions/DecaCreate" } } }, "Annulment": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 500 } } }, "VehicleChange": { "type": "object", "additionalProperties": false, "required": [ "tractorPlate", "effectiveAt" ], "properties": { "tractorPlate": { "type": "string", "maxLength": 20 }, "trailerPlate": { "type": "string", "maxLength": 20 }, "effectiveAt": { "type": "string", "pattern": "^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$", "description": "Date DD-MM-YYYY (YYYY-MM-DD is also accepted).", "examples": [ "06-10-2026" ] }, "reason": { "type": "string", "maxLength": 200 } } }, "CompletionResendRequest": { "type": "object", "properties": { "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 48 } } }, "DraftCreate": { "type": "object", "description": "Any subset of the DecaCreate fields (without completionRequest or draft).", "properties": { "externalId": { "type": "string", "pattern": "^[A-Za-z0-9._\\-/]{1,100}$" }, "reference": { "type": "string", "maxLength": 120 }, "loadDate": { "type": "string", "pattern": "^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$", "description": "Date DD-MM-YYYY (YYYY-MM-DD is also accepted).", "examples": [ "06-10-2026" ] }, "unloadDate": { "type": "string", "pattern": "^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$", "description": "Date DD-MM-YYYY (YYYY-MM-DD is also accepted).", "examples": [ "06-10-2026" ] }, "vehicle": { "type": "object" }, "shipper": {}, "carrier": {}, "shipments": { "type": "array", "items": { "type": "object" } } } }, "DraftPatch": { "type": "object", "description": "JSON Merge Patch (RFC 7386) applied to the draft." }, "DecaStatus": { "type": "object", "required": [ "id", "reference", "status", "availability", "version", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "reference": { "type": "string", "x-nullable": true, "examples": [ "DECA-A4F2C9E1" ] }, "externalId": { "type": "string", "x-nullable": true }, "groupageRef": { "type": "string", "x-nullable": true }, "status": { "type": "string", "enum": [ "active", "annulled" ] }, "availability": { "type": "string", "enum": [ "public", "expired", "annulled" ] }, "version": { "type": "integer", "x-nullable": true }, "createdAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "updatedAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "annulledAt": { "type": "string", "x-nullable": true, "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "service": { "type": "object", "properties": { "finished": { "type": "boolean" }, "finishedAt": { "type": "string", "x-nullable": true, "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "note": { "type": "string", "x-nullable": true } } }, "verificationUrl": { "type": "string", "x-nullable": true, "format": "uri" } } }, "ServiceCompletion": { "type": "object", "additionalProperties": false, "properties": { "note": { "type": "string", "maxLength": 500, "description": "Optional remark." } } }, "LoadOrder": { "type": "object", "required": [ "id", "number", "status", "format" ], "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_vehicle", "active", "cancelled" ] }, "format": { "type": "string", "enum": [ "joint", "separate" ] }, "reference": { "type": "string", "x-nullable": true }, "carrierName": { "type": "string", "x-nullable": true }, "loadDate": { "type": "string", "x-nullable": true, "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "DD-MM-YYYY" }, "deca": { "type": "object", "x-nullable": true, "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "annulled" ] } } }, "platesPending": { "type": "boolean" }, "version": { "type": "object", "x-nullable": true, "properties": { "number": { "type": "integer" }, "kind": { "type": "string" }, "createdAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "pdfSha256": { "type": "string", "x-nullable": true } } }, "acceptance": { "type": "object", "x-nullable": true, "properties": { "versionNo": { "type": "integer" }, "acceptedAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" } } }, "createdAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "LoadOrderList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/LoadOrder" } } } }, "Deca": { "type": "object", "required": [ "id", "status", "verification", "pdf", "links" ], "properties": { "id": { "type": "string" }, "reference": { "type": "string", "x-nullable": true }, "externalId": { "type": "string", "x-nullable": true }, "groupageRef": { "type": "string", "x-nullable": true, "description": "Operational groupage reference (G-…), shared by the independent DeCA of one operation." }, "status": { "type": "string", "enum": [ "active", "annulled" ] }, "availability": { "type": "string", "enum": [ "public", "expired", "annulled" ] }, "version": { "type": "integer", "x-nullable": true }, "createdAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "updatedAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "annulledAt": { "type": "string", "x-nullable": true, "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "service": { "type": "object", "description": "OPERATIONAL service-finished flag; it never changes the administrative status, the PDF or the URL.", "properties": { "finished": { "type": "boolean" }, "finishedAt": { "type": "string", "x-nullable": true, "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "note": { "type": "string", "x-nullable": true } } }, "serviceType": { "type": "string", "enum": [ "goods", "passenger" ] }, "servicePeriod": { "type": "object", "properties": { "start": { "type": "string", "x-nullable": true, "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "DD-MM-YYYY" }, "end": { "type": "string", "x-nullable": true, "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "DD-MM-YYYY" }, "publicUntil": { "type": "string", "x-nullable": true, "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "DD-MM-YYYY" } } }, "verification": { "type": "object", "properties": { "url": { "type": "string", "x-nullable": true, "format": "uri" }, "note": { "type": "string" } } }, "pdf": { "type": "object", "properties": { "href": { "type": "string" }, "sha256": { "type": "string", "x-nullable": true }, "contentType": { "const": "application/pdf" } } }, "data": { "type": "object", "x-nullable": true, "description": "DeCA content (parties, vehicle, shipments); dates DD-MM-YYYY." }, "warnings": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "DecaList": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/DecaListItem" } }, "nextCursor": { "type": "string", "x-nullable": true } } }, "DecaListItem": { "type": "object", "description": "A DeCA in the list: the lightweight status (as in GET /decas/{id}/status), the verification URL, a summary and the links. The full content is at GET /decas/{id}.", "required": [ "id", "reference", "status", "availability", "version", "createdAt", "updatedAt", "verificationUrl", "summary", "links" ], "properties": { "id": { "type": "string" }, "reference": { "type": "string", "x-nullable": true, "examples": [ "DECA-A4F2C9E1" ] }, "externalId": { "type": "string", "x-nullable": true }, "groupageRef": { "type": "string", "x-nullable": true }, "status": { "type": "string", "enum": [ "active", "annulled" ] }, "availability": { "type": "string", "enum": [ "public", "expired", "annulled" ] }, "version": { "type": "integer", "x-nullable": true }, "createdAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "updatedAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "annulledAt": { "type": "string", "x-nullable": true, "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "service": { "type": "object", "properties": { "finished": { "type": "boolean" }, "finishedAt": { "type": "string", "x-nullable": true, "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "note": { "type": "string", "x-nullable": true } } }, "verificationUrl": { "type": "string", "x-nullable": true, "format": "uri" }, "summary": { "type": "object", "x-nullable": true, "properties": { "shipper": { "type": "string", "x-nullable": true, "description": "Shipper name." }, "carrier": { "type": "string", "x-nullable": true, "description": "Carrier name." }, "tractorPlate": { "type": "string", "x-nullable": true }, "loadDate": { "type": "string", "x-nullable": true, "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "DD-MM-YYYY" }, "shipmentCount": { "type": "integer" } } }, "links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "Validation": { "type": "object", "required": [ "valid", "warnings" ], "properties": { "valid": { "const": true }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "VersionList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "version", "current", "createdAt", "actorType", "verificationUrl", "pdf" ], "properties": { "version": { "type": "integer" }, "current": { "type": "boolean" }, "createdAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "changeReason": { "type": "string", "x-nullable": true }, "actorType": { "type": "string", "enum": [ "api", "user", "anonymous" ] }, "verificationUrl": { "type": "string", "format": "uri" }, "pdf": { "type": "object", "properties": { "href": { "type": "string" }, "sha256": { "type": "string", "x-nullable": true } } } } } } } }, "VehicleList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "initial", "change" ] }, "tractorPlate": { "type": "string" }, "trailerPlate": { "type": "string", "x-nullable": true }, "effectiveAt": { "type": "string", "x-nullable": true, "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "DD-MM-YYYY" }, "reason": { "type": "string", "x-nullable": true }, "current": { "type": "boolean" } } } } } }, "Me": { "type": "object", "required": [ "credential", "company", "access", "limits", "usage" ], "properties": { "credential": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string", "description": "Masked key: the secret is never returned." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "test = test key (fvd_test_)." }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "expiresAt": { "type": "string", "x-nullable": true, "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" } } }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "taxId": { "type": "string", "x-nullable": true } } }, "access": { "type": "object", "properties": { "plan": { "type": "string", "description": "The company's plan." }, "businessEligible": { "type": "boolean", "description": "The plan allows API access." }, "apiEntitlement": { "type": "string", "enum": [ "paid", "manual", "none" ], "description": "Source of the API access." }, "paidAddon": { "type": "string", "enum": [ "active", "cancelling", "inactive" ], "description": "Status of the API add-on." }, "manualGrant": { "type": "string", "enum": [ "active", "expired", "ended", "none" ] } } }, "limits": { "type": "object", "properties": { "requestsPerMinute": { "type": "integer" }, "createsPerDay": { "type": "integer" } } }, "usage": { "type": "object", "properties": { "decasThisMonth": { "type": "integer", "description": "DeCA created in the current plan period (API and dashboard share the allowance)." }, "planMonthlyLimit": { "type": "integer", "x-nullable": true, "description": "Monthly plan allowance (null = unlimited)." }, "remainingThisMonth": { "type": "integer", "x-nullable": true }, "decasThisPeriod": { "type": "integer" }, "remainingThisPeriod": { "type": "integer", "x-nullable": true }, "periodStart": { "type": "string", "x-nullable": true, "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "periodEnd": { "type": "string", "x-nullable": true, "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" } } } } }, "Draft": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string" }, "draftId": { "type": "string" }, "object": { "type": "string", "enum": [ "api_draft", "draft" ], "description": "api_draft = created through the API; draft = draft started in the web app." }, "origin": { "type": "string", "enum": [ "api", "web" ] }, "status": { "type": "string", "enum": [ "open", "generated", "cancelled" ] }, "version": { "type": "integer", "description": "Draft version (ETag \".\")." }, "externalId": { "type": "string", "x-nullable": true }, "data": { "type": "object" }, "ready": { "type": "boolean", "description": "Only on open drafts read one by one: true if the DeCA can be generated now." }, "warnings": { "type": "array", "items": { "type": "string" } }, "issues": { "type": "array", "description": "What is missing or invalid (empty when ready is true).", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "createdBy": { "type": "string", "x-nullable": true, "description": "Web drafts only." }, "updatedBy": { "type": "string", "x-nullable": true, "description": "Web drafts only." }, "decaId": { "type": "string", "x-nullable": true }, "generatedAt": { "type": "string", "x-nullable": true, "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "cancelledAt": { "type": "string", "x-nullable": true, "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "createdAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "updatedAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "DraftList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/Draft" } }, "nextCursor": { "type": "string", "x-nullable": true } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "createdAt", "livemode", "data" ], "description": "Notification sent to your endpoint. Headers: DeCA-Event-Id, DeCA-Event-Type, DeCA-Signature (t=,v1=.\">).", "properties": { "id": { "type": "string", "description": "Identical across retries: use it to discard duplicates." }, "type": { "type": "string", "enum": [ "deca.created", "deca.corrected", "deca.annulled", "draft.generated", "completion.completed", "deca.service_finished", "deca.service_reopened", "load_order.issued", "load_order.accepted", "webhook.test" ] }, "createdAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "livemode": { "type": "boolean" }, "data": { "type": "object" } } }, "CompletionRequestResult": { "type": "object", "description": "Draft with its third-party completion request (status, recipient, expiry)." }, "SavedCompanyInput": { "type": "object", "additionalProperties": false, "required": [ "name", "taxId", "address", "postalCode", "city" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "taxId": { "type": "string", "minLength": 3, "maxLength": 20 }, "address": { "type": "string", "minLength": 4, "maxLength": 300 }, "postalCode": { "type": "string", "minLength": 3, "maxLength": 12 }, "city": { "type": "string", "minLength": 2, "maxLength": 120 }, "role": { "type": "string", "enum": [ "shipper", "carrier", "both" ] } } }, "SavedVehicleInput": { "type": "object", "additionalProperties": false, "required": [ "tractorPlate" ], "properties": { "tractorPlate": { "type": "string", "minLength": 2, "maxLength": 20 }, "trailerPlate": { "type": "string", "maxLength": 20 }, "alias": { "type": "string", "maxLength": 80 }, "habitualDriver": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "email": { "type": "string", "maxLength": 200 } } } } }, "SavedPlaceInput": { "type": "object", "additionalProperties": false, "required": [ "name", "address", "postalCode", "city" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "address": { "type": "string", "minLength": 4, "maxLength": 300 }, "postalCode": { "type": "string", "minLength": 3, "maxLength": 12 }, "city": { "type": "string", "minLength": 2, "maxLength": 120 }, "province": { "type": "string", "maxLength": 120 }, "country": { "type": "string", "maxLength": 80 }, "type": { "type": "string", "enum": [ "load", "unload", "both" ] } } }, "SavedShipmentInput": { "type": "object", "additionalProperties": false, "required": [ "loadPlaceExternalId", "unloadPlaceExternalId" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "loadPlaceExternalId": { "type": "string", "pattern": "^[A-Za-z0-9._~:-]{1,100}$" }, "unloadPlaceExternalId": { "type": "string", "pattern": "^[A-Za-z0-9._~:-]{1,100}$" }, "goods": { "type": "string", "maxLength": 300 }, "weight": { "type": "string", "maxLength": 60 }, "recipient": { "type": "string", "maxLength": 200 } } }, "SavedRecord": { "type": "object", "description": "A Saved data record: id, externalId (null if it was created in the web app), createdAt and the resource fields (those of its *Input; shipments return loadPlace and unloadPlace with id, externalId and name).", "properties": { "id": { "type": "string" }, "externalId": { "type": "string", "x-nullable": true }, "createdAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" } } }, "SavedList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/SavedRecord" } }, "nextCursor": { "type": "string", "x-nullable": true } } }, "SavedDeleted": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "externalId": { "type": "string" } } }, "BatchCreate": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/definitions/DecaCreate" } } } }, "Batch": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "completed" ] }, "total": { "type": "integer" }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "createdAt": { "type": "string", "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "completedAt": { "type": "string", "x-nullable": true, "description": "ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "externalId": { "type": "string", "x-nullable": true }, "status": { "type": "string", "enum": [ "pending", "processing", "created", "replayed", "failed" ] }, "decaId": { "type": "string", "x-nullable": true }, "error": { "type": "object", "x-nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "pdfs": { "type": "string" } } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "description": "Stable error code: branch your integration on it." }, "message": { "type": "string", "description": "Informative message: Spanish by default, English with `Accept-Language: en`. Never parse it." }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "paths": { "/api/v1/me": { "get": { "operationId": "get_me", "summary": "Checks the credential: integration, company, permissions, limits and usage this month.", "description": "The first endpoint to call to verify the connection.\n\nNo specific scope required.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Me" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/validate": { "post": { "operationId": "post_decas_validate", "summary": "Validates a DeCA without creating it: same rules as creation.", "description": "It creates no DeCA, generates no PDF and does not use up the plan allowance.\n\nRequired scope: deca:create.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DecaCreate" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Validation" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas": { "post": { "operationId": "post_decas", "summary": "Creates a DeCA and returns the verification URL, the reference and the PDF.", "description": "Returns 201 (or 200 if it is a retry with the same Idempotency-Key). With completionRequest (or draft: true) it creates a draft and returns 202: see «Completion of a DeCA by a third party».\n\nRequired scope: deca:create.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result.", "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DecaCreate" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Deca" } }, "default": { "description": "Error (check error.code)" } } }, "get": { "operationId": "get_decas", "summary": "Lists the DeCAs, newest first, with cursor pagination.", "description": "Filters: limit (1–100, default 25), cursor, externalId, groupageRef (groupage reference, G-…), status (active | annulled), createdFrom, createdTo (DD-MM-YYYY, days in Madrid time; createdTo includes the whole of that day). All API dates are in DD-MM-YYYY and all times in Madrid time.\n\nRequired scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–100, default 25).", "type": "string" }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the previous page.", "type": "string" }, { "name": "externalId", "in": "query", "required": false, "description": "Exact match on externalId.", "type": "string" }, { "name": "groupageRef", "in": "query", "required": false, "description": "Groupage reference (G-…); case-insensitive.", "type": "string" }, { "name": "status", "in": "query", "required": false, "description": "Administrative status.", "type": "string" }, { "name": "createdFrom", "in": "query", "required": false, "description": "Created on or after this day (DD-MM-YYYY, day in Europe/Madrid time; an ISO 8601 date-time with time zone is also accepted).", "type": "string" }, { "name": "createdTo", "in": "query", "required": false, "description": "Created up to and including this day (DD-MM-YYYY, day in Europe/Madrid time; an ISO 8601 date-time with time zone is also accepted).", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DecaList" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/{id}": { "get": { "operationId": "get_decas_id", "summary": "The full DeCA: status, service period, verification URL, PDF and data.", "description": "Required scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DeCA identifier.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Deca" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/{id}/status": { "get": { "operationId": "get_decas_id_status", "summary": "Lightweight status (version, availability, verification URL) for periodic polling.", "description": "Required scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DeCA identifier.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DecaStatus" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/{id}/versions": { "get": { "operationId": "get_decas_id_versions", "summary": "Version history: reason for the change, origin (api / user), and the URL and PDF of each version.", "description": "Required scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DeCA identifier.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/VersionList" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/{id}/pdf": { "get": { "operationId": "get_decas_id_pdf", "summary": "Downloads the PDF (current version or ?version=N).", "description": "Headers X-Pdf-Sha256 (PDF fingerprint) and X-Deca-Status (active | annulled).\n\nRequired scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/pdf" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DeCA identifier.", "type": "string" }, { "name": "version", "in": "query", "required": false, "description": "Version number (default: the current version).", "type": "string" } ], "responses": { "200": { "description": "Success" }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/{id}/corrections": { "post": { "operationId": "post_decas_id_corrections", "summary": "Corrects a DeCA: creates a new version with a new URL, QR code and PDF.", "description": "Returns 201 with the new version (200 if it is a retry with the same Idempotency-Key). Only DeCAs created by the same integration; previous versions are kept.\n\nRequired scope: deca:correct.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DeCA identifier.", "type": "string" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result.", "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Correction" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Deca" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/{id}/vehicles": { "get": { "operationId": "get_decas_id_vehicles", "summary": "Vehicles of the transport: the initial one and every recorded change, with the current one flagged.", "description": "Required scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DeCA identifier.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/VehicleList" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/{id}/vehicle-changes": { "post": { "operationId": "post_decas_id_vehicle_changes", "summary": "Records a vehicle change (tractor unit and, if it changes, trailer) during the transport.", "description": "It is a correction: a new version with a new URL, QR code and PDF, which does not use up any DeCA from the plan. The date (DD-MM-YYYY) must fall within the transport and after the previous change. Without trailerPlate the previous trailer is kept. Returns 201 (200 if it is a retry with the same Idempotency-Key).\n\nRequired scope: deca:correct.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DeCA identifier.", "type": "string" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result.", "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/VehicleChange" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Deca" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/{id}/annulment": { "post": { "operationId": "post_decas_id_annulment", "summary": "Annuls a DeCA. The annulment is final; repeating the call returns 200 with no changes.", "description": "Only DeCAs created by the same integration.\n\nRequired scope: deca:annul.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DeCA identifier.", "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Annulment" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Deca" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/{id}/completion-request": { "post": { "operationId": "post_decas_id_completion_request", "summary": "Asks a third party, by email, for the data missing from a draft.", "description": "Returns 201 (200 if it is a retry with the same Idempotency-Key). Only drafts of the same integration.\n\nRequired scope: deca:create.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DeCA identifier.", "type": "string" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result.", "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/CompletionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CompletionRequestResult" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/{id}/completion-request/resend": { "post": { "operationId": "post_decas_id_completion_request_resend", "summary": "Resends the request with a new link (the previous one stops working).", "description": "Returns 201 (200 if it is a retry). At most 5 resends per draft per hour.\n\nRequired scope: deca:create.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DeCA identifier.", "type": "string" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CompletionRequestResult" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/batch": { "post": { "operationId": "post_decas_batch", "summary": "Creates up to 50 DeCAs in a single call (batch).", "description": "Body { items: [ …same format as POST /decas… ] }. Returns 202 with the batch already validated: each item is pending or failed with its details (one error does not affect the others). Creation continues in the background; check GET /api/v1/batches/{id}. Each item uses up one DeCA from the plan, like a normal creation. The same Idempotency-Key with the same body returns the same batch (200); a DeCA is never duplicated.\n\nRequired scope: deca:create.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Batch" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/batches/{id}": { "get": { "operationId": "get_batches_id", "summary": "Status of the batch and result of each item (created, replayed, failed, pending).", "description": "status changes from processing to completed when every item has finished.\n\nRequired scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Batch identifier.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Batch" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/batches/{id}/pdfs": { "get": { "operationId": "get_batches_id_pdfs", "summary": "Downloads a ZIP file with the current PDF of each DeCA created by the batch.", "description": "Returns 409 batch_without_documents if the batch has not created any DeCA yet.\n\nRequired scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/zip" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Batch identifier.", "type": "string" } ], "responses": { "200": { "description": "Success" }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/drafts": { "post": { "operationId": "post_drafts", "summary": "Opens a new, independent draft (partial data). It does not use up the allowance.", "description": "Returns 201 with draftId (200 if it is a retry with the same Idempotency-Key).\n\nRequired scope: deca:create.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result.", "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DraftCreate" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Draft" } }, "default": { "description": "Error (check error.code)" } } }, "get": { "operationId": "get_drafts", "summary": "Lists the drafts: status=open (default) | generated | cancelled | all.", "description": "Paginated with limit and cursor, like /decas. Drafts belong to the company: with deca:read_company you also see the drafts started on the website (origin: \"web\") and those of other integrations, and you can complete, generate or discard them.\n\nRequired scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Draft status (default open).", "type": "string" }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–100, default 25).", "type": "string" }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the previous page.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DraftList" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/drafts/{id}": { "get": { "operationId": "get_drafts_id", "summary": "A draft, with ready and issues (what is still missing before it can be generated).", "description": "Required scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Draft identifier.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Draft" } }, "default": { "description": "Error (check error.code)" } } }, "patch": { "operationId": "patch_drafts_id", "summary": "Modifies or completes an open draft (JSON Merge Patch).", "description": "Optional If-Match with the ETag: 412 if another change arrived first.\n\nRequired scope: deca:create.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Draft identifier.", "type": "string" }, { "name": "If-Match", "in": "header", "required": false, "description": "ETag read from the draft: prevents overwriting someone else's changes (412 precondition_failed).", "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DraftPatch" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Draft" } }, "default": { "description": "Error (check error.code)" } } }, "delete": { "operationId": "delete_drafts_id", "summary": "Discards an open draft (it becomes cancelled).", "description": "Required scope: deca:create.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Draft identifier.", "type": "string" }, { "name": "If-Match", "in": "header", "required": false, "description": "ETag read from the draft: prevents overwriting someone else's changes (412 precondition_failed).", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Draft" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/drafts/{id}/generate": { "post": { "operationId": "post_drafts_id_generate", "summary": "Generates the final DeCA from that draft; the other drafts do not change.", "description": "201 with the DeCA; repeating the call returns the same DeCA (200). This is where the allowance is used up.\n\nRequired scope: deca:create.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Draft identifier.", "type": "string" }, { "name": "If-Match", "in": "header", "required": false, "description": "ETag read from the draft: prevents overwriting someone else's changes (412 precondition_failed).", "type": "string" } ], "responses": { "201": { "description": "Success", "schema": { "$ref": "#/definitions/Deca" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/decas/{id}/service-completion": { "post": { "operationId": "post_decas_id_service_completion", "summary": "Marks the service as finished (operational data; the DeCA, its PDF and its URL do not change).", "description": "Optional body { note } (up to 500 characters). Idempotent: returns the DeCA with service.finished. 409 deca_annulled on an annulled DeCA. Webhook deca.service_finished.\n\nRequired scope: deca:correct.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DeCA identifier.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Deca" } }, "default": { "description": "Error (check error.code)" } } }, "delete": { "operationId": "delete_decas_id_service_completion", "summary": "Reopens a service marked as finished (it goes back to pending).", "description": "Idempotent. Webhook deca.service_reopened.\n\nRequired scope: deca:correct.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DeCA identifier.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/Deca" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/load-orders": { "get": { "operationId": "get_load_orders", "summary": "Lists the load orders: number, status, format (combined or separate), linked DeCA, pending plates an", "description": "Filters: decaId, status (pending_vehicle | active | cancelled), limit (1–100). Without deca:read_company, only those of DeCAs created by your integration. It never includes the price or the conditions (they are in the PDF). To issue one: POST /api/v1/decas with loadOrder.\n\nRequired scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "decaId", "in": "query", "required": false, "description": "Only the load order of this DeCA.", "type": "string" }, { "name": "status", "in": "query", "required": false, "description": "Load order status.", "type": "string" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of load orders (1–100, default 50).", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/LoadOrderList" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/load-orders/{id}": { "get": { "operationId": "get_load_orders_id", "summary": "A load order: status, current version, linked DeCA and acceptance by the carrier.", "description": "Required scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Load order identifier.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/LoadOrder" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/load-orders/{id}/pdf": { "get": { "operationId": "get_load_orders_id_pdf", "summary": "The PDF of the current version of the load order.", "description": "Required scope: deca:read.", "consumes": [ "application/json" ], "produces": [ "application/pdf" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Load order identifier.", "type": "string" } ], "responses": { "200": { "description": "Success" }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/saved/companies": { "get": { "operationId": "get_saved_companies", "summary": "Lists the saved companies (shippers and carriers) of the company.", "description": "In order of creation. Parameters: limit (1–100, default 50), cursor (nextCursor from the previous page) and externalId (exact match). Also includes the records created on the website (externalId null).\n\nRequired scope: saved:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page (default 50).", "type": "string" }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the previous page.", "type": "string" }, { "name": "externalId", "in": "query", "required": false, "description": "Exact match on externalId.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedList" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/saved/companies/{externalId}": { "get": { "operationId": "get_saved_companies_externalId", "summary": "Reads a record by the identifier from your ERP or TMS (externalId).", "description": "Required scope: saved:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "The record's identifier in your ERP or TMS.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedRecord" } }, "default": { "description": "Error (check error.code)" } } }, "put": { "operationId": "put_saved_companies_externalId", "summary": "Creates or updates the record with that externalId (sync without duplicates).", "description": "Returns 201 when it creates the record and 200 when it updates it; repeating the same call leaves the same record. It is validated with the same rules as the website and appears immediately in Saved data («Datos habituales»). It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "The record's identifier in your ERP or TMS.", "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/SavedCompanyInput" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedRecord" } }, "default": { "description": "Error (check error.code)" } } }, "delete": { "operationId": "delete_saved_companies_externalId", "summary": "Deletes the record with that externalId.", "description": "It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "The record's identifier in your ERP or TMS.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedDeleted" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/saved/vehicles": { "get": { "operationId": "get_saved_vehicles", "summary": "Lists the saved vehicles (with their usual driver) of the company.", "description": "In order of creation. Parameters: limit (1–100, default 50), cursor (nextCursor from the previous page) and externalId (exact match). Also includes the records created on the website (externalId null).\n\nRequired scope: saved:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page (default 50).", "type": "string" }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the previous page.", "type": "string" }, { "name": "externalId", "in": "query", "required": false, "description": "Exact match on externalId.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedList" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/saved/vehicles/{externalId}": { "get": { "operationId": "get_saved_vehicles_externalId", "summary": "Reads a record by the identifier from your ERP or TMS (externalId).", "description": "Required scope: saved:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "The record's identifier in your ERP or TMS.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedRecord" } }, "default": { "description": "Error (check error.code)" } } }, "put": { "operationId": "put_saved_vehicles_externalId", "summary": "Creates or updates the record with that externalId (sync without duplicates).", "description": "Returns 201 when it creates the record and 200 when it updates it; repeating the same call leaves the same record. It is validated with the same rules as the website and appears immediately in Saved data («Datos habituales»). It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "The record's identifier in your ERP or TMS.", "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/SavedVehicleInput" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedRecord" } }, "default": { "description": "Error (check error.code)" } } }, "delete": { "operationId": "delete_saved_vehicles_externalId", "summary": "Deletes the record with that externalId.", "description": "It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "The record's identifier in your ERP or TMS.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedDeleted" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/saved/places": { "get": { "operationId": "get_saved_places", "summary": "Lists the saved loading and unloading places of the company.", "description": "In order of creation. Parameters: limit (1–100, default 50), cursor (nextCursor from the previous page) and externalId (exact match). Also includes the records created on the website (externalId null).\n\nRequired scope: saved:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page (default 50).", "type": "string" }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the previous page.", "type": "string" }, { "name": "externalId", "in": "query", "required": false, "description": "Exact match on externalId.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedList" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/saved/places/{externalId}": { "get": { "operationId": "get_saved_places_externalId", "summary": "Reads a record by the identifier from your ERP or TMS (externalId).", "description": "Required scope: saved:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "The record's identifier in your ERP or TMS.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedRecord" } }, "default": { "description": "Error (check error.code)" } } }, "put": { "operationId": "put_saved_places_externalId", "summary": "Creates or updates the record with that externalId (sync without duplicates).", "description": "Returns 201 when it creates the record and 200 when it updates it; repeating the same call leaves the same record. It is validated with the same rules as the website and appears immediately in Saved data («Datos habituales»). It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "The record's identifier in your ERP or TMS.", "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/SavedPlaceInput" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedRecord" } }, "default": { "description": "Error (check error.code)" } } }, "delete": { "operationId": "delete_saved_places_externalId", "summary": "Deletes the record with that externalId.", "description": "Returns 409 saved_in_use if a saved shipment uses that place.\n\nRequired scope: saved:write.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "The record's identifier in your ERP or TMS.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedDeleted" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/saved/shipments": { "get": { "operationId": "get_saved_shipments", "summary": "Lists the saved shipments (loading place + unloading place + goods) of the company.", "description": "In order of creation. Parameters: limit (1–100, default 50), cursor (nextCursor from the previous page) and externalId (exact match). Also includes the records created on the website (externalId null).\n\nRequired scope: saved:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page (default 50).", "type": "string" }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the previous page.", "type": "string" }, { "name": "externalId", "in": "query", "required": false, "description": "Exact match on externalId.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedList" } }, "default": { "description": "Error (check error.code)" } } } }, "/api/v1/saved/shipments/{externalId}": { "get": { "operationId": "get_saved_shipments_externalId", "summary": "Reads a record by the identifier from your ERP or TMS (externalId).", "description": "Required scope: saved:read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "The record's identifier in your ERP or TMS.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedRecord" } }, "default": { "description": "Error (check error.code)" } } }, "put": { "operationId": "put_saved_shipments_externalId", "summary": "Creates or updates the record with that externalId (sync without duplicates).", "description": "Returns 201 when it creates the record and 200 when it updates it; repeating the same call leaves the same record. It is validated with the same rules as the website and appears immediately in Saved data («Datos habituales»). Places are referenced by their externalId (loadPlaceExternalId, unloadPlaceExternalId): sync them first. It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "The record's identifier in your ERP or TMS.", "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/SavedShipmentInput" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedRecord" } }, "default": { "description": "Error (check error.code)" } } }, "delete": { "operationId": "delete_saved_shipments_externalId", "summary": "Deletes the record with that externalId.", "description": "It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "The record's identifier in your ERP or TMS.", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SavedDeleted" } }, "default": { "description": "Error (check error.code)" } } } } } }