DeCA
Main website
API DeCA
API DeCA

Schemas

Download schema

CountryCode

string · pattern: ^[A-Z]{2}$

Two-letter country code; normalized to uppercase. This format does not verify membership of the ISO 3166-1 catalogue.

Example: ES

PositiveDecimal

string · pattern: ^(?!0+(?:\.0+)?$)(?:…

Positive decimal as a string, using a dot, without commas or scientific notation. Up to 15 integer digits and 6 decimal places. Responses strip trailing decimal zeros.

Example: 1850.000

WeightKilograms

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = string
type = number
Properties for Variant 1:
PositiveDecimal · pattern: ^(?!0+(?:\.0+)?$)(?:…

Positive decimal as a string, using a dot, without commas or scientific notation. Up to 15 integer digits and 6 decimal places. Responses strip trailing decimal zeros.

Example: 1850.000

Address

street
​string · minLength: 1 · maxLength: 255 · required

Street and building number.

postal_code
​string · minLength: 1 · maxLength: 255 · required

Postal code as text to preserve leading zeros.

city
​string · minLength: 1 · maxLength: 255 · required

Address locality.

country
​CountryCode · pattern: ^[A-Z]{2}$ · required

Two-letter country code; normalized to uppercase. This format does not verify membership of the ISO 3166-1 catalogue.

Example: ES

Shipper

Contractual shipper; may differ from the origin warehouse and the DeCA customer.
name
​string · minLength: 1 · maxLength: 255 · required

Name or legal business name.

tax_country
​CountryCode · pattern: ^[A-Z]{2}$ · required

Two-letter country code; normalized to uppercase. This format does not verify membership of the ISO 3166-1 catalogue.

Example: ES
tax_id
​string · minLength: 1 · maxLength: 32 · required

Tax ID normalized to uppercase without spaces or hyphens; length is checked after normalization. Spain validates the format and check character of DNI, NIE and entity NIF (CIF). Special K, L and M tax IDs are checked by format only: prefix, seven alphanumeric characters and a final letter. Other countries require alphanumeric format without tax checksum verification. Validation does not establish existence or tax registration.

​Address · required

Carrier

Carrier actually performing the transport, including subcontractors.
name
​string · minLength: 1 · maxLength: 255 · required

Name or legal business name.

tax_country
​CountryCode · pattern: ^[A-Z]{2}$ · required

Two-letter country code; normalized to uppercase. This format does not verify membership of the ISO 3166-1 catalogue.

Example: ES
tax_id
​string · minLength: 1 · maxLength: 32 · required

Tax ID normalized to uppercase without spaces or hyphens; length is checked after normalization. Spain validates the format and check character of DNI, NIE and entity NIF (CIF). Special K, L and M tax IDs are checked by format only: prefix, seven alphanumeric characters and a final letter. Other countries require alphanumeric format without tax checksum verification. Validation does not establish existence or tax registration.

​object

Optional carrier address. If supplied, all Address fields are required; article 6 does not require it as a minimum data item.

TransportLocation

place
​string · minLength: 1 · maxLength: 255 · required

Actual loading or unloading location, identifiable by site name or address. Together with city and country it must identify the location clearly; street and postal_code are optional. A consignee company's identity is not a mandatory minimum item.

city
​string · minLength: 1 · maxLength: 255 · required

Locality.

country
​string · enum · required

The initial scope covers domestic transport in Spain; it does not replace the international CMR.

Enum values:
ES
street
​string · minLength: 1 · maxLength: 255

Optional street and building number of the loading or unloading location to identify it precisely.

postal_code
​string · minLength: 1 · maxLength: 255

Optional postal code of the loading or unloading location, as text to preserve leading zeros.

AlternativeMeasure

Alternative measurement when weight is difficult to determine. Send either this measurement or weight, never both.
value
​PositiveDecimal · pattern: ^(?!0+(?:\.0+)?$)(?:… · required

Positive decimal as a string, using a dot, without commas or scientific notation. Up to 15 integer digits and 6 decimal places. Responses strip trailing decimal zeros.

Example: 1850.000
unit
​string · minLength: 1 · maxLength: 255 · required

Explicit measurement unit, up to 255 characters.

Example: palés

Goods

Nature and weight of the goods, or an alternative measurement where applicable. Send exactly one measurement.
description
​string · minLength: 1 · maxLength: 2000 · required

Description of the nature of the goods.

​WeightKilograms

Positive weight in kg, as a JSON number or a decimal string. Up to 15 integer digits and 6 decimal places. Responses normalise to a string and preserve precision; PDFs display up to 3 decimal places, using a decimal comma and dots for thousands. Use a decimal string to avoid losing precision with large values.

Example: 1850.5
​AlternativeMeasure

Alternative measurement when weight is difficult to determine. Send either this measurement or weight, never both.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · Required fields: weight_kg
type = object · Required fields: alternative_measure
Properties for Variant 1:
​WeightKilograms · required

Positive weight in kg, as a JSON number or a decimal string. Up to 15 integer digits and 6 decimal places. Responses normalise to a string and preserve precision; PDFs display up to 3 decimal places, using a decimal comma and dots for thousands. Use a decimal string to avoid losing precision with large values.

Example: 1850.5
description
​string · minLength: 1 · maxLength: 2000

Description of the nature of the goods.

​AlternativeMeasure

Alternative measurement when weight is difficult to determine. Send either this measurement or weight, never both.

Vehicle

Actual vehicle; if a trailer or semi-trailer is present, supply both trailer fields together.
country
​CountryCode · pattern: ^[A-Z]{2}$ · required

Two-letter country code; normalized to uppercase. This format does not verify membership of the ISO 3166-1 catalogue.

Example: ES
registration
​string · minLength: 1 · maxLength: 20 · required

Registration normalized to uppercase without spaces or hyphens. Spain accepts current ordinary registrations, former provincial registrations and the special E series. Other countries accept 3 to 20 alphanumeric characters.

Example: 4827 MNL
trailer_country
​CountryCode · pattern: ^[A-Z]{2}$

Two-letter country code; normalized to uppercase. This format does not verify membership of the ISO 3166-1 catalogue.

Example: ES
trailer_registration
​string · minLength: 1 · maxLength: 20

Trailer or semi-trailer registration, normalized like the tractor registration. Spain requires the R series. Other countries accept 3 to 20 alphanumeric characters.

Example: R 5832 BCD
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · Required fields: trailer_country, trailer_registration
type = object · Required fields: country, registration
Properties for Variant 1:
trailer_country
​CountryCode · pattern: ^[A-Z]{2}$ · required

Two-letter country code; normalized to uppercase. This format does not verify membership of the ISO 3166-1 catalogue.

Example: ES
trailer_registration
​string · minLength: 1 · maxLength: 20 · required

Trailer or semi-trailer registration, normalized like the tractor registration. Spain requires the R series. Other countries accept 3 to 20 alphanumeric characters.

Example: R 5832 BCD
country
​CountryCode · pattern: ^[A-Z]{2}$

Two-letter country code; normalized to uppercase. This format does not verify membership of the ISO 3166-1 catalogue.

Example: ES
registration
​string · minLength: 1 · maxLength: 20

Registration normalized to uppercase without spaces or hyphens. Spain accepts current ordinary registrations, former provincial registrations and the special E series. Other countries accept 3 to 20 alphanumeric characters.

Example: 4827 MNL

SpecialAuthorization

Special circulation authorization when required. Omit or send null if not applicable.
number
​string · minLength: 1 · maxLength: 255 · required

Authorization number or reference.

issuer
​string · minLength: 1 · maxLength: 255

Issuing authority, if supplied.

CreateDocumentRequest

transport_date
​string · date · required

Actual transport date in YYYY-MM-DD format; not the PDF creation timestamp.

​Shipper · required

Contractual shipper; may differ from the origin warehouse and the DeCA customer.

​Carrier · required

Carrier actually performing the transport, including subcontractors.

​TransportLocation · required
​TransportLocation · required
​Goods · required

Nature and weight of the goods, or an alternative measurement where applicable. Send exactly one measurement.

​Vehicle · required

Actual vehicle; if a trailer or semi-trailer is present, supply both trailer fields together.

reference
​string | null · minLength: 1 · maxLength: 120 · pattern: ^[A-Za-z0-9-]+(?![\s…

Optional customer reference, unique per organization and environment and printed on the PDF. Identifies retries and allows retrieval by reference. It is not released when the document is deleted.

​SpecialAuthorization

Special circulation authorization when required. Omit or send null if not applicable.

observations
​string | null · maxLength: 4000

Remarks requested by the parties for inclusion in the document.

​object | null

Optional JSON object, retained and returned without semantic changes. Not printed on the PDF. Maximum serialized size 16 KiB and nesting depth 8.

DocumentResult

uuid
​string · uuid · required

UUID of the issued document.

reference
​string | null · pattern: ^[A-Za-z0-9-]+(?![\s… · required

Customer reference or null.

created_at
​string · date-time · required

Original creation timestamp, in UTC.

url
​string · uri · required

Full HTTPS QR download URL including its secret. Do not log or publish it.

​object · required
pdf_download_url
​string · uri · required

Authenticated download URL; requires the owning credential's Bearer within 24 hours.

rectifies_uuid
​string | null · uuid · required

Corrected UUID, or null for an initial issue.

​CreateDocumentRequest · required
​object | null · required

The request's unchanged metadata; null if omitted.

document_locale
​string · enum · required

PDF language selected from the organization at issue time. Preserved in the result; changing the organization language does not modify existing documents. Does not change JSON fields or API error messages.

Enum values:
es
ca
gl
ca-valencia
eu
en
pt-pt
fr

DocumentSummary

uuid
​string · uuid · required
reference
​string | null · pattern: ^[A-Za-z0-9-]+(?![\s… · required
created_at
​string · date-time · required
transport_date
​string · date · required
rectifies_uuid
​string | null · uuid · required

DocumentList

​DocumentSummary[] · required
​object · required

ErrorResponse

​object[] · minItems: 1 · required

All independently detected errors; no request data, secrets or stack traces.

RectifyDocumentRequest

All corrected transport details. The previous document is identified in the URL. If reference is supplied, it must be a new reference for the corrective document.
transport_date
​string · date · required

Actual transport date in YYYY-MM-DD format; not the PDF creation timestamp.

​Shipper · required

Contractual shipper; may differ from the origin warehouse and the DeCA customer.

​Carrier · required

Carrier actually performing the transport, including subcontractors.

​TransportLocation · required
​TransportLocation · required
​Goods · required

Nature and weight of the goods, or an alternative measurement where applicable. Send exactly one measurement.

​Vehicle · required

Actual vehicle; if a trailer or semi-trailer is present, supply both trailer fields together.

reference
​string | null · minLength: 1 · maxLength: 120 · pattern: ^[A-Za-z0-9-]+(?![\s…

Optional new reference for the corrective document, unique per organization and environment. Do not reuse the reference of the document identified in the URL.

​SpecialAuthorization

Special circulation authorization when required. Omit or send null if not applicable.

observations
​string | null · maxLength: 4000

Remarks requested by the parties for inclusion in the document.

​object | null

Optional JSON object, retained and returned without semantic changes. Not printed on the PDF. Maximum serialized size 16 KiB and nesting depth 8.

DeleteDocumentRequest

reason
​string · minLength: 1 · maxLength: 2000 · required

Reason for the error detected while generating the document.

confirm_not_delivered
​boolean · required

Must be true to delete: confirms it has not been handed to the carrier or driver. false returns 409 DOCUMENT_ALREADY_DELIVERED.

confirm_not_used
​boolean · required

Must be true to delete: confirms it has not been used for transport. false returns 409 DOCUMENT_ALREADY_USED.

DocumentStatus

status
​string · enum · required

Document status. Does not include transport data, PDF, QR, metadata or dates.

Enum values:
active
deleted

DemoTokenResult

token
​string · pattern: ^sk_demo_[0-9a-f]{64… · required

You can request an sk_demo_ token without an account or a registered organisation. It lasts 24 hours from issuance and works only from the public IP that requested it. Changing network or IP requires another token.

expires_at
​string · date-time · required

Token expiry time in UTC. All its documents and links expire at this instant.

document_locale
​string · enum · required

Language of this token’s PDFs. Spanish by default.

Enum values:
es
ca
gl
ca-valencia
eu
en
pt-pt
fr

DemoDocumentResult

The demo adds demo: true, expires_at, qr_url (alias of url) and pdf_url (alias of pdf_download_url). document_locale is the language selected when requesting the token (es by default). Temporary data and PDFs are separate from the real archive and are not encrypted like real documents.
uuid
​string · uuid · required

UUID of the issued document.

reference
​string | null · pattern: ^[A-Za-z0-9-]+(?![\s… · required

Customer reference or null.

created_at
​string · date-time · required

Original creation timestamp, in UTC.

url
​string · uri · required

Full HTTPS QR download URL including its secret. Do not log or publish it.

​object · required
pdf_download_url
​string · uri · required

You can request an sk_demo_ token without an account or a registered organisation. It lasts 24 hours from issuance and works only from the public IP that requested it. Changing network or IP requires another token.

rectifies_uuid
​string | null · uuid · required

Corrected UUID, or null for an initial issue.

​CreateDocumentRequest · required
​object | null · required

The request's unchanged metadata; null if omitted.

document_locale
​string · enum · required

Language of this token’s PDFs. Spanish by default.

Enum values:
es
ca
gl
ca-valencia
eu
en
pt-pt
fr
demo
​boolean · enum · required

Demo only; always true. Absent from development and production results.

Enum values:
true
expires_at
​string · date-time · required

Token expiry time in UTC. All its documents and links expire at this instant.

qr_url
​string · uri · required

Demo only; alias of url.

pdf_url
​string · uri · required

Demo only; alias of pdf_download_url. Requires the demo token and its IP.