Customer API

El modelo: un borrador que se rellena

El DeCA se constituye por partes: nace como un borrador incompleto, se rellena con tantas llamadas como necesites y se cierra al llamar a generar QR. Mientras está abierto está en modo borrador, y no tiene validez legal.

              POST /v1/decas
              (constituye, N veces)
                    ↺
                    │
   ──────────►  borrador  ──────────────►  emitido
   crear            ▲      generar_QR         │
                    │                         │
                    └────── regenerar ────────┘
                          (abre borrador nuevo,
                           sembrado con lo emitido)

Cada llamada de escritura corresponde a una transición: constituir se puede repetir, generar consume un número de tu serie legal y produce el PDF, y regenerar abre una corrección que queda registrada. Ninguna de las dos últimas ocurre como efecto de la primera.

Autenticación

Clave estática por cabecera, en las cuatro llamadas. Se emite al dar de alta la integración y es revocable en caliente, sin desplegar nada de tu lado.

x-api-key: dk_live_a1b2c3d4e5f6g7h8i9j0
Content-Type: application/json

La clave identifica una cuenta y una empresa. Lo que emitas queda bajo esa empresa, con su serie de numeración propia, y solo esa cuenta lo consulta. La referenciaExterna es única dentro de esa empresa, no globalmente: dos clientes pueden usar el mismo OC-100425 sin cruzarse.

Constituir DeCA

Abre el borrador si referenciaExterna es nueva; si ya hay uno abierto, funde los campos recibidos con los que hubiera. Es la misma llamada en los dos casos.

Entrada

{
  "referenciaExterna": "OC-100425",
  "cargadorNombre":    "Segura SL",
  "cargadorNif":       "B12345678",
  "cargadorDomicilio": "Pol. Fuente del Jarro, 46988 Paterna",
  "origen":            "Valencia",
  "destino":           "Irún",
  "mercanciaNatura":   "Palés de cerámica",
  "mercanciaPeso":     "18500 kg"
}

{
  "id":                "3f9a2b1c-8d5e-4f2a-9c1b-7e6d5a4b3c2d",
  "referenciaExterna": "OC-100425",
  "estado":            "borrador",
  "faltan": ["transportistaNombre", "transportistaNif",
              "matriculaTractor", "fechaTransporte"]
}

{ "referenciaExterna":  "OC-100425",
  "transportistaNombre": "Logística Ríos SL",
  "transportistaNif":    "B98765432",
  "matriculaTractor":    "4521 KLM",
  "matriculaRemolque":   "R-8830" }

// → 200 { "estado":"borrador", "faltan":["fechaTransporte"] }
// Los campos de la llamada 1 siguen ahí. Esto suma, no reemplaza.

Generar QR

Cierra el borrador. Valida los once obligatorios, asigna el siguiente número de la serie de tu empresa y genera el PDF con su código QR de verificación incrustado.

Entrada

La referenciaExterna en la ruta y la clave en la cabecera. Sin cuerpo.

{ "id": "3f9a2b1c-8d5e-4f2a-9c1b-7e6d5a4b3c2d",
  "referenciaExterna": "OC-100425",
  "estado": "emitiendo" }

202 y no 200: la generación es asíncrona y tarda unos segundos. Sondea la consulta hasta que el estado sea emitido, o pide que te configuremos un webhook de aviso.

{ "error": "campos_obligatorios",
  "detalle": "no se puede emitir sin todos los apartados del art. 6",
  "faltan": ["fechaTransporte"] }

Un 422 no toca nada: el borrador sigue abierto y con su contenido intacto. Completa lo que falte y vuelve a llamar.

Si la llamas dos veces

Después de la primera llamada ya no queda borrador que emitir. La segunda encuentra el documento en curso o terminado y te lo devuelve.

Ni segundo PDF, ni segundo número de serie, ni segunda versión. Para que exista una v2 hay que pasar por regenerar, que es una llamada distinta y exige un motivo.

Regenerar

