DecaEasy

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

  1. 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.
  2. 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.
  3. DecaEasy valida los datos, numera el DeCA y genera el PDF. La respuesta trae el número y la url del QR.
  4. 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.

CampoObligatorioTipoPara qué sirve
dataSíobjetoLos datos del DeCA: ver los datos del DeCA, campo a campo.
publishNotrue / falsetrue: se publica en la misma petición (número, PDF y QR). false: queda como borrador.
Ejemplo: true
externalIdNotextoTu referencia (pedido, expedición). Sirve para consultarlo con ext:{externalId} y sale en los webhooks.
Ejemplo: "PED-48213"
requestIdNotextoIdempotencia (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"
driverIdNonúmero enteroConductor del directorio al que se asigna (alternativa a data.conductor.nif).
Ejemplo: 31
confirmWarningsNotrue / falsetrue: 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:

CampoQué es
idIdentificador interno.
numberNúmero del DeCA (año-empresa-correlativo). null mientras es borrador.
statusdraft: 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.
versionVersión vigente: 1 al emitirse, y una más con cada rectificación, anulación o sustitución.
urlURL 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_urlPDF 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_idTu referencia (externalId). Se consulta con ext:{externalId}; al sustituir, el nuevo DeCA la hereda.
driver_idConductor asignado (directorio de conductores).
sha256Huella SHA-256 del PDF vigente.
dataLos 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.

CampoObligatorioTipoPara qué sirve
cargador.nombreSítextoRazón social, o nombre y apellidos. Hasta 200 caracteres.
Ejemplo: "Cerámicas Levante SL"
cargador.nifSítextoNIF, 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.domicilioSítextoDomicilio 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.

CampoObligatorioTipoPara qué sirve
transportista.nombreSítextoRazón social, o nombre y apellidos. Hasta 200 caracteres.
Ejemplo: "Transportes Pérez SL"
transportista.nifSítextoNIF, 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í.

CampoObligatorioTipoPara qué sirve
intermediario.nombreNotextoRazón social. Si se envía, intermediario.nif es obligatorio. Hasta 200 caracteres.
intermediario.nifNotextoNIF, 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

CampoObligatorioTipoPara qué sirve
fecha_transporteSífecha AAAA-MM-DDDí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.

CampoObligatorioTipoPara qué sirve
vehiculo.matricula_tractoraSítextoMatrí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_remolqueNotextoMatrí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_especialNotextoAutorizació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.

CampoObligatorioTipoPara qué sirve
conductor.nombreNotextoNombre y apellidos. Hasta 200 caracteres.
Ejemplo: "Juan García López"
conductor.nifNotextoDNI 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.

CampoObligatorioTipoPara qué sirve
envios[].referenciaNotextoTu referencia del envío (albarán, pedido o expedición). Opcional. Hasta 80 caracteres.
Ejemplo: "ALB-9912"
envios[].origen.direccionSítextoCalle y número, polígono o punto kilométrico. Hasta 300 caracteres.
Ejemplo: "Ctra. Onda km 3"
envios[].origen.cpNotextoCódigo postal. Opcional. Hasta 12 caracteres.
Ejemplo: "12200"
envios[].origen.municipioSítextoMunicipio. Hasta 120 caracteres.
Ejemplo: "Onda"
envios[].origen.provinciaNotextoProvincia. Opcional. Hasta 120 caracteres.
Ejemplo: "Castellón"
envios[].origen.paisNotextoPaís. Si se omite, "España". Hasta 60 caracteres.
envios[].destino.direccionSítextoCalle y número, polígono o punto kilométrico. Hasta 300 caracteres.
Ejemplo: "Av. del Puerto 10"
envios[].destino.cpNotextoCódigo postal. Opcional. Hasta 12 caracteres.
Ejemplo: "46024"
envios[].destino.municipioSítextoMunicipio. Hasta 120 caracteres.
Ejemplo: "Valencia"
envios[].destino.provinciaNotextoProvincia. Opcional. Hasta 120 caracteres.
Ejemplo: "Valencia"
envios[].destino.paisNotextoPaís. Si se omite, "España". Hasta 60 caracteres.
envios[].naturalezaSítextoNaturaleza de la mercancía, p. ej. "Azulejos paletizados". Hasta 300 caracteres.
Ejemplo: "Azulejos paletizados"
envios[].peso_kgSí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_estimadoNotrue / falsetrue 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[].bultosNotextoNúmero y tipo de bultos, en texto libre (p. ej. "22 palés"). Opcional. Hasta 60 caracteres.
Ejemplo: "22 palés"
envios[].peso_calculoNotextoCó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)

