API para integrar el DeCA en tu programa
Emite el DeCA desde tu ERP, TMS o programa de gestión: envías los datos del transporte en una petición y recibes al momento el número, el PDF y la URL del QR. Sin formularios y sin cambiar de programa.
Crear cuenta y clave gratis Guía rápida
Un DeCA en una llamada
Validación de NIF, matrículas, pesos y fechas, número correlativo, PDF y QR con descarga directa, como exige la Resolución.
Todo el ciclo
Borradores, rectificaciones con el mismo QR, sustituciones, anulaciones y archivo, con el historial en el PDF.
Avisos en tu servidor
Webhooks firmados cuando se publica, rectifica o anula un DeCA, también los que se hacen en la web o en la app.
Hasta el 31 de enero de 2027, la API está incluida sin coste en todas las cuentas. Documentación abierta: especificación OpenAPI 3.1 y colección de Postman. ¿Dudas con la integración? Escríbenos a soporte@decaeasy.es.
Cómo funciona
- La empresa que emite los DeCA crea su cuenta en DecaEasy con su razón social y su NIF, y en Ajustes → API crea una clave.
- Tu programa envía los datos del transporte a
POST /api/v1/documents: quién carga, quién transporta, la fecha, el vehículo y los envíos. - DecaEasy valida los datos, numera el DeCA y genera el PDF. La respuesta trae el número y la
urldel QR. - El conductor lleva el QR (impreso o en el móvil). En un control, al leerlo se descarga el PDF vigente, sin contraseñas.
Si haces el programa para un cliente (empresa de software o integrador): el cliente crea su cuenta y su clave y te la da; tu programa guarda una clave por cliente. Cada clave es de una sola empresa, así que los DeCA salen a su nombre y cuentan en su plan. A ti no se te cobra nada. Si vas a integrar a varios clientes, cuéntanoslo.
Guía rápida: tu primer DeCA en 5 minutos
1. Crea la clave. Entra en Ajustes → API, ponle un nombre (p. ej. «ERP producción») y elige Lectura y escritura. Cópiala: solo se enseña una vez. En los ejemplos está en la variable $DECA_KEY.
2. Comprueba la conexión con GET /me: dice de qué empresa es la clave y cuántos DeCA quedan por API este mes.
curl https://decaeasy.es/api/v1/me \ -H "Authorization: Bearer $DECA_KEY"
{
"workspace": {
"id": 14,
"name": "Cerámicas Levante SL",
"nif": "B12345674"
},
"key": {
"name": "ERP producción",
"prefix": "deca_Ab3dE",
"scope": "write"
},
"plan": {
"name": "Flexible",
"free_until": null,
"api_monthly": 1000,
"api_used": 37,
"api_left": 963
}
}
3. Prepara los datos del transporte. Guarda esto en un archivo deca.json: data son los datos del DeCA (cada campo, más abajo), externalId es tu referencia y "publish": true lo publica al momento.
{
"externalId": "PED-48213",
"publish": true,
"data": {
"cargador": {
"nombre": "Cerámicas Levante SL",
"nif": "B12345674",
"domicilio": "Ctra. Onda km 3, 12200 Onda (Castellón)"
},
"transportista": {
"nombre": "Transportes Pérez SL",
"nif": "12345678Z"
},
"fecha_transporte": "2026-11-22",
"vehiculo": {
"matricula_tractora": "1234LMN",
"matricula_remolque": "R5678BCD"
},
"conductor": {
"nombre": "Juan García López",
"nif": "X1234567L"
},
"envios": [
{
"referencia": "ALB-9912",
"origen": {
"direccion": "Ctra. Onda km 3",
"cp": "12200",
"municipio": "Onda",
"provincia": "Castellón"
},
"destino": {
"direccion": "Av. del Puerto 10",
"cp": "46024",
"municipio": "Valencia",
"provincia": "Valencia"
},
"naturaleza": "Azulejos paletizados",
"peso_kg": 18500,
"bultos": "22 palés"
}
]
}
}
4. Valida los datos sin crear nada con POST /documents/validate. Responde siempre 200: mira valid, errors y warnings.
curl -X POST https://decaeasy.es/api/v1/documents/validate \
-H "Authorization: Bearer $DECA_KEY" \
-H "Content-Type: application/json" \
-d @deca.json
# Respuesta
{
"valid": true,
"needs_confirmation": false,
"errors": {},
"warnings": [],
"data": "…los datos tal como se guardarían…"
}
5. Publica con POST /documents. La cabecera Idempotency-Key (por ejemplo, tu número de pedido) permite reintentar sin crear un DeCA duplicado.
curl -X POST https://decaeasy.es/api/v1/documents \ -H "Authorization: Bearer $DECA_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: pedido-48213" \ -d @deca.json
6. Guarda el resultado: la respuesta (201) trae number y url. Dale esa URL o su QR al conductor (más abajo, qué hacer con la respuesta).
Autenticación y claves
- Cada petición lleva la clave en la cabecera
Authorization: Bearer deca_…. No hay usuario ni contraseña, y la API no usa cookies. - Hay claves de solo lectura (solo GET: consultar, listar y descargar PDF) y de lectura y escritura (todo).
- Cada clave es de una empresa (un espacio de trabajo). Si una cuenta tiene varias empresas, cada una tiene sus claves.
- La crea y la revoca la persona titular de la cuenta, en Ajustes → API. Una clave revocada deja de funcionar al momento (401).
- Guárdala como una contraseña: en el servidor, nunca en una app móvil ni en una página web. Si se filtra, revócala y crea otra.
Authorization: Bearer deca_Ab3dE… Content-Type: application/json
Crear y publicar un DeCA
POST /api/v1/documents con este cuerpo. Con "publish": true se publica en la misma petición; sin él, queda como borrador para publicarlo después.
| Campo | Obligatorio | Tipo | Para qué sirve |
|---|---|---|---|
data | Sí | objeto | Los datos del DeCA: ver los datos del DeCA, campo a campo. |
publish | No | true / false | true: se publica en la misma petición (número, PDF y QR). false: queda como borrador. Ejemplo: true |
externalId | No | texto | Tu referencia (pedido, expedición). Sirve para consultarlo con ext:{externalId} y sale en los webhooks. Ejemplo: "PED-48213" |
requestId | No | texto | Idempotencia (alternativa a la cabecera Idempotency-Key): repetido con la misma clave de API y los mismos datos, devuelve el documento ya creado (200); con publish: true, si era un borrador, lo publica. Con otros datos responde 422 con error "idempotency_mismatch" y no devuelve el documento anterior: para otro DeCA usa una clave nueva; para cambiar ese, PATCH /documents/{ref} (y POST /documents/{ref}/publish si es un borrador). Los datos se comparan con los del borrador tal como está o con los de la emisión (versión 1). En la respuesta 422, "document" dice cuál es (id, número y estado). Ejemplo: "pedido-48213" |
driverId | No | número entero | Conductor del directorio al que se asigna (alternativa a data.conductor.nif). Ejemplo: 31 |
confirmWarnings | No | true / false | true: publica aunque haya avisos (fecha pasada, matrícula extranjera…). Sin él, los avisos dan 422 con needs_confirmation. Ejemplo: true |
Cabecera opcional: Idempotency-Key (equivale a requestId, ver reintentos sin duplicados).
Respuesta: 201 Created
{
"id": 1842,
"number": "2026-014-000127",
"status": "published",
"archived": false,
"version": 1,
"external_id": "PED-48213",
"url": "https://decaeasy.es/d/Xk3pQ9vLm2RtY7wZ4nB8cD1e",
"pdf_url": "https://decaeasy.es/d/Xk3pQ9vLm2RtY7wZ4nB8cD1e/pdf",
"replaces_id": null,
"replaced_by_id": null,
"driver_id": 31,
"created_at": "2026-11-22T07:42:10.512Z",
"updated_at": "2026-11-22T07:42:10.512Z",
"published_at": "2026-11-22T07:42:10.512Z",
"sha256": "9f2c4e7a1b03d58e6c2f4a9b7d1e0c3a5f8b2d6e4c1a7f9b3d5e8c0a2f4b6d8e",
"data": {
"cargador": {
"nombre": "Cerámicas Levante SL",
"nif": "B12345674",
"domicilio": "Ctra. Onda km 3, 12200 Onda (Castellón)"
},
"transportista": {
"nombre": "Transportes Pérez SL",
"nif": "12345678Z"
},
"intermediario": {
"nombre": "",
"nif": ""
},
"fecha_transporte": "2026-11-22",
"vehiculo": {
"matricula_tractora": "1234LMN",
"matricula_remolque": "R5678BCD",
"autorizacion_especial": ""
},
"conductor": {
"nombre": "Juan García López",
"nif": "X1234567L"
},
"envios": [
{
"referencia": "ALB-9912",
"origen": {
"direccion": "Ctra. Onda km 3",
"cp": "12200",
"municipio": "Onda",
"provincia": "Castellón",
"pais": "España"
},
"destino": {
"direccion": "Av. del Puerto 10",
"cp": "46024",
"municipio": "Valencia",
"provincia": "Valencia",
"pais": "España"
},
"naturaleza": "Azulejos paletizados",
"peso_kg": "18500",
"bultos": "22 palés"
}
],
"observaciones": ""
}
}
Lo más importante de la respuesta:
| Campo | Qué es |
|---|---|
id | Identificador interno. |
number | Número del DeCA (año-empresa-correlativo). null mientras es borrador. |
status | draft: borrador (sin número ni QR). published: vigente. voided: anulado. superseded: sustituido por otro (ver replaced_by_id). Rectificar no cambia el estado: sube version. |
version | Versión vigente: 1 al emitirse, y una más con cada rectificación, anulación o sustitución. |
url | URL del QR: descarga directa del PDF vigente, sin credenciales. La página de consulta con el estado y el historial es {url}/info, y la imagen del QR, {url}/qr.png. |
pdf_url | PDF vigente ({url}/pdf); ?v=N da una versión anterior y ?download=1 lo descarga como archivo. Es público como el QR: si la empresa desactiva la descarga pública tras el fin del servicio (Ajustes), responde 410. Con la clave de API, GET /documents/{ref}/pdf lo da siempre. |
external_id | Tu referencia (externalId). Se consulta con ext:{externalId}; al sustituir, el nuevo DeCA la hereda. |
driver_id | Conductor asignado (directorio de conductores). |
sha256 | Huella SHA-256 del PDF vigente. |
data | Los datos guardados, normalizados: NIF y matrículas en mayúsculas y sin espacios, todos los campos presentes (vacíos si no tienen valor) y el peso como texto con punto decimal. |
El mismo ejemplo en tu lenguaje
data es el objeto con los datos del DeCA, como en deca.json.
Node.js (18 o posterior)
// data: los datos del DeCA, como en deca.json (ver «Los datos del DeCA, campo a campo»)
const res = await fetch('https://decaeasy.es/api/v1/documents', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.DECA_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'pedido-48213', // el mismo en cada reintento de este pedido
},
body: JSON.stringify({ externalId: 'PED-48213', publish: true, data }),
});
const deca = await res.json();
if (res.status === 201 || res.status === 200) {
console.log(deca.number, deca.url); // guarda los dos con tu pedido
} else if (res.status === 422 && deca.needs_confirmation) {
// Solo hay avisos (deca.warnings): enséñalos y, si se aceptan, reenvía con confirmWarnings: true
} else {
throw new Error(`${res.status} ${deca.error}: ${deca.message}`);
}Python (requests)
import os
import requests
r = requests.post(
'https://decaeasy.es/api/v1/documents',
headers={
'Authorization': f"Bearer {os.environ['DECA_KEY']}",
'Idempotency-Key': 'pedido-48213', # el mismo en cada reintento de este pedido
},
json={'externalId': 'PED-48213', 'publish': True, 'data': data},
timeout=30,
)
deca = r.json()
if r.status_code in (200, 201):
print(deca['number'], deca['url']) # guarda los dos con tu pedido
elif r.status_code == 422 and deca.get('needs_confirmation'):
pass # solo hay avisos (deca['warnings']): si se aceptan, reenvía con 'confirmWarnings': True
else:
raise RuntimeError(f"{r.status_code} {deca['error']}: {deca['message']}")PHP (cURL)
<?php
$ch = curl_init('https://decaeasy.es/api/v1/documents');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('DECA_KEY'),
'Content-Type: application/json',
'Idempotency-Key: pedido-48213', // el mismo en cada reintento de este pedido
],
CURLOPT_POSTFIELDS => json_encode(['externalId' => 'PED-48213', 'publish' => true, 'data' => $data]),
]);
$deca = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status === 201 || $status === 200) {
echo $deca['number'], ' ', $deca['url']; // guarda los dos con tu pedido
} elseif ($status === 422 && !empty($deca['needs_confirmation'])) {
// Solo hay avisos ($deca['warnings']): si se aceptan, reenvía con 'confirmWarnings' => true
} else {
throw new Exception("$status {$deca['error']}: {$deca['message']}");
}C# (.NET 6 o posterior)
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("DECA_KEY"));
var req = new HttpRequestMessage(HttpMethod.Post, "https://decaeasy.es/api/v1/documents")
{
Content = JsonContent.Create(new { externalId = "PED-48213", publish = true, data }),
};
req.Headers.Add("Idempotency-Key", "pedido-48213"); // el mismo en cada reintento de este pedido
var res = await http.SendAsync(req);
var deca = await res.Content.ReadFromJsonAsync<JsonElement>();
if (res.IsSuccessStatusCode)
Console.WriteLine($"{deca.GetProperty("number")} {deca.GetProperty("url")}");
else if ((int)res.StatusCode == 422 && deca.TryGetProperty("needs_confirmation", out var nc) && nc.GetBoolean())
{ /* Solo hay avisos: si se aceptan, reenvía con confirmWarnings = true */ }
else
throw new Exception($"{(int)res.StatusCode} {deca.GetProperty("error")}: {deca.GetProperty("message")}");Borradores
Sin "publish": true, el DeCA queda como borrador: no tiene número, PDF ni QR, y los datos pueden estar incompletos. Sirve si alguien tiene que revisarlo en la web o en la app antes de publicarlo. Se completa con PATCH /documents/{ref} y se publica con POST /documents/{ref}/publish; un borrador se descarta con POST /documents/{ref}/void.
curl -X POST https://decaeasy.es/api/v1/documents/1842/publish \
-H "Authorization: Bearer $DECA_KEY" \
-H "Content-Type: application/json" \
-d '{}'
Los datos del DeCA, campo a campo
Son los datos del art. 6 de la Orden FOM/2861/2012. Los obligatorios lo son para publicar; un borrador se puede guardar incompleto. Los campos opcionales se pueden omitir. En la respuesta vuelven todos, vacíos ("") si no tienen valor.
Normalización. DecaEasy quita los espacios de más, pasa a mayúsculas los NIF y las matrículas (sin espacios, puntos ni guiones) y comprueba la letra de control de NIF, CIF y NIE. Los errores vienen por campo, con la ruta como clave: "envios.0.peso_kg" es el peso del primer envío.
Cargador contractual cargador
Cargador contractual: quien contrata el transporte directamente con el transportista efectivo. Suele ser quien envía la mercancía; si el transporte lo contrata una agencia, un operador logístico o un transitario, esa empresa.
| Campo | Obligatorio | Tipo | Para qué sirve |
|---|---|---|---|
cargador.nombre | Sí | texto | Razón social, o nombre y apellidos. Hasta 200 caracteres. Ejemplo: "Cerámicas Levante SL" |
cargador.nif | Sí | texto | NIF, CIF o NIE español (con o sin el prefijo ES) o NIF-IVA de un país de la UE, el EEE o Suiza (empresas que hacen cabotaje). Se guarda en mayúsculas y sin espacios, puntos ni guiones. Se comprueba la letra de control; uno extranjero da un aviso (no se puede verificar). Hasta 30 caracteres. Ejemplo: "B12345674" |
cargador.domicilio | Sí | texto | Domicilio del cargador contractual, en una línea. Hasta 300 caracteres. Ejemplo: "Ctra. Onda km 3, 12200 Onda (Castellón)" |
Transportista efectivo transportista
Transportista efectivo: quien hace el transporte con sus vehículos.
| Campo | Obligatorio | Tipo | Para qué sirve |
|---|---|---|---|
transportista.nombre | Sí | texto | Razón social, o nombre y apellidos. Hasta 200 caracteres. Ejemplo: "Transportes Pérez SL" |
transportista.nif | Sí | texto | NIF, CIF o NIE español (con o sin el prefijo ES) o NIF-IVA de un país de la UE, el EEE o Suiza (empresas que hacen cabotaje). Se guarda en mayúsculas y sin espacios, puntos ni guiones. Se comprueba la letra de control; uno extranjero da un aviso (no se puede verificar). Hasta 30 caracteres. Ejemplo: "12345678Z" |
Otra empresa que interviene intermediario (opcional)
Opcional y solo informativo («Otra empresa que interviene»): una empresa que aparece en el transporte sin contratarlo directamente con el transportista. Una agencia que contrata el transporte va en cargador, no aquí.
| Campo | Obligatorio | Tipo | Para qué sirve |
|---|---|---|---|
intermediario.nombre | No | texto | Razón social. Si se envía, intermediario.nif es obligatorio. Hasta 200 caracteres. |
intermediario.nif | No | texto | NIF, CIF o NIE español (con o sin el prefijo ES) o NIF-IVA de un país de la UE, el EEE o Suiza (empresas que hacen cabotaje). Se guarda en mayúsculas y sin espacios, puntos ni guiones. Se comprueba la letra de control; uno extranjero da un aviso (no se puede verificar). Hasta 30 caracteres. |
Fecha del transporte fecha_transporte
| Campo | Obligatorio | Tipo | Para qué sirve |
|---|---|---|---|
fecha_transporte | Sí | fecha AAAA-MM-DD | Día del transporte (AAAA-MM-DD, hora de España peninsular). Si es anterior a hoy o está a más de 30 días vista, da un aviso; a más de un año vista, un error. Ejemplo: "2026-11-22" |
Vehículo vehiculo
Vehículo que hace el transporte.
| Campo | Obligatorio | Tipo | Para qué sirve |
|---|---|---|---|
vehiculo.matricula_tractora | Sí | texto | Matrícula del vehículo rígido o de la tractora, de 4 a 12 caracteres. Se guarda en mayúsculas y sin espacios ni guiones. Si no sigue el formato español, da un aviso (vale si es extranjera). Hasta 30 caracteres. Ejemplo: "1234LMN" |
vehiculo.matricula_remolque | No | texto | Matrícula del remolque o semirremolque, si lleva uno. En un vehículo articulado es obligatoria (art. 6.g de la Orden FOM/2861/2012). Hasta 30 caracteres. Ejemplo: "R5678BCD" |
vehiculo.autorizacion_especial | No | texto | Autorización especial de circulación, si el transporte la necesita. Hasta 200 caracteres. |
Conductor conductor (opcional)
Opcional. Si el NIF coincide con un conductor del directorio de la empresa (o se envía driverId), el DeCA se le asigna: lo ve en su portal y en la app.
| Campo | Obligatorio | Tipo | Para qué sirve |
|---|---|---|---|
conductor.nombre | No | texto | Nombre y apellidos. Hasta 200 caracteres. Ejemplo: "Juan García López" |
conductor.nif | No | texto | DNI o NIE del conductor. Hasta 30 caracteres. Ejemplo: "X1234567L" |
Envíos envios
Envíos del DeCA, de 1 a 100: cada par origen → destino con su mercancía. Varios envíos van en un mismo DeCA solo si comparten cargador contractual y transportista efectivo.
| Campo | Obligatorio | Tipo | Para qué sirve |
|---|---|---|---|
envios[].referencia | No | texto | Tu referencia del envío (albarán, pedido o expedición). Opcional. Hasta 80 caracteres. Ejemplo: "ALB-9912" |
envios[].origen.direccion | Sí | texto | Calle y número, polígono o punto kilométrico. Hasta 300 caracteres. Ejemplo: "Ctra. Onda km 3" |
envios[].origen.cp | No | texto | Código postal. Opcional. Hasta 12 caracteres. Ejemplo: "12200" |
envios[].origen.municipio | Sí | texto | Municipio. Hasta 120 caracteres. Ejemplo: "Onda" |
envios[].origen.provincia | No | texto | Provincia. Opcional. Hasta 120 caracteres. Ejemplo: "Castellón" |
envios[].origen.pais | No | texto | País. Si se omite, "España". Hasta 60 caracteres. |
envios[].destino.direccion | Sí | texto | Calle y número, polígono o punto kilométrico. Hasta 300 caracteres. Ejemplo: "Av. del Puerto 10" |
envios[].destino.cp | No | texto | Código postal. Opcional. Hasta 12 caracteres. Ejemplo: "46024" |
envios[].destino.municipio | Sí | texto | Municipio. Hasta 120 caracteres. Ejemplo: "Valencia" |
envios[].destino.provincia | No | texto | Provincia. Opcional. Hasta 120 caracteres. Ejemplo: "Valencia" |
envios[].destino.pais | No | texto | País. Si se omite, "España". Hasta 60 caracteres. |
envios[].naturaleza | Sí | texto | Naturaleza de la mercancía, p. ej. "Azulejos paletizados". Hasta 300 caracteres. Ejemplo: "Azulejos paletizados" |
envios[].peso_kg | Sí | número (o texto) | Kilogramos, mayor que 0. Mejor como número JSON (12.5). En texto, "12,5" y "12.5" son decimales, pero "12.345" es 12 345 kg (punto de miles, como en "1.250,5"); "1,250.5" da error. En la respuesta vuelve como texto con punto decimal ("18500", "1250.5"). Si el total del DeCA pasa de 60 000 kg, da un aviso. Ejemplo: 18500 |
envios[].peso_estimado | No | true / false | true si no se puede saber el peso exacto y peso_kg es una estimación (la Orden permite otra magnitud para determinarlo). Sin estimar, se omite (en la respuesta no aparece). |
envios[].bultos | No | texto | Número y tipo de bultos, en texto libre (p. ej. "22 palés"). Opcional. Hasta 60 caracteres. Ejemplo: "22 palés" |
envios[].peso_calculo | No | texto | Cómo se ha calculado el peso estimado, p. ej. "por palés: 22 × 800 kg" o "capacidad del vehículo". Sale en el PDF junto al peso: "9.000 kg (estimado: por palés: 22 × 800 kg)". Opcional: con peso_estimado: true y sin peso_calculo (o vacío), se guarda "Estimado por el cargador". Solo con peso_estimado: true; si no, se ignora. Hasta 120 caracteres. |
Observaciones observaciones (opcional)
| Campo | Obligatorio | Tipo | Para qué sirve |
|---|---|---|---|
observaciones | No | texto | Texto libre que sale en el PDF. Admite saltos de línea (hasta 25 líneas). Hasta 2000 caracteres. |
Peso estimado
Si no se puede saber el peso exacto (áridos, graneles, mudanzas…), la Orden permite estimarlo. Envía el peso estimado en peso_kg, "peso_estimado": true y, si quieres, cómo lo has calculado:
{
"origen": {
"direccion": "Ctra. Onda km 3",
"cp": "12200",
"municipio": "Onda",
"provincia": "Castellón"
},
"destino": {
"direccion": "Av. del Puerto 10",
"cp": "46024",
"municipio": "Valencia",
"provincia": "Valencia"
},
"naturaleza": "Grava 20/40",
"peso_kg": 24000,
"peso_estimado": true,
"peso_calculo": "capacidad de la caja: 16 m³ × 1,5 t/m³"
}
Qué hacer con la respuesta: el QR y el conductor
La url de la respuesta es la del QR. Al abrirla se descarga el PDF de la versión vigente, sin contraseñas ni páginas intermedias (Resolución de 5 de junio de 2026). En un control, el conductor tiene que poder enseñar el DeCA: el QR impreso o el PDF en el móvil.
| Dirección | Qué da |
|---|---|
https://decaeasy.es/d/Xk3pQ9vLm2RtY7wZ4nB8cD1e | El PDF vigente (es la URL que va en el QR). |
https://decaeasy.es/d/Xk3pQ9vLm2RtY7wZ4nB8cD1e/qr.png | La imagen del QR (PNG de 360 px), para imprimirla en tu albarán u hoja de ruta. |
https://decaeasy.es/d/Xk3pQ9vLm2RtY7wZ4nB8cD1e/info | Una página con el estado del DeCA (vigente, rectificado, anulado o sustituido) y su historial. |
https://decaeasy.es/d/Xk3pQ9vLm2RtY7wZ4nB8cD1e/pdf?v=1 | Una versión anterior del PDF; con ?download=1, se descarga como archivo. |
Para que el conductor lo tenga:
- Imprime el QR en el albarán, la carta de porte o la hoja de ruta que ya saca tu programa.
- Mándale la URL por SMS, WhatsApp o email desde tu programa.
- Asígnaselo: si el conductor está en el directorio de la empresa (con su DNI), envía su
driverIdo su NIF endata.conductor.nif. Lo verá en su portal y en la app de DecaEasy, con el QR listo para enseñar.
Si cambia algo del transporte, rectifica el DeCA: el QR sigue siendo el mismo y al leerlo sale la versión nueva. Si lo sustituyes, hay un QR nuevo que hay que darle al conductor.
Avisos y errores de validación
Los errores impiden publicar: faltan datos obligatorios o no son válidos. La respuesta es 422 con errors por campo:
{
"error": "validation",
"message": "Hay datos obligatorios incompletos o no válidos.",
"errors": {
"cargador.nif": "NIF/CIF/NIE no válido",
"envios.0.peso_kg": "Obligatorio"
},
"warnings": [],
"needs_confirmation": false
}
Los avisos no lo impiden, pero hay que confirmarlos: fecha anterior a hoy o a más de un mes vista, matrícula o NIF extranjeros, el mismo NIF de cargador y transportista, una tractora sin semirremolque o más de 60 000 kg en total. Sin confirmar, la respuesta es 422 con needs_confirmation: true:
{
"error": "validation",
"message": "Revisa los avisos antes de publicar.",
"errors": {},
"warnings": [
"La fecha de transporte es anterior a hoy. El DeCA debe emitirse antes del inicio del servicio."
],
"needs_confirmation": true
}
Enseña los avisos a la persona usuaria y, si los acepta, reenvía lo mismo con "confirmWarnings": true. Si tu programa ya los revisa, puedes enviarlo siempre. Los mensajes están en español y se pueden enseñar tal cual.
Rectificar, sustituir o anular
| Qué pasa | Qué usar | El QR |
|---|---|---|
| Cambia algún dato del mismo transporte (otro camión, otro peso, otra fecha cercana…) | Rectificar: PATCH /documents/{ref} con reason | El mismo. Sale la versión nueva, con los datos anteriores marcados como no válidos. |
| El cambio es grande, ya pasó el plazo para rectificar o es otro transporte | Sustituir: POST /documents/{ref}/replace | Uno nuevo (otro número). El anterior queda como sustituido, con un enlace al nuevo. |
| El transporte no se hace | Anular: POST /documents/{ref}/void | El mismo, con el PDF marcado como ANULADO. |
En data basta con enviar lo que cambia: los bloques (cargador, vehiculo…) se fusionan campo a campo y un campo se vacía enviándolo como "". Si envías envios, va la lista completa.
Rectificar (cambia el semirremolque):
curl -X PATCH https://decaeasy.es/api/v1/documents/ext:PED-48213 \
-H "Authorization: Bearer $DECA_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Cambio de semirremolque",
"data": {
"vehiculo": {
"matricula_remolque": "R9012FGH"
}
}
}'
Se puede rectificar hasta 7 días naturales después del fin del servicio (o los días de descarga pública de la empresa, si son más), como mucho 20 veces y sin mover la fecha más de 7 días. Fuera de eso, la respuesta es 422 (correction_closed si ha pasado el plazo) y hay que sustituirlo.
Sustituir (cambia el destino; la respuesta es el DeCA nuevo, con su url):
curl -X POST https://decaeasy.es/api/v1/documents/ext:PED-48213/replace \
-H "Authorization: Bearer $DECA_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Cambio de destino",
"data": {
"envios": [
{
"referencia": "ALB-9912",
"origen": {
"direccion": "Ctra. Onda km 3",
"cp": "12200",
"municipio": "Onda",
"provincia": "Castellón"
},
"destino": {
"direccion": "C/ Industria 4",
"municipio": "Sagunto"
},
"naturaleza": "Azulejos paletizados",
"peso_kg": 18500,
"bultos": "22 palés"
}
]
}
}'
Anular:
curl -X POST https://decaeasy.es/api/v1/documents/ext:PED-48213/void \
-H "Authorization: Bearer $DECA_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "El transporte no se ha hecho"
}'
Archivar solo lo oculta de la lista (no cambia el DeCA): POST /documents/{ref}/archive con {"archived": true} o false.
Consultar y buscar
{ref} es el id, el número del DeCA o tu referencia con el prefijo ext:. Con ext:, si hay varios con la misma referencia, da el más reciente (al sustituir, el nuevo hereda la referencia).
curl https://decaeasy.es/api/v1/documents/ext:PED-48213 \ -H "Authorization: Bearer $DECA_KEY" curl https://decaeasy.es/api/v1/documents/2026-014-000127 \ -H "Authorization: Bearer $DECA_KEY" # El PDF con tu clave (también si la empresa desactivó la descarga pública) curl https://decaeasy.es/api/v1/documents/1842/pdf \ -H "Authorization: Bearer $DECA_KEY" -o DeCA.pdf
El listado admite filtros y paginación:
curl https://decaeasy.es/api/v1/documents?status=published&from=2026-10-01&to=2026-10-31&limit=100&offset=0 \ -H "Authorization: Bearer $DECA_KEY"
| Parámetro | Para qué sirve |
|---|---|
q | Busca en número, empresas, NIF, matrículas, conductor, municipios, referencias y mercancía. |
status | Uno de: draft, published, voided, superseded. |
from | Fecha de transporte desde (incluida). |
to | Fecha de transporte hasta (incluida). |
externalId | Tu referencia exacta. |
archived | Uno de: true, false, all. Por defecto, false. |
limit | Por defecto, 100. Máximo 1000. |
offset | Por defecto, 0. |
Responde {"total": 128, "items": [ … ]}, del más reciente al más antiguo.
Reintentos sin duplicados (idempotencia)
Si una petición se corta y no sabes si llegó, repítela con la misma cabecera Idempotency-Key (o requestId en el cuerpo). Usa un valor único por DeCA, por ejemplo el número de tu pedido.
- Con la misma clave y los mismos datos, recibes el DeCA que ya se creó, con 200 en lugar de 201. Si se quedó como borrador a medio publicar, se publica.
- Con la misma clave y otros datos, la respuesta es 422
idempotency_mismatchydocumentdice qué DeCA tiene ya esa clave. Para cambiarlo, usaPATCH; para otro DeCA, una clave nueva. - Si esa
Idempotency-Keyya la usó otra clave de API u otra persona de la empresa, la respuesta es 409.
Webhooks
DecaEasy avisa a tu servidor cuando cambia un DeCA de la empresa, también los que se hacen en la web, en la app o con una importación. Así tu programa se entera sin consultar cada poco.
Cómo se configuran: en Ajustes → Webhooks, pon la URL de tu servidor (HTTPS, pública), elige los eventos y guarda el secreto de firma (whsec_…), que solo se enseña una vez. Con «Enviar prueba» llega un evento ping.
| Evento | Cuándo llega | Qué trae en data |
|---|---|---|
document.draft_created | Se crea un borrador (en la web, en la app, con una importación o por la API). | El documento. |
document.published | Se publica un DeCA: ya tiene número, PDF y QR. | El documento. |
document.corrected | Se rectifica (mismo QR, versión nueva). | El documento, con reason y changes (cada dato: antes y después). |
document.replaced | Se sustituye por un DeCA nuevo (otro número y otro QR). | old y new (los dos documentos) y reason. |
document.voided | Se anula. | El documento, con reason. |
document.archived | Se archiva. | El documento. |
ping | Pulsas «Enviar prueba» en Ajustes → Webhooks. | workspace (nombre de la empresa). |
Llega un POST con JSON y estas cabeceras:
POST /webhooks/deca HTTP/1.1 Content-Type: application/json User-Agent: DeCA-Webhooks/1.0 X-DeCA-Event: document.published X-DeCA-Signature: t=1760600530,v1=5f3a9c…
{
"id": "6f1c2a9e-3b7d-4e58-9a0c-2d4b6e8f1a3c",
"type": "document.published",
"created_at": "2026-11-22T07:42:10.512Z",
"data": {
"id": 1842,
"number": "2026-014-000127",
"status": "published",
"archived": false,
"version": 1,
"external_id": "PED-48213",
"url": "https://decaeasy.es/d/Xk3pQ9vLm2RtY7wZ4nB8cD1e",
"pdf_url": "https://decaeasy.es/d/Xk3pQ9vLm2RtY7wZ4nB8cD1e/pdf",
"replaces_id": null,
"replaced_by_id": null,
"driver_id": 31,
"created_at": "2026-11-22T07:42:10.512Z",
"updated_at": "2026-11-22T07:42:10.512Z",
"published_at": "2026-11-22T07:42:10.512Z",
"sha256": "9f2c4e7a1b03d58e6c2f4a9b7d1e0c3a5f8b2d6e4c1a7f9b3d5e8c0a2f4b6d8e",
"data": {
"cargador": {
"nombre": "Cerámicas Levante SL",
"nif": "B12345674",
"domicilio": "Ctra. Onda km 3, 12200 Onda (Castellón)"
},
"transportista": {
"nombre": "Transportes Pérez SL",
"nif": "12345678Z"
},
"intermediario": {
"nombre": "",
"nif": ""
},
"fecha_transporte": "2026-11-22",
"vehiculo": {
"matricula_tractora": "1234LMN",
"matricula_remolque": "R5678BCD",
"autorizacion_especial": ""
},
"conductor": {
"nombre": "Juan García López",
"nif": "X1234567L"
},
"envios": [
{
"referencia": "ALB-9912",
"origen": {
"direccion": "Ctra. Onda km 3",
"cp": "12200",
"municipio": "Onda",
"provincia": "Castellón",
"pais": "España"
},
"destino": {
"direccion": "Av. del Puerto 10",
"cp": "46024",
"municipio": "Valencia",
"provincia": "Valencia",
"pais": "España"
},
"naturaleza": "Azulejos paletizados",
"peso_kg": "18500",
"bultos": "22 palés"
}
],
"observaciones": ""
}
}
}
Comprobar la firma
v1 es el HMAC-SHA256, en hexadecimal, de "{t}.{cuerpo}" con tu secreto, donde t es la hora del envío (segundos Unix) y el cuerpo es tal cual llega, sin interpretarlo. Rechaza el aviso si la firma no coincide o si t es de hace más de 5 minutos.
Node.js (Express)
const crypto = require('crypto');
// express.raw: hace falta el cuerpo tal cual llega, sin interpretar, para comprobar la firma
app.post('/webhooks/deca', express.raw({ type: 'application/json' }), (req, res) => {
const sig = Object.fromEntries((req.get('X-DeCA-Signature') || '').split(',').map((p) => p.split('=')));
const expected = crypto.createHmac('sha256', process.env.DECA_WEBHOOK_SECRET)
.update(`${sig.t}.${req.body}`).digest('hex');
const valid = typeof sig.v1 === 'string' && sig.v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(sig.v1), Buffer.from(expected));
if (!valid || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return res.sendStatus(400);
const event = JSON.parse(req.body);
// event.id es único: si ya lo has procesado (un reintento), contesta 200 y no hagas nada más
res.sendStatus(200); // contesta enseguida; el trabajo largo, después
});PHP
<?php
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_DECA_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('DECA_WEBHOOK_SECRET'));
if (!hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) ($sig['t'] ?? 0)) > 300) {
http_response_code(400);
exit;
}
$event = json_decode($body, true);
// $event['id'] es único: si ya lo has procesado (un reintento), contesta 200 y no hagas nada más
http_response_code(200);Python (Flask)
import hashlib, hmac, os, time
from flask import abort, request
@app.post('/webhooks/deca')
def deca_webhook():
body = request.get_data() # el cuerpo tal cual llega
header = request.headers.get('X-DeCA-Signature', '')
sig = dict(p.split('=', 1) for p in header.split(',') if '=' in p)
expected = hmac.new(os.environ['DECA_WEBHOOK_SECRET'].encode(),
f"{sig.get('t', '')}.".encode() + body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, sig.get('v1', '')) or abs(time.time() - int(sig.get('t', 0))) > 300:
abort(400)
event = request.get_json()
# event['id'] es único: si ya lo has procesado (un reintento), contesta 200 y no hagas nada más
return '', 200Reintentos y buenas prácticas
- Contesta con un código 2xx en menos de 5 segundos. Cualquier otro código (también una redirección) o no contestar en 5 segundos cuenta como fallo.
- Si falla, se reintenta hasta 6 veces en total, con esperas de 1, 2, 4, 8 y 16 minutos. El historial de envíos está en Ajustes → Webhooks.
- Los avisos de cada empresa se envían de uno en uno, por orden, pero uno que se reintenta puede llegar después de otros más nuevos: ordénalos por
created_ato consulta el DeCA. Un reintento trae el mismoid: guárdalo para no procesar dos veces el mismo aviso. - Haz el trabajo largo después de contestar, y si dudas de un dato, consulta el DeCA con
GET /documents/{ref}.
Directorios
Las empresas, vehículos, lugares y conductores guardados de la empresa. Se rellenan solos con cada DeCA publicado, y se pueden consultar y añadir por la API:
GET /api/v1/companies POST /api/v1/companies GET /api/v1/vehicles POST /api/v1/vehicles GET /api/v1/addresses POST /api/v1/addresses GET /api/v1/drivers POST /api/v1/drivers
Para asignar DeCA a un conductor, dalo de alta con su DNI o NIE; su id es el driverId:
curl -X POST https://decaeasy.es/api/v1/drivers \
-H "Authorization: Bearer $DECA_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Juan García López",
"nif": "X1234567L",
"phone": "600123456"
}'
Los campos de cada tipo están en la especificación OpenAPI (esquemas Company, Vehicle, Address y Driver).
Códigos de error
Todos los errores son JSON con error (un código fijo, para tu programa) y message (en español, para la persona usuaria).
| HTTP | error | Qué significa | Qué hacer |
|---|---|---|---|
| 400 | invalid_json, bad_request | El cuerpo no es JSON válido o la petición está mal formada. | Revisa el JSON que envías. |
| 401 | unauthorized | Falta la clave, no es válida o está revocada. | Envía Authorization: Bearer deca_… con una clave activa. |
| 402 | plan | El plan no incluye la API, o ya se han emitido por API los DeCA que incluye este mes. | Cambia de plan. Rectificar y anular siguen funcionando. |
| 403 | forbidden, account_suspended | Clave de solo lectura en una petición que no es GET, o cuenta suspendida. | Usa una clave de lectura y escritura, o escribe a soporte. |
| 404 | not_found | No hay ningún DeCA con esa referencia en esta empresa, o la ruta no existe. | Revisa el {ref} y la ruta. |
| 409 | conflict | El estado del DeCA no permite la operación (p. ej., ya está publicado o anulado) o hay otra petición en curso sobre el mismo DeCA. | Consulta el DeCA (GET) antes de reintentar. |
| 413 | too_large | La petición pasa de 1 MB. | Envía menos envíos por DeCA. |
| 422 | validation | Hay datos que faltan o no son válidos (errors), o avisos sin confirmar (needs_confirmation: true). | Corrige los campos de errors, o reenvía con "confirmWarnings": true. |
| 422 | idempotency_mismatch | Esa Idempotency-Key ya se usó con otros datos. | Para otro DeCA, usa una clave nueva. document dice cuál tiene ya esa clave. |
| 422 | correction_closed | Ya pasó el plazo para rectificar el DeCA. | Sustitúyelo (POST /documents/{ref}/replace). |
| 429 | rate_limited | Más de 120 peticiones por minuto desde la misma IP. | Espera los segundos de la cabecera Retry-After. |
| 500, 502, 503 | — | Error de nuestro lado o mantenimiento. | Reintenta pasado un rato con la misma Idempotency-Key. |
Límites
| Límite | Valor |
|---|---|
| Peticiones | 120 por minuto por IP. Si se pasa, 429 con Retry-After. |
| DeCA emitidos por API | Los que incluye el plan al mes (hora de Madrid): 1000 en Flexible y 5000 en Pro. Solo cuenta la emisión: rectificar, anular y consultar no cuentan; sustituir cuenta como un DeCA nuevo. GET /me dice cuántos quedan. |
| Tamaño | 1 MB por petición, de 1 a 100 envíos por DeCA y la longitud de cada campo (en la tabla de campos). |
| Listados | Hasta 1000 DeCA por página (limit y offset). |
| Rectificaciones | Hasta 20 por DeCA, hasta 7 días naturales tras el fin del servicio y sin mover la fecha más de 7 días. Si no, se sustituye. |
| Webhooks | 5 por empresa, 5 segundos de espera por envío y 6 intentos. |
| Directorios | 5000 fichas de cada tipo por empresa. |
Probar la integración
- Crea una cuenta de pruebas con los datos de tu empresa (hasta el 31 de enero de 2027, con la API incluida) y una clave.
- Prueba la conexión con
GET /mey tus datos conPOST /documents/validate: no crea nada ni gasta número. - Prueba el ciclo completo con borradores y algún DeCA publicado: publica, rectifica, sustituye y anula. Los DeCA de prueba se anulan al terminar.
- Configura un webhook y pulsa «Enviar prueba» para comprobar la firma.
- Cuando funcione, el cliente crea su clave en su cuenta y la pones en tu programa.
Con la colección de Postman tienes todas las peticiones listas: impórtala y pon tu clave en la variable apiKey. La especificación OpenAPI sirve para generar el cliente en tu lenguaje (openapi-generator, NSwag, Kiota…).
Versiones y cambios
La API es la versión 1 (/api/v1). Dentro de la versión 1 no se quitan ni se cambian campos ni rutas: solo se añaden. Tu programa debe ignorar los campos que no conozca. Si algún día hace falta un cambio incompatible, será en /api/v2, con aviso y conviviendo con la v1.
- 1.1.0 (16 de octubre de 2026):
GET /mepara comprobar la clave,POST /documents/validatepara validar sin crear nada,needs_confirmationen los 422 y la descripción de cada campo en la especificación. - 1.0.0 (5 de octubre de 2026): primera versión.
Preguntas frecuentes
¿Hay un entorno de pruebas?
No hace falta uno aparte. POST /documents/validate comprueba los datos como al publicar, sin crear nada ni gastar número, y los borradores (sin "publish": true) no tienen PDF ni QR. Para probar de principio a fin, abre una cuenta de pruebas con los datos de tu empresa: los DeCA que publiques ahí se pueden anular después.
¿Quién tiene que crear la cuenta y la clave?
La empresa en cuyo nombre se emiten los DeCA (el cargador contractual o el transportista efectivo, que pueden acordar quién lo emite). Si haces el programa para un cliente, el cliente crea su cuenta y su clave y te la da. Cada clave es de una sola empresa: los DeCA salen a su nombre y cuentan en su plan.
¿Cuánto cuesta?
Hasta el 31 de enero de 2027, la API está incluida sin coste en todas las cuentas. Después va en los planes de pago (Flexible y Pro): ver precios. A quien desarrolla la integración no se le cobra nada.
¿Puedo poner el QR en mi propio albarán u hoja de ruta?
Sí. La imagen del QR está en {url}/qr.png, o puedes generar tú el QR con la url de la respuesta. Tiene que llevar a esa URL tal cual: es la que descarga el PDF.
¿Qué pasa si se corta la conexión a mitad de una petición?
Repite la petición con la misma cabecera Idempotency-Key: si el DeCA ya se creó, recibes ese mismo (200) en lugar de uno duplicado.
¿Puedo guardar el PDF en mi sistema?
Sí: GET /documents/{ref}/pdf lo da con tu clave, y sha256 es su huella para comprobar que no ha cambiado. El que vale en un control es siempre el que da el QR, que tiene la versión vigente.
¿Qué pasa con los DeCA que se hacen en la web o en la app?
Son de la misma empresa: los ves por la API (GET /documents) y, si configuras webhooks, recibes también sus avisos. Lo que se emite por API también se ve en la web y en la app de DecaEasy.