El documento emitido no se edita. Regenerar abre un borrador nuevo sembrado con los campos del documento vigente, ya enlazado al anterior: es la vía para un cambio de vehículo a mitad de ruta o un error en el peso.

Entrada

Ningún campo del transporte: los cambios entran después por POST /v1/decas, la única puerta de escritura.

{ "motivo": "cambio de vehículo por avería en ruta" }

// → 200
{ "id":      "7d2e9f04-…",        // el DeCA nuevo, todavía sin emitir
  "estado":  "borrador",
  "version": 2,
  "regeneradoDe": "3f9a2b1c-…",  // el DeCA vigente hasta ahora
  "faltan":  [] }                 // viene completo: se sembró de uno emitido

El ciclo de corrección

POST /v1/decas/OC-100425/regenerar   { motivo }              → 200 borrador, faltan:[]
POST /v1/decas                       { matriculaTractor }    → 200 borrador
POST /v1/decas/OC-100425/generar_QR                          → 202 → v2, referencia 47

• La versión nueva hereda la referencia legal. Tu numeración no salta: sigue siendo el DeCA nº 47, corregido.
• La anterior queda marcada como reemplazada y sigue descargable.
• El QR del PDF nuevo apunta al anterior: la cadena v1 → v2 → v3 queda trazada.
• Tu referenciaExterna no cambia nunca y siempre resuelve a la versión vigente.

Consultar documento

Válido en cualquier fase. En borrador devuelve lo acumulado y lo que falta; emitido, el número legal, el PDF vigente y la cadena de versiones.

{
  "id":                "7d2e9f04-…",
  "referenciaExterna": "OC-100425",
  "estado":            "emitido",
  "referencia":        47,          // nº de DeCA de tu empresa
  "version":           2,
  "emitidoEl":         "2026-08-18T14:31:07Z",
  "pdfUrl":            "https://f003.backblazeb2.com/…?X-Amz-Signature=…",
  "versiones": [
    { "version": 1, "emitidoEl": "2026-08-18T11:04:22Z",
      "reemplazado": true,  "motivo": null, "pdfUrl": "https://…" },
    { "version": 2, "emitidoEl": "2026-08-18T14:31:07Z",
      "reemplazado": false, "motivo": "cambio de vehículo por avería en ruta",
      "pdfUrl": "https://…" }
  ],
  "documento": { /* todos los campos tal y como se imprimieron */ }
}

Campos del documento

Los nombres son los del contrato y no cambian dentro de v1. Los once obligatorios son los apartados del artículo 6 y son condición para generar, no para constituir.

Obligatorios para generar

mercanciaPeso es texto, no número: la norma admite expresar la cantidad en otra magnitud. Manda la unidad dentro del valor.

Opcionales

Estados y transiciones

Qué admite cada estado

Dos invariantes al integrar: hay como mucho un borrador abierto por referencia (de ahí el 409 de regenerar sobre un borrador) y un documento en error no ha consumido número de serie, así que reintentar no deja huecos en tu numeración.

Reintentos

Las cuatro llamadas se pueden repetir. La unicidad la impone una restricción en base de datos, no una comprobación de la aplicación.

Códigos de error

Formato único en todas las rutas. El texto de detalle es explicativo y puede cambiar: para tu lógica usa el código HTTP y el campo error, que sí es estable.

{ "error": "ya_emitido", "detalle": "usa /regenerar para abrir una corrección" }

Límites y alcance

Fuera de alcance en v1

• Sin EDI ni SFTP. Solo HTTPS con JSON. Si tu operativa es de ficheros por lotes, escríbenos y lo vemos aparte.
• Sin OCR por API. La extracción de campos desde una foto del albarán vive en el panel web. La API recibe los datos ya estructurados.
• Sin firma electrónica cualificada. El DeCA no la exige.
• Sin borrado de documentos emitidos. Se corrigen, no se eliminan.
• Una empresa por clave. Si emites en nombre de varias sociedades, una clave por cada una.