API V1

Conecta tu ERP

Una petición representa un envío entre una carga y una entrega de un tramo. El Excel y la API utilizan los mismos campos y validaciones.

Acceso y referencias

Cabecera X-Deca-Key con una credencial específica de cliente. Cada credencial autoriza determinados CIF. Conserva la clave en el servidor de tu ERP.

La combinación empresaCif + referenciaExterna + tramoReferencia + envioReferencia identifica el envío. Repetir datos idénticos recupera el mismo documento. Cambiar los datos requiere rectificación explícita y versión esperada.

POST /api/v1/deca
Content-Type: application/json
X-Deca-Key: [credencial privada]

{
  "empresaCif": "B00000001",
  "referenciaExterna": "SERV-2026-001",
  "tramoReferencia": "T01",
  "envioReferencia": "E01",
  "inicioTransporte": "2026-10-05T08:00:00+02:00",
  "cargadorNombre": "Cargador de ejemplo",
  "cargadorNif": "B00000001",
  "cargadorDireccion": "Calle de ejemplo 1, Barcelona",
  "transportistaNombre": "Transportista de ejemplo",
  "transportistaNif": "B00000002",
  "origen": "Barcelona",
  "origenPais": "ES",
  "destino": "Madrid",
  "destinoPais": "ES",
  "mercancia": "Mercancía paletizada",
  "pesoKg": 1200,
  "matriculaTractora": "1234BCD",
  "conRemolque": false,
  "matriculaRemolque": "",
  "requiereAutorizacionEspecial": false,
  "autorizacionEspecial": "",
  "conductorReferencia": "CON-001",
  "observaciones": "Datos ficticios: sustituir antes de emitir"
}

La fecha del ejemplo debe sustituirse por una fecha futura. La emisión inicial se realiza antes del transporte. Las fechas de API incluyen zona horaria; las fechas nativas de Excel se interpretan en Europe/Madrid.

Operaciones

Método y ruta	Resultado
GET /api/v1/cuenta	Cliente, CIF autorizados y entorno.
POST /api/v1/deca	Emite o recupera un DeCA. Devuelve id, versión, URL, SHA-256 y reutilizado.
POST /api/v1/lotes	Objeto con items: hasta 500 envíos. Todo el lote se confirma o se revierte.
POST /api/v1/importaciones/validar	Multipart con file XLSX. Revisa datos sin emitir.
GET /api/v1/deca?pagina=1	100 documentos vigentes por página.
GET /api/v1/deca/{id}	Datos, estado y referencia a la versión vigente.
PUT /api/v1/deca/{id}	Rectifica con {versionEsperada, motivo, datos}. Nuevo PDF, URL y QR; conserva el original.
POST /api/v1/deca/{id}/finalizar	{versionEsperada, finServicio}. Fecha real, posterior al inicio y no futura.
GET /api/v1/deca/{id}/pdf	Descarga autenticada del archivo conservado.
GET /d/{token}.pdf	Descarga directa del PDF mediante token no predecible, sin login.

Respuestas: 400 formato, 401 credencial, 404 recurso no accesible, 409 conflicto de versión/referencia, 410 enlace público finalizado, 413 tamaño, 422 datos incompletos y 429 límite de peticiones.

El enlace público puede caducar siete días después de la finalización real. Sin finalización registrada permanece activo. La copia privada y las versiones se conservan. No hay borrado automático.

Alcance de esta versión

Emisión nacional, archivo y entrada de datos por Excel/API. La referencia de conductor se guarda para la futura distribución; todavía no realiza avisos push ni incluye autenticación o aplicación de conductor. El entorno local genera documentos identificados como pruebas.

El contrato define la interoperabilidad técnica. Antes de operar en producción deben validarse el procedimiento documental, HTTPS público, conservación, copias de seguridad, recuperación y carga de trabajo.