API e integración

Crea, consulta, actualiza, publica, rectifica, sustituye, anula y archiva DeCA desde tu ERP, TMS o WMS.

Especificación OpenAPI Colección Postman

Autenticación

Crea claves en Ajustes → API, de lectura o de lectura y escritura. Envía Authorization: Bearer deca_…. Cada clave pertenece a un espacio de trabajo.

Flujo recomendado

POST https://decaeasy.es/api/v1/documents          # crea borrador (o "publish": true para publicar directamente)
POST https://decaeasy.es/api/v1/documents/{ref}/publish
GET  https://decaeasy.es/api/v1/documents/{ref}     # {ref} = id, número de DeCA o ext:{externalId}

Crear y publicar

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 '{
  "externalId": "PED-48213",
  "publish": true,
  "data": {
    "cargador": {"nombre": "Cerámicas Levante SL", "nif": "B12345674", "domicilio": "Ctra. Onda km 3, Onda"},
    "transportista": {"nombre": "Transportes Pérez SL", "nif": "12345678Z"},
    "fecha_transporte": "2026-10-05",
    "vehiculo": {"matricula_tractora": "1234LMN", "matricula_remolque": "R5678BCD"},
    "conductor": {"nif": "X1234567L"},
    "envios": [{
      "origen": {"direccion": "Ctra. Onda km 3", "municipio": "Onda", "provincia": "Castellón"},
      "destino": {"direccion": "Av. del Puerto 10", "municipio": "Valencia"},
      "naturaleza": "Azulejos paletizados", "peso_kg": 18500, "bultos": "22 palés", "referencia": "ALB-9912"
    }]
  }}'

Respuesta 201 con id, number, url (la del QR), pdf_url, version y sha256.

Validación y avisos

Los errores devuelven 422 con errors por campo (p. ej. "envios.0.peso_kg"). Si solo hay avisos (fecha pasada, matrícula extranjera), reenvía con "confirmWarnings": true.

Idempotencia

Envía Idempotency-Key (o requestId en el cuerpo). Un reintento con la misma clave devuelve el documento ya creado con 200 en lugar de duplicarlo.

Modificar

PATCH /api/v1/documents/{ref}              # borrador: actualiza datos
PATCH /api/v1/documents/{ref}  {"reason": "...", "data": {...}}   # publicado: rectifica (mismo QR)
POST  /api/v1/documents/{ref}/replace {"reason": "...", "data": {...}}   # nuevo DeCA, nuevo QR
POST  /api/v1/documents/{ref}/void    {"reason": "..."}
POST  /api/v1/documents/{ref}/archive
GET   /api/v1/documents/{ref}/pdf

Si omites la versión, la API trabaja siempre sobre la versión vigente.

Directorios

GET|POST /api/v1/companies · /vehicles · /addresses · /drivers

Para asignar un conductor, indica driverId o su NIF en data.conductor.nif.

Webhooks firmados

Eventos: document.draft_created, document.published, document.corrected, document.replaced, document.voided, document.archived. Cabecera X-DeCA-Signature: t=…,v1=… con HMAC-SHA256 de "{t}.{cuerpo}".

const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', SECRET).update(t + '.' + rawBody).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) throw new Error('firma inválida');

Límites

DeCA emitidos por API al mes según el plan (1000 en Flexible, 5000 en Pro). Máximo 120 peticiones por minuto por IP.