CampoObligatorioTipoPara qué sirve
observacionesNotextoTexto 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ónQué da
https://decaeasy.es/d/Xk3pQ9vLm2RtY7wZ4nB8cD1eEl PDF vigente (es la URL que va en el QR).
https://decaeasy.es/d/Xk3pQ9vLm2RtY7wZ4nB8cD1e/qr.pngLa imagen del QR (PNG de 360 px), para imprimirla en tu albarán u hoja de ruta.
https://decaeasy.es/d/Xk3pQ9vLm2RtY7wZ4nB8cD1e/infoUna página con el estado del DeCA (vigente, rectificado, anulado o sustituido) y su historial.
https://decaeasy.es/d/Xk3pQ9vLm2RtY7wZ4nB8cD1e/pdf?v=1Una 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 driverId o su NIF en data.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é pasaQué usarEl QR
Cambia algún dato del mismo transporte (otro camión, otro peso, otra fecha cercana…)Rectificar: PATCH /documents/{ref} con reasonEl 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 transporteSustituir: POST /documents/{ref}/replaceUno nuevo (otro número). El anterior queda como sustituido, con un enlace al nuevo.
El transporte no se haceAnular: POST /documents/{ref}/voidEl 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ámetroPara qué sirve
qBusca en número, empresas, NIF, matrículas, conductor, municipios, referencias y mercancía.
statusUno de: draft, published, voided, superseded.
fromFecha de transporte desde (incluida).
toFecha de transporte hasta (incluida).
externalIdTu referencia exacta.
archivedUno 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_mismatch y document dice qué DeCA tiene ya esa clave. Para cambiarlo, usa PATCH; para otro DeCA, una clave nueva.
  • Si esa Idempotency-Key ya 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.

EventoCuándo llegaQué trae en data
document.draft_createdSe crea un borrador (en la web, en la app, con una importación o por la API).El documento.
document.publishedSe publica un DeCA: ya tiene número, PDF y QR.El documento.
document.correctedSe rectifica (mismo QR, versión nueva).El documento, con reason y changes (cada dato: antes y después).
document.replacedSe sustituye por un DeCA nuevo (otro número y otro QR).old y new (los dos documentos) y reason.
document.voidedSe anula.El documento, con reason.
document.archivedSe archiva.El documento.
pingPulsas «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 '', 200

Reintentos 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_at o consulta el DeCA. Un reintento trae el mismo id: 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).

HTTPerrorQué significaQué hacer
400invalid_json, bad_requestEl cuerpo no es JSON válido o la petición está mal formada.Revisa el JSON que envías.
401unauthorizedFalta la clave, no es válida o está revocada.Envía Authorization: Bearer deca_… con una clave activa.
402planEl 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.
403forbidden, account_suspendedClave 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.
404not_foundNo hay ningún DeCA con esa referencia en esta empresa, o la ruta no existe.Revisa el {ref} y la ruta.
409conflictEl 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.
413too_largeLa petición pasa de 1 MB.Envía menos envíos por DeCA.
422validationHay 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.
422idempotency_mismatchEsa Idempotency-Key ya se usó con otros datos.Para otro DeCA, usa una clave nueva. document dice cuál tiene ya esa clave.
422correction_closedYa pasó el plazo para rectificar el DeCA.Sustitúyelo (POST /documents/{ref}/replace).
429rate_limitedMá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ímiteValor
Peticiones120 por minuto por IP. Si se pasa, 429 con Retry-After.
DeCA emitidos por APILos 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ño1 MB por petición, de 1 a 100 envíos por DeCA y la longitud de cada campo (en la tabla de campos).
ListadosHasta 1000 DeCA por página (limit y offset).
RectificacionesHasta 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.
Webhooks5 por empresa, 5 segundos de espera por envío y 6 intentos.
Directorios5000 fichas de cada tipo por empresa.

Probar la integración

  1. 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.
  2. Prueba la conexión con GET /me y tus datos con POST /documents/validate: no crea nada ni gasta número.
  3. Prueba el ciclo completo con borradores y algún DeCA publicado: publica, rectifica, sustituye y anula. Los DeCA de prueba se anulan al terminar.
  4. Configura un webhook y pulsa «Enviar prueba» para comprobar la firma.
  5. 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 /me para comprobar la clave, POST /documents/validate para validar sin crear nada, needs_confirmation en 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.

Crear cuenta y clave gratis Hablar con nosotros