API de DeCA: integrar la carta de porte digital en su ERP

Guía del DeCA · Para programadores

Cualquier programa de gestión puede cumplir el DeCA sin que nadie teclee nada dos veces. La API de DeCA es REST, con JSON y una clave por empresa. Tiene dos formas de uso: su programa genera el PDF y DeCA lo publica con su dirección y su QR, o su programa manda los datos y DeCA hace la carta. Esta página lo cuenta todo, con ejemplos que puede pegar.

curl -s -o /dev/null -w "%{redirect_url}\n" https://deca.overline.es/demo
# https://deca.overline.es/panel#0a1b2c…   ← la clave es lo que va detrás de «#»

Lo básico

• Dirección base: https://deca.overline.es. Solo HTTPS.
• Autenticación: cabecera X-Api-Key con la clave de la empresa. La clave es la parte que va detrás de # en el enlace de acceso de la empresa (https://deca.overline.es/mi#CLAVE). Trátela como una contraseña: quien la tiene, actúa como la empresa.
• Formato: JSON en UTF‑8 (en Windows, si prueba con curl, guarde el cuerpo en un fichero UTF‑8 y mándelo con --data-binary @carta.json: la consola manda los acentos en otra codificación y la petición da 400), nombres de campo en camelCase. Fechas yyyy-MM-dd; fecha y hora yyyy-MM-ddTHH:mm (hora local, sin zona).
• Errores: un código HTTP y, en el cuerpo, {"error": "…"} o un application/problem+json con detail. Los mensajes están en español y se pueden enseñar tal cual al usuario.

Forma 1: su programa hace el PDF, DeCA lo publica

Es la integración más corta y la que usa OverFacNet: su programa sigue imprimiendo su albarán o su carta de porte con su diseño, le añade un QR y sube el PDF. El truco está en que el identificador lo pone su programa: genera un UUID, y la dirección pública es siempre https://deca.overline.es/d/{uuid}, así que puede imprimir el QR en el PDF antes de subirlo.

1. Genere un UUID para el documento (y guárdelo con el albarán: es su identificador para siempre).
2. Dibuje en el PDF un QR con https://deca.overline.es/d/{uuid}. Si su generador de informes no hace QR, GET /qr/{uuid} le devuelve la imagen (BMP), sin clave.
3. Suba el PDF con PUT /api/deca/{uuid}. Desde ese momento el QR funciona.

PUT/api/deca/{uuid}

Publica el PDF (cuerpo: el PDF tal cual, Content-Type: application/pdf, hasta 5 MB). Si el UUID ya existe, es una versión nueva del mismo documento: la dirección y el QR no cambian y la versión anterior queda en el historial. Cabeceras opcionales:

• X-Deca-Referencia: su número de albarán o carta (texto ASCII), para encontrarlo en el panel.
• X-Deca-Fin-Servicio: fecha de fin del transporte (yyyy-MM-dd). Mándela siempre: la dirección pública se retira sola a los 7 días de esa fecha, como permite la norma. Sin ella, el documento sigue público hasta que se retire a mano.

curl -X PUT "https://deca.overline.es/api/deca/3f2b8c1e-5d4a-4f7e-9a10-2c6b7d8e9f01" \
  -H "X-Api-Key: $CLAVE" \
  -H "Content-Type: application/pdf" \
  -H "X-Deca-Referencia: ALB-2026-001234" \
  -H "X-Deca-Fin-Servicio: 2026-10-03" \
  --data-binary @albaran.pdf

{"url":"https://deca.overline.es/d/3f2b8c1e-5d4a-4f7e-9a10-2c6b7d8e9f01","version":1,"sinCambios":false}

Subir otra vez el mismo PDF (un reintento) no crea otra versión: contesta con la vigente y "sinCambios": true.

Lo mismo en C#:

using var http = new HttpClient { BaseAddress = new Uri("https://deca.overline.es") };
http.DefaultRequestHeaders.Add("X-Api-Key", clave);

var uuid = Guid.NewGuid();                       // guárdelo con el albarán
var urlQr = $"https://deca.overline.es/d/{uuid}"; // lo que va en el QR del PDF
byte[] pdf = GenerarAlbaranConQr(albaran, urlQr); // su informe de siempre, con el QR

