El DeCA desde su propio programa

1. Obtenga una clave

Un administrador de la empresa entra en Ajustes › API dentro de la aplicación y crea una clave. Le pone un nombre («ERP oficina»), elige los permisos que le concede y, si quiere, una fecha de caducidad. La clave se muestra una sola vez; guárdela en el gestor de secretos de su programa, nunca en el código.

Cada clave actúa en nombre de un usuario de la empresa: los DeCA emitidos con ella quedan a su nombre en la auditoría, y la clave nunca puede hacer más de lo que ese usuario puede. Una clave se revoca desde la misma pantalla y deja de funcionar al instante.

2. Compruebe que funciona

Todas las peticiones van a https://app.decamio.com/api/v1 con la clave en la cabecera Authorization. La primera llamada es GET /cuenta: dice quién es usted, qué puede hacer la clave y cuántos DeCA le quedan este año.

curl https://app.decamio.com/api/v1/cuenta \
  -H "Authorization: Bearer $DECA_CLAVE" \
  -H "Accept: application/json"

3. Dé de alta a sus clientes

Clientes, vehículos y conductores se crean, consultan y modifican en /clientes, /vehiculos y /conductores. El NIF y la matrícula se normalizan (mayúsculas, sin separadores) y son únicos dentro de su empresa. Los datos de un cliente se copian a cada DeCA en el momento de emitirlo, así que cambiarlos después no altera los documentos ya emitidos.

curl -X POST https://app.decamio.com/api/v1/clientes \
  -H "Authorization: Bearer $DECA_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Cargadora del Sur, S.L.",
    "nif": "B12345678",
    "tipo": "cargador",
    "domicilio": "Calle Mayor, 1",
    "cp": "41001",
    "poblacion": "Sevilla"
  }'

Si ya tiene los datos en una hoja de cálculo, la aplicación también los importa desde Utilidades › Importar; la API no es obligatoria para eso.

4. Emita un DeCA

POST /documentos. Cada parte del documento admite el id de un maestro, los datos escritos, o las dos cosas: lo escrito gana campo a campo. El documento se numera, se genera su PDF con huella sha256 y queda publicado en la URL de su código QR en la misma llamada. Con envio.enviar se manda por correo al terminar.

curl -X POST https://app.decamio.com/api/v1/documentos \
  -H "Authorization: Bearer $DECA_CLAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-2026-04471" \
  -d '{
    "cargador":      { "cliente_id": 12 },
    "transportista": { "cliente_id": 3 },
    "destinatario":  { "nombre": "Almacenes Norte", "domicilio": "Pol. Ind. Las Rozas, nave 7" },
    "conductor":     { "conductor_id": 7 },
    "vehiculo":      { "matricula_tractor": "1234ABC", "matricula_remolque": "R0001BBB" },
    "servicio": {
      "origen": "Sevilla",
      "destino": "Madrid",
      "naturaleza_mercancia": "Palés de material de construcción",
      "peso": 12500,
      "bultos": 24,
      "fecha_envio": "2026-10-05"
    },
    "envio": { "email": "recepcion@almacen.es", "enviar": true }
  }'

La respuesta es 201 con el documento completo:

{
  "data": {
    "uuid": "0192c3a1-7f2e-7c1b-9a3d-5e6f7a8b9c0d",
    "referencia": "DECA-2026-000012",
    "version": 1,
    "situacion": "vigente",
    "cargador": { "cliente_id": 12, "nombre": "Cargadora del Sur, S.L.", "nif": "B12345678", "domicilio": "Calle Mayor, 1, 41001 Sevilla" },
    "servicio": { "origen": "Sevilla", "destino": "Madrid", "peso": 12500, "bultos": 24, "fecha_envio": "2026-10-05", "…": "…" },
    "envio": { "email_destinatario": "recepcion@almacen.es", "estado": "encolado" },
    "pdf": {
      "url": "https://app.decamio.com/api/v1/documentos/0192c3a1-…/pdf",
      "bytes": 48213,
      "sha256": "3f8a…c91e",
      "generado_en": "2026-10-05T10:21:03+02:00"
    },
    "url_publica": "https://app.decamio.com/deca/0192c3a1-7f2e-7c1b-9a3d-5e6f7a8b9c0d",
    "…": "…"
  }
}

Guarde el uuid: es el identificador público del documento, el mismo que codifica el QR, y con él se consulta, se descarga, se modifica y se anula. La referencia es la numeración correlativa de su empresa, la que se imprime.

Reintentos seguros

Emitir consume un número de la serie correlativa. Si a su programa se le corta la conexión después de que el servidor haya terminado, un reintento a ciegas emitiría un segundo DeCA. Para evitarlo, envíe en cada POST una cabecera Idempotency-Key con un valor único por operación —el número de su pedido, un UUID—. Una repetición con la misma clave y el mismo cuerpo devuelve la respuesta original con la cabecera Idempotent-Replayed: true y no emite nada. La reserva dura 24 horas.

5. Descargue el PDF

GET /documentos/{uuid}/pdf devuelve el fichero tal como se custodia, con el nombre de la referencia. Su huella está en pdf.sha256: puede comprobarla al recibirlo.

curl https://app.decamio.com/api/v1/documentos/0192c3a1-7f2e-7c1b-9a3d-5e6f7a8b9c0d/pdf \
  -H "Authorization: Bearer $DECA_CLAVE" \
  -o DECA-2026-000012.pdf

6. Modifique o anule

La norma permite corregir un DeCA emitido siempre que quede constancia. Por eso PATCH /documentos/{uuid} exige un motivo; la versión sube, el PDF se regenera y la URL del QR no cambia. cambios es parcial: sólo lo que envía se modifica.

curl -X PATCH https://app.decamio.com/api/v1/documentos/0192c3a1-7f2e-7c1b-9a3d-5e6f7a8b9c0d \
  -H "Authorization: Bearer $DECA_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "motivo": "Error en el pesaje: la báscula marcó 12.000 kg",
    "cambios": { "servicio": { "peso": 12000 } }
  }'

POST /documentos/{uuid}/anular, también con motivo. Nunca se borra nada: durante el periodo de conservación la URL del QR sigue respondiendo y muestra que el documento está anulado. El cupo anual no se recupera al anular.

7. Errores

Todo error devuelve message, un texto en castellano para leer, y codigo, un identificador estable para programar contra él. Cuando el cliente puede hacer algo para resolverlo, se añade accion.

8. Límites y buenas prácticas

• 120 peticiones por minuto y clave. Los listados devuelven 25 elementos por página (por_pagina, máximo 100).
• Una clave por integración, con los permisos justos. Una clave de sólo lectura para el cuadro de mando, otra con crear-documentos para el TMS.
• Referencie los maestros por id siempre que pueda: el documento queda enlazado a la ficha y los datos salen de un solo sitio.
• Los identificadores numéricos (cliente_id, conductor_id) son de su empresa; un id ajeno responde 422 en su campo, nunca emite.
• La API se corta entera si la suscripción deja de estar al corriente. Los documentos ya emitidos siguen accesibles desde la aplicación y desde su QR.

¿Está integrando un producto?

Si desarrolla software para transportistas y quiere ofrecer el DeCA dentro de su programa, hable con nosotros: le damos una cuenta de pruebas y le avisamos antes de cualquier cambio en la API.