Integración con su programa de gestión (API)

Si su empresa ya planifica los viajes en un TMS, un ERP o una hoja de rutas, puede generar los DeCA sin teclear nada dos veces. La API es REST con JSON, se autentica con una clave de cuenta y devuelve el documento con su número, su URL única y su PDF.

1. Clave de acceso

El titular de la cuenta crea claves en «Usuarios y cuenta → Claves de API». Cada petición lleva la cabecera Authorization: Bearer deca_…. Las claves pueden revocarse en cualquier momento y cada uso queda en el registro de actividad. Límite: 120 peticiones por minuto.

Base: https://deca.vulcano.dev/api/v1

2. Crear y emitir un DeCA

POST /api/v1/decas. Por defecto el documento se emite en la misma llamada ("emitir": true); si falta algún dato esencial, responde 422 con los errores y su artículo, y el documento queda guardado como borrador.

curl -X POST https://deca.vulcano.dev/api/v1/decas \
  -H "Authorization: Bearer deca_SU_CLAVE" -H "Content-Type: application/json" \
  -d '{
    "role_mode": "transportista",
    "shipper_name": "Frutas del Júcar, S.L.", "shipper_nif": "B46987657",
    "shipper_address": "Camino de la Ribera 45, 46600 Alzira", "shipper_email": "logistica@frutasdeljucar.example",
    "transport_date": "2026-10-18", "transport_time": "06:00",
    "vehicle_plate": "4521 LKM", "articulated": true, "trailer_plate": "R2345BBC",
    "driver_name": "Antonio Ruiz Pérez",
    "envios": [
      {"origin": "Frutas del Júcar, Alzira", "destination": "Mercamadrid, nave F, Madrid", "goods_nature": "Naranjas en palés", "weight_kg": 23500}
    ]
  }'

Si actúa como transportista efectivo (role_mode «transportista» o «ambos»), sus datos de empresa se añaden solos; si subcontrata (role_mode «cargador»), envíe carrier_name, carrier_nif y, opcionalmente, carrier_authorization. Puede usar shipper_id, vehicle_id, trailer_id y driver_id con los identificadores de sus catálogos (GET /api/v1/catalogo/cargadores|vehiculos|conductores|transportistas); si indica driver_id, el conductor recibe la copia en su app.

Respuesta (201):

{
  "documento": {
    "numero": "TDL-2026-000031", "estado": "emitido", "version": 1,
    "fecha_transporte": "2026-10-18", "hora_prevista": "06:00",
    "cargador_contractual": {"nombre": "Frutas del Júcar, S.L.", "nif": "B46987657", "domicilio": "…", "email": "…"},
    "transportista_efectivo": {"nombre": "Transportes Demo Levante, S.L.", "nif": "B46123451", "autorizacion": "MDPE 46-0012345"},
    "vehiculo": {"matricula": "4521 LKM", "articulado": true, "remolque": "R2345BBC"},
    "envios": [{"posicion": 1, "origen": "…", "destino": "…", "mercancia": "…", "peso_kg": 23500, "otra_magnitud": null}],
    "creado": "2026-10-17T03:49:19+02:00", "modificado": null,
    "url_publica": "https://deca.vulcano.dev/d/…/.pdf", "url_qr": "https://deca.vulcano.dev/d/…/.png", "sha256": "…",
    "versiones": [{"version": 1, "fecha": "…", "motivo": null, "cambios": null, "sha256": "…"}]
  }
}

3. Consultar, descargar, modificar y anular

Petición	Qué hace
`GET /api/v1/decas?desde=2026-10-01&hasta=2026-10-31&estado=emitido`	Lista paginada (`por_pagina` hasta 200).
`GET /api/v1/decas/{numero}`	Un documento con sus versiones.
`GET /api/v1/decas/{numero}/pdf`	El PDF vigente (binario).
`POST /api/v1/decas/{numero}/emitir`	Emite un borrador.
`POST /api/v1/decas/{numero}/modificar` con `motivo` y los campos que cambian	Nueva versión en la misma URL y QR; los datos no enviados se conservan (Resolución, Quinto).
`POST /api/v1/decas/{numero}/anular` con `motivo`	Anula el documento; el PDF pasa a mostrar la anulación.

curl -X POST https://deca.vulcano.dev/api/v1/decas/TDL-2026-000031/modificar \
  -H "Authorization: Bearer deca_SU_CLAVE" -H "Content-Type: application/json" \
  -d '{"motivo": "Cambio de semirremolque por avería", "trailer_plate": "R9988DDF"}'

4. Errores

401 clave no válida · 403 cuenta sin plan activo · 404 documento no encontrado · 409 estado incompatible (por ejemplo, modificar un borrador) · 422 datos incompletos o inválidos (campo errors con los mensajes, o errores con mensaje y norma cuando falta un dato esencial del art. 6) · 429 demasiadas peticiones.

5. Importación desde Excel

Si no quiere programar, la oficina puede importar una hoja CSV con un DeCA por fila (plantilla descargable en «Importar desde Excel»). Las dos vías conviven: los documentos creados por API o por importación se ven y se gestionan igual que los demás.

¿Necesita campos adicionales o un webhook al modificar o anular? Cuéntenoslo.