using var cuerpo = new ByteArrayContent(pdf);
cuerpo.Headers.ContentType = new("application/pdf");
using var req = new HttpRequestMessage(HttpMethod.Put, $"/api/deca/{uuid}") { Content = cuerpo };
req.Headers.Add("X-Deca-Referencia", albaran.Numero);
req.Headers.Add("X-Deca-Fin-Servicio", albaran.Fecha.ToString("yyyy-MM-dd"));
var r = await http.SendAsync(req);
if (!r.IsSuccessStatusCode) throw new Exception(await r.Content.ReadAsStringAsync());

GET/api/deca/{uuid}

El estado de un documento suyo: url, referencia, finServicio, activo (si la dirección pública sigue abierta), version, creado, modificado y descargas (cuántas veces se ha abierto el QR).

POST/api/deca/{uuid}/desactivar

Retira la dirección pública antes de que lo haga el servicio. Solo se admite pasados 7 días del fin del servicio (409 si no): la norma obliga a mantenerla mientras tanto. El documento se sigue conservando un año.

Forma 2: su programa manda los datos, DeCA hace la carta

Si prefiere no dibujar el PDF, mande los datos y DeCA genera la carta de porte con su impreso (el completo de trece recuadros, el mínimo, o la plantilla con el membrete de la empresa), la numera, la publica y le devuelve la dirección. Es lo que hace el móvil por dentro.

POST/api/cartas

Crea y publica una carta. Imprescindibles: el lugar de destino (destino) o el destinatario (cliente), y la mercancía (mercancia). Lo demás puede faltar al guardar —en el muelle no se bloquea a nadie por un teléfono—, pero lo que exige el artículo 6 de la Orden y no venga se devuelve en faltan.

curl -X POST https://deca.overline.es/api/cartas \
  -H "X-Api-Key: $CLAVE" -H "Content-Type: application/json" \
  -d '{
    "fecha": "2026-10-03",
    "traNombre": "Transportes Pérez, S.L.", "traNif": "B26000001",
    "carNombre": "Áridos del Ebro, S.A.", "carNif": "A26000002",
    "carDireccion": "Camino de la Gravera s/n, 26200 Haro (La Rioja)",
    "oriNombre": "Áridos del Ebro, S.A.", "oriDireccion": "Gravera de Haro, 26200 Haro",
    "cliente": "Hormigones Rioja, S.L.", "clienteNif": "B26000003",
    "destino": "Planta de Logroño, Pol. Cantabria, 26009 Logroño",
    "mercancia": "Grava 6/12 a granel", "bruto": 40120, "tara": 14300,
    "matricula": "1234BCD", "remolque": "R5678BBB",
    "transportista": "Juan Pérez", "transportistaDni": "12345678Z"
  }'

{"uuid":"…","numero":128,"url":"https://deca.overline.es/d/…","publicada":true,"aviso":null,"faltan":[]}

Los campos, por recuadro del impreso:

Los NIF y DNI se guardan sin espacios ni guiones; las matrículas, en mayúsculas. El número de carta lo pone el servicio, correlativo por empresa. Con la opción «crear empresas automáticamente» de la cuenta, las empresas de la carta se dan de alta solas; con «crear conductores automáticamente», también el conductor (si viene su DNI), que verá la carta en su móvil.

PUT/api/cartas/{uuid}

Corrige una carta: mande la carta entera (los campos que no vengan quedan vacíos). Se vuelve a publicar en la misma dirección, así que el QR no cambia. Si no cambia ningún dato, no se publica versión nueva y la respuesta trae "sinCambios": true. Si la carta ya está firmada, 409: hay que quitar antes las firmas desde el panel. Si está anulada, 409: se hace otra.

Borradores

Con "borrador": true en el POST, la carta se guarda sin emitir: sin número, sin PDF ni QR, y el conductor no la ve. Vale con los datos que haya (en un borrador es normal no saber aún el peso o la matrícula). Se retoca con PUT (con "borrador": true sigue de borrador) y se emite con un PUT sin esa marca: en ese momento se le pone el número (el siguiente de la empresa, así la numeración no deja huecos aunque se tiren borradores) y se publica. Un borrador se elimina con DELETE /api/cartas/{uuid}; una carta emitida no se elimina: se anula. Los borradores son cosa de la clave de empresa: con una clave de editor se emite siempre.

POST/api/panel/documento/{uuid}/anular

{"motivo": "Datos erróneos"} (el motivo es opcional). Anula un documento emitido, suyo o subido por su programa. No se borra nada: queda marcado, con el motivo, con todas sus versiones y firmas a la vista; una carta hecha por DeCA se vuelve a publicar como última versión con la marca «ANULADA» cruzada y el motivo al pie, y la dirección del QR lleva a una vista que lo dice en grande. Ya no admite cambios, ni firmas, ni versiones nuevas (409). Para corregirla, haga otra carta: si en el POST manda "sustituyeA": "{uuid de la anulada}", la anulada queda apuntando a la nueva (y la nueva dice a cuál sustituye). Cada carta devuelve anulada, anuladaEn, anuladaMotivo y sustituidaPor.

GET/api/cartas?dias=30

Las cartas de los últimos dias (de 1 a 366; por defecto 5), la más reciente primero, cada una entera, con sus 13 recuadros y además uuid, numero, url, publicada, firmada, faltan, creada y modificada. Es lo que usa OverFacNet para traerse como albaranes las cartas hechas desde el móvil. Las claves de conductor ven solo las suyas, y como mucho las de 7 días.

GET/api/cartas/{uuid} · /api/cartas/{uuid}/pdf

Una carta, con sus firmas (quién y cuándo), y su PDF. El PDF por aquí pide clave, no cuenta como descarga pública y sigue disponible aunque la dirección pública ya se haya retirado.

Clientes, transportistas y conductores

Para que al hacer una carta (en el móvil o en el panel) se elija la empresa con un buscador en vez de teclearla, su programa puede volcar sus maestros.

PUT/api/empresas

Una lista de empresas. Cada una entra por su id en su programa y, si no existe con ese id pero sí una con el mismo NIF, se considera la misma. roles dice qué papel hace en las cartas: transportista, cargador, origen, destino (sin roles, destino). Con ?completo=true, las que mandó antes y ahora no vienen quedan de baja.

[
  {"id": "430000123", "nombre": "Hormigones Rioja, S.L.", "nif": "B26000003",
   "direccion": "Pol. Cantabria, calle B 4", "cp": "26009", "poblacion": "Logroño",
   "provincia": "La Rioja", "telefono": "941 000 111", "email": "pedidos@ejemplo.es",
   "activo": true, "roles": ["destino"]}
]

Respuesta: {"recibidos", "guardados", "bajas"}. Ojo: una cuenta que recibe empresas de su ERP pasa a llevarlas desde allí, y en el panel ya no se cambian su nombre, NIF ni dirección (sí sus roles), para que no se desparejen.

GET/api/empresas?busca=rioja&rol=destino

Busca por nombre o NIF; salen primero las del papel pedido. Por defecto 20 (limite hasta 1000).

PUT/api/conductores

Una lista de conductores: {"nombre", "dni", "matricula", "remolque", "movil", "email"}. Cada uno entra por su DNI: si ya existe se actualiza; si no, se da de alta con su propia clave, lista para mandarle su enlace del móvil desde el panel. No da de baja a nadie. Respuesta: {"recibidos", "nuevos", "actualizados", "sinDni"}.

GET/api/conductores

Los conductores de la empresa, cada uno con su enlace para el móvil.

Otras llamadas útiles

• GET/api/panel/documentos.xlsx?desde=2026-10-01&hasta=2026-10-31&q=rioja: los documentos del periodo en una hoja de Excel, con todos sus datos agrupados por recuadros.
• GET/api/panel/documento/{uuid}/versiones: todas las versiones de un documento suyo, con su fecha, su motivo (alta, corrección, firma…) y la huella SHA-256 de cada PDF; el de una versión, en /api/panel/documento/{uuid}/pdf?version=n. Mientras está publicado, también sin clave: /api/publico/{uuid}/versiones y /d/{uuid}/v/{n}.
• GET/qr/{uuid}: el QR de un documento, como imagen. Sin clave.
• GET/d/{uuid}: la dirección pública, la del QR. Sin clave, PDF directo; 410 cuando ya se ha retirado.
• GET/api/sesion: quién es la clave (empresa, conductor…), sus datos y, si está en prueba, hasta cuándo.

Consejos de integración

• Publique antes de que salga el camión. La Resolución pide que el documento exista antes del inicio del servicio. Lo natural es subirlo al emitir el albarán.
• Guarde el UUID con el documento de su programa. Para corregir, vuelva a subir con el mismo UUID: el papel que ya lleva el conductor sigue valiendo.
• Reintente si falla la red, con el mismo UUID: subir dos veces lo mismo solo crea una versión más.
• Una clave por empresa: si su programa lleva varias empresas, cada una con su cuenta y su clave.