API

Conecta tu ERP y emite sin teclear

Tu programa manda el porte, DecaFirma emite el DeCA y el albarán con su QR y te devuelve el enlace y el PDF. Lo mismo que en pantalla, con las mismas comprobaciones.

¿Usas a3ERP, Holded, Odoo u otro? Si prefieres que lo conectemos nosotros, escríbenos: es lo que hacemos en Francodesystems.

1. La clave

Quien administra la empresa la crea en Configuración → Conectar tu programa (API). Se enseña una sola vez. Va en cada petición:

Authorization: Bearer dfk_…

Lo que se emite con una clave va a nombre de quien la creó. Si esa persona deja de poder emitir, la clave deja de valer. Como mucho 120 peticiones por minuto. Durante la prueba, los documentos salen marcados como DEMO, igual que en pantalla.

2. Crear el envío y emitir

POST /api/v1/envios

curl -X POST https://decafirma.com/api/v1/envios \
  -H "Authorization: Bearer dfk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "referencia": "PED-4521",
    "shipperName": "Cerámicas Levante, S.L.",
    "shipperTaxId": "B98765431",
    "shipperAddress": "Camí Collet 14, 12200 Onda",
    "originCity": "Onda",
    "destinationCity": "Riba-roja de Túria",
    "consigneeName": "Almacenes Pérez, S.A.",
    "goodsDescription": "Palés de azulejo",
    "weightKg": 9000,
    "packages": 12,
    "transportDate": "2026-10-05",
    "plate": "1234KLM",
    "driverName": "Paco Martínez",
    "emitir": "ambos"
  }'

Respuesta (201):

{
  "id": "cmu…",
  "referencia": "PED-4521",
  "estado": "documentado",
  "documentos": [
    { "id": "cmv…", "tipo": "deca", "referencia": "DECA-…", "version": 1, "estado": "vigente",
      "demo": false, "url": "https://decafirma.com/d/…", "pdf": "https://decafirma.com/api/v1/documentos/cmv…/pdf" },
    { "id": "cmw…", "tipo": "albaran", "referencia": "ALB-2026-0042", "version": 1, "estado": "vigente",
      "demo": false, "url": "https://decafirma.com/d/…", "urlFirma": "https://decafirma.com/d/…/firmar", "firmado": null,
      "pdf": "https://decafirma.com/api/v1/documentos/cmw…/pdf" }
  ]
}

url es lo que abre el QR: se puede mandar tal cual al conductor. urlFirma es donde firma el cliente la entrega.

Los campos

Los mismos del formulario de emitir. Un campo que no conocemos devuelve error, para que una errata no se pierda en silencio.

referencia: Tu número de pedido o porte. Si ya existe un envío con esa referencia, no se crea otro: se devuelve el que hay.
shipperName, shipperTaxId, shipperAddress: Cargador contractual (quien contrata el porte): nombre, NIF y domicilio. Obligatorios para el DeCA.
carrierName, carrierTaxId: Transportista efectivo. Si no los mandas, eres tú.
carrierPhone, carrierEmail: Para mandarle el QR. No se imprimen.
originCity, destinationCity: Municipio de origen y de destino. Obligatorios.
originName, originAddress, originPostcode, originProvince, originPhone, originContact: El resto del origen (y lo mismo con destination…).
consigneeName, consigneeTaxId, consigneeContact, consigneeContactPhone, consigneeEmail: Destinatario. Obligatorio solo para el albarán.
goodsDescription, weightKg, packages: Mercancía, peso en kilos y bultos. Mercancía y peso son obligatorios.
transportDate, transportTime: Fecha AAAA-MM-DD (obligatoria) y hora HH:MM.
plate, trailerPlate: Matrícula de la tractora (obligatoria) y del remolque.
driverName, driverTaxId, driverPhone: Conductor. Con el teléfono se le puede mandar el QR.
noteKind: Tipo de albarán: DELIVERY (entrega, por defecto), PICKUP (recogida) o SERVICE.
freightTerms, importe, terms, notes: Portes (PREPAID o COLLECT), importe en euros, condiciones y observaciones.
lineas: Líneas del albarán: [{ "descripcion", "referencia", "bultos", "pesoKg" }].
numeroAlbaran: El número de albarán de tu programa. Sin él, lo numera DecaFirma.
autorizacionEspecial: true si el vehículo circula con autorización especial.
emitir: «deca», «albaran», «ambos» o «ninguno» (por defecto: solo se guarda).

3. Consultar y descargar

# El envío, sus documentos y si el albarán está firmado
curl https://decafirma.com/api/v1/envios/cmu… -H "Authorization: Bearer dfk_…"

# El PDF (última versión)
curl https://decafirma.com/api/v1/documentos/cmv…/pdf -H "Authorization: Bearer dfk_…" -o DECA.pdf

# Emitir más tarde (si lo creaste sin emitir o faltaba algo)
curl -X POST https://decafirma.com/api/v1/envios/cmu…/emitir -H "Authorization: Bearer dfk_…" \
  -H "Content-Type: application/json" -d '{"tipo": "deca"}'

Errores

Siempre en JSON, con un mensaje que se entiende: { "error": "…", "detalles": [...] }.

400: la petición no es válida (dice qué campo).
401: falta la clave o está revocada. 403: quien la creó ya no puede emitir.
422: el envío se ha creado pero no se ha podido emitir (falta un dato, un NIF mal…). Viene el envío y el motivo: lo arreglas y llamas a /emitir.
429: más de 120 peticiones en un minuto.