Documentacion API · DecaServer

Referencia para integraciones

API DecaServer v1

Integra tus contactos, vehículos y documentos DeCA. Consulta cada operación con sus parámetros, ejemplos y respuestas.

Empezar

Conecta tu empresa

Autenticación y empresa

Un propietario o administrador crea el token en Acceso API. Usa el subdominio de esa empresa y envía Authorization: Bearer TOKEN y Accept: application/json. El token puede caducar y solo permite las capacidades y empresas autorizadas.

Escrituras e idempotencia

En las escrituras envía Content-Type: application/json e Idempotency-Key. Repite la misma clave y el mismo cuerpo si debes reintentar. Una clave reutilizada con otros datos responde 409.

Primera consulta

curl 'https://EMPRESA.DOMINIO/api/v1/documentos' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN'

Sustituye EMPRESA.DOMINIO por el subdominio real. Usa HTTPS en producción. Los ejemplos emplean valores ficticios y no envían peticiones.

Reglas que conviene conocer

Solo la primera emisión consume una unidad del plan mensual, aunque tenga varios envíos. Los borradores, reintentos y rectificaciones no consumen otra. Al agotarse el cupo o vencer el plazo de regularización del pago, crear y emitir responden 409 con codigo cupo_agotado o pago_pendiente; tras ampliar o regularizar puedes reintentar con la misma Idempotency-Key. Se conservan las consultas y descargas.

El flujo habitual es crear un borrador, emitirlo y entregar la copia vigente con PDF y QR antes del transporte. El estado incompleto procede del asistente web y no puede emitirse hasta confirmar el borrador. Cerrar un documento es opcional. Los hitos son seguimiento opcional. Cada rectificación conserva las versiones anteriores y requiere entregar la nueva copia.

Emitir o rectificar no envía correos automáticamente. Para compartir la versión vigente, usa POST /documentos/{documento}/versiones/{version}/distribuir con los datos del destinatario. La respuesta 202 identifica la solicitud y su resultado puede consultarse en las versiones del documento. Solicitar un correo no acredita la entrega al conductor.

Los catálogos son contactos y vehículos. Los papeles pueden enviarse manualmente o vinculados a un contacto. Cada envío usa lugares de carga y descarga estructurados, con campos como carga_codigo_postal y fecha_descarga. Los campos antiguos origen, destino, fecha_transporte y conductor_id devuelven 422, incluso con null.

Al cerrar una empresa se bloquean los documentos nuevos, pero se pueden entregar, corregir y cerrar los ya emitidos. Una vez cerrados, la empresa pasa a archivo y conserva consultas, versiones y descargas.

Referencia de operaciones

Catalogos

GET /api/v1/catalogos/{tipo}

Lista contactos o vehiculos

Pagina los resultados; sin el filtro activo se incluyen registros activos e inactivos.

Capacidad requerida: catalogos:leer

Parámetros de ruta

ParámetroTipoUsoDetalles

tipo string Obligatorio

Valores: contactos, vehiculos

Parámetros de consulta

ParámetroTipoUsoDetalles

page integer Opcional

Mínimo: 1 · Predeterminado: 1

buscar string Opcional

Máximo: 255

activo boolean Opcional

por_pagina integer Opcional

Valores: 10, 20, 50, 100 · Predeterminado: 20

Petición cURL

curl -X GET 'https://EMPRESA.DOMINIO/api/v1/catalogos/contactos' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN'

Respuestas

200 Pagina del catalogo application/json

ParámetroTipoUsoDetalles

data array Obligatorio

meta object Obligatorio

meta.pagina integer Obligatorio

meta.por_pagina integer Obligatorio

meta.total integer Obligatorio

meta.ultima_pagina integer Obligatorio

{
    "data": [
        {
            "id": 1,
            "nombre": "Transportes Ejemplo SL",
            "identificacion_fiscal": "B12345678",
            "activo": true
        }
    ],
    "meta": {
        "pagina": 1,
        "por_pagina": 20,
        "total": 1,
        "ultima_pagina": 1
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

POST /api/v1/catalogos/{tipo}

Crea un registro activo del catalogo

Capacidad requerida: catalogos:gestionar

Parámetros de ruta

ParámetroTipoUsoDetalles

tipo string Obligatorio

Valores: contactos, vehiculos

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Cuerpo JSON

ContactoEntrada

Contacto sin clasificacion, utilizable en todos los papeles del documento. El identificador fiscal no es unico para permitir establecimientos.

ParámetroTipoUsoDetalles

nombre string Obligatorio

Máximo: 255

nombre_comercial string | null Opcional

Máximo: 255

identificacion_fiscal string Obligatorio

Máximo: 50

domicilio string | null Opcional

Máximo: 255

codigo_postal string | null Opcional

Máximo: 20

localidad string | null Opcional

Máximo: 255

provincia string | null Opcional

Máximo: 255

pais string | null Opcional

Máximo: 255 · Predeterminado: Espana

email string | null (email) Opcional

telefono string | null Opcional

Máximo: 30

activo boolean Opcional

Predeterminado: true

por_defecto_cargador boolean Opcional

Predeterminado como cargador en el asistente. Sustituye al anterior; requiere contacto activo. Omitir conserva la preferencia.

por_defecto_transportista boolean Opcional

Predeterminado como transportista en el asistente, independiente del cargador. Desactivar elimina ambas preferencias sin escoger otro contacto.

VehiculoEntrada

ParámetroTipoUsoDetalles

alias string | null Opcional

Máximo: 255

conductor_nombre string | null Opcional

Máximo: 255

conductor_telefono string | null Opcional

Máximo: 30

conductor_email string | null (email) Opcional

Máximo: 255

matricula string Obligatorio

Máximo: 30

con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Al crear se deduce de su matrícula si se omite; al actualizar se conserva.

matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

tipo string | null Opcional

Máximo: 50

transportista_id integer | null Opcional

Contacto asociado al vehiculo. Nombre conservado por compatibilidad; no clasifica al contacto ni concede acceso a documentos.

activo boolean Opcional

Predeterminado: true

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/catalogos/contactos' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ejemplo-crearRegistroCatalogo' \
  --data '{
    "nombre": "Transportes Ejemplo SL",
    "identificacion_fiscal": "B12345678",
    "domicilio": "Calle del Puerto 12",
    "codigo_postal": "28001",
    "localidad": "Madrid",
    "pais": "Espana"
}'

JSON de ejemplo

{
    "nombre": "Transportes Ejemplo SL",
    "identificacion_fiscal": "B12345678",
    "domicilio": "Calle del Puerto 12",
    "codigo_postal": "28001",
    "localidad": "Madrid",
    "pais": "Espana"
}

Respuestas

201 Registro creado application/json

ParámetroTipoUsoDetalles

data Contacto | Vehiculo Obligatorio

{
    "data": {
        "id": 1,
        "nombre": "Transportes Ejemplo SL",
        "identificacion_fiscal": "B12345678",
        "activo": true
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

409 Solicitud concurrente, estado incompatible, cupo agotado, pago pendiente o clave reutilizada con otros datos. Los errores con codigo cupo_agotado o pago_pendiente permiten reintentar con la misma clave y solicitud después de ampliar o regularizar, sin cerrar la idempotencia. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

GET /api/v1/catalogos/{tipo}/{identificador}

Consulta un registro del catalogo

Capacidad requerida: catalogos:leer

Parámetros de ruta

ParámetroTipoUsoDetalles

tipo string Obligatorio

Valores: contactos, vehiculos

identificador integer Obligatorio

Mínimo: 1

Petición cURL

curl -X GET 'https://EMPRESA.DOMINIO/api/v1/catalogos/contactos/1' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN'

Respuestas

200 Registro del catalogo application/json

ParámetroTipoUsoDetalles

data Contacto | Vehiculo Obligatorio

{
    "data": {
        "id": 1,
        "nombre": "Transportes Ejemplo SL",
        "identificacion_fiscal": "B12345678",
        "activo": true
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

PUT /api/v1/catalogos/{tipo}/{identificador}

Actualiza los datos de un registro sin borrar documentos emitidos

Capacidad requerida: catalogos:gestionar

Parámetros de ruta

ParámetroTipoUsoDetalles

tipo string Obligatorio

Valores: contactos, vehiculos

identificador integer Obligatorio

Mínimo: 1

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Cuerpo JSON

ContactoEntrada

Contacto sin clasificacion, utilizable en todos los papeles del documento. El identificador fiscal no es unico para permitir establecimientos.

ParámetroTipoUsoDetalles

nombre string Obligatorio

Máximo: 255

nombre_comercial string | null Opcional

Máximo: 255

identificacion_fiscal string Obligatorio

Máximo: 50

domicilio string | null Opcional

Máximo: 255

codigo_postal string | null Opcional

Máximo: 20

localidad string | null Opcional

Máximo: 255

provincia string | null Opcional

Máximo: 255

pais string | null Opcional

Máximo: 255 · Predeterminado: Espana

email string | null (email) Opcional

telefono string | null Opcional

Máximo: 30

activo boolean Opcional

Predeterminado: true

por_defecto_cargador boolean Opcional

Predeterminado como cargador en el asistente. Sustituye al anterior; requiere contacto activo. Omitir conserva la preferencia.

por_defecto_transportista boolean Opcional

Predeterminado como transportista en el asistente, independiente del cargador. Desactivar elimina ambas preferencias sin escoger otro contacto.

VehiculoEntrada

ParámetroTipoUsoDetalles

alias string | null Opcional

Máximo: 255

conductor_nombre string | null Opcional

Máximo: 255

conductor_telefono string | null Opcional

Máximo: 30

conductor_email string | null (email) Opcional

Máximo: 255

matricula string Obligatorio

Máximo: 30

con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Al crear se deduce de su matrícula si se omite; al actualizar se conserva.

matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

tipo string | null Opcional

Máximo: 50

transportista_id integer | null Opcional

Contacto asociado al vehiculo. Nombre conservado por compatibilidad; no clasifica al contacto ni concede acceso a documentos.

activo boolean Opcional

Predeterminado: true

Petición cURL

curl -X PUT 'https://EMPRESA.DOMINIO/api/v1/catalogos/contactos/1' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ejemplo-actualizarRegistroCatalogo' \
  --data '{
    "nombre": "Transportes Ejemplo SL",
    "identificacion_fiscal": "B12345678",
    "domicilio": "Calle del Puerto 12",
    "codigo_postal": "28001",
    "localidad": "Madrid",
    "pais": "Espana"
}'

JSON de ejemplo

{
    "nombre": "Transportes Ejemplo SL",
    "identificacion_fiscal": "B12345678",
    "domicilio": "Calle del Puerto 12",
    "codigo_postal": "28001",
    "localidad": "Madrid",
    "pais": "Espana"
}

Respuestas

200 Registro actualizado application/json

ParámetroTipoUsoDetalles

data Contacto | Vehiculo Obligatorio

{
    "data": {
        "id": 1,
        "nombre": "Transportes Ejemplo SL",
        "identificacion_fiscal": "B12345678",
        "activo": true
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

PATCH /api/v1/catalogos/{tipo}/{identificador}

Actualiza parcialmente un registro del catalogo

Capacidad requerida: catalogos:gestionar

Parámetros de ruta

ParámetroTipoUsoDetalles

tipo string Obligatorio

Valores: contactos, vehiculos

identificador integer Obligatorio

Mínimo: 1

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Cuerpo JSON

ContactoEntrada

Contacto sin clasificacion, utilizable en todos los papeles del documento. El identificador fiscal no es unico para permitir establecimientos.

ParámetroTipoUsoDetalles

nombre string Obligatorio

Máximo: 255

nombre_comercial string | null Opcional

Máximo: 255

identificacion_fiscal string Obligatorio

Máximo: 50

domicilio string | null Opcional

Máximo: 255

codigo_postal string | null Opcional

Máximo: 20

localidad string | null Opcional

Máximo: 255

provincia string | null Opcional

Máximo: 255

pais string | null Opcional

Máximo: 255 · Predeterminado: Espana

email string | null (email) Opcional

telefono string | null Opcional

Máximo: 30

activo boolean Opcional

Predeterminado: true

por_defecto_cargador boolean Opcional

Predeterminado como cargador en el asistente. Sustituye al anterior; requiere contacto activo. Omitir conserva la preferencia.

por_defecto_transportista boolean Opcional

Predeterminado como transportista en el asistente, independiente del cargador. Desactivar elimina ambas preferencias sin escoger otro contacto.

VehiculoEntrada

ParámetroTipoUsoDetalles

alias string | null Opcional

Máximo: 255

conductor_nombre string | null Opcional

Máximo: 255

conductor_telefono string | null Opcional

Máximo: 30

conductor_email string | null (email) Opcional

Máximo: 255

matricula string Obligatorio

Máximo: 30

con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Al crear se deduce de su matrícula si se omite; al actualizar se conserva.

matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

tipo string | null Opcional

Máximo: 50

transportista_id integer | null Opcional

Contacto asociado al vehiculo. Nombre conservado por compatibilidad; no clasifica al contacto ni concede acceso a documentos.

activo boolean Opcional

Predeterminado: true

Petición cURL

curl -X PATCH 'https://EMPRESA.DOMINIO/api/v1/catalogos/contactos/1' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ejemplo-actualizarParcialRegistroCatalogo' \
  --data '{
    "nombre": "Transportes Ejemplo SL",
    "identificacion_fiscal": "B12345678",
    "domicilio": "Calle del Puerto 12",
    "codigo_postal": "28001",
    "localidad": "Madrid",
    "pais": "Espana"
}'

JSON de ejemplo

{
    "nombre": "Transportes Ejemplo SL",
    "identificacion_fiscal": "B12345678",
    "domicilio": "Calle del Puerto 12",
    "codigo_postal": "28001",
    "localidad": "Madrid",
    "pais": "Espana"
}

Respuestas

200 Registro actualizado application/json

ParámetroTipoUsoDetalles

data Contacto | Vehiculo Obligatorio

{
    "data": {
        "id": 1,
        "nombre": "Transportes Ejemplo SL",
        "identificacion_fiscal": "B12345678",
        "activo": true
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

POST /api/v1/catalogos/{tipo}/{identificador}/desactivar

Desactiva un registro sin eliminarlo

Capacidad requerida: catalogos:gestionar

Parámetros de ruta

ParámetroTipoUsoDetalles

tipo string Obligatorio

Valores: contactos, vehiculos

identificador integer Obligatorio

Mínimo: 1

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/catalogos/contactos/1/desactivar' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Idempotency-Key: ejemplo-desactivarRegistroCatalogo'

Respuestas

200 Registro desactivado application/json

ParámetroTipoUsoDetalles

data Contacto | Vehiculo Obligatorio

{
    "data": {
        "id": 1,
        "nombre": "Transportes Ejemplo SL",
        "identificacion_fiscal": "B12345678",
        "activo": true
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

Referencia de operaciones

Documentos

GET /api/v1/documentos

Lista documentos y borradores

Capacidad requerida: deca:leer

Parámetros de consulta

ParámetroTipoUsoDetalles

estado string Opcional

Valores: incompleto, borrador, emitido, archivado, descartado

id_externo string Opcional

Busca el identificador externo solo entre documentos creados por esta integracion.

Mínimo: 1 · Máximo: 160

page integer Opcional

Mínimo: 1 · Predeterminado: 1

por_pagina integer Opcional

Valores: 10, 20, 50, 100 · Predeterminado: 20

Petición cURL

curl -X GET 'https://EMPRESA.DOMINIO/api/v1/documentos' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN'

Respuestas

200 Pagina de documentos application/json

ParámetroTipoUsoDetalles

data array Opcional

data[].id string (uuid) Opcional

data[].estado string Opcional

Valores: incompleto, borrador, emitido, archivado, descartado

data[].estado_etiqueta string Opcional

Valores: Incompleto, Borrador, Emitido, Cerrado

data[].referencia string | null Opcional

data[].version_actual integer Opcional

data[].revision_edicion integer Opcional

Revision necesaria para sustituir un borrador.

data[].payload_hash string | null Opcional

Huella de los datos enviados por la integracion.

data[].version_emitida string | null (uuid) Opcional

data[].creado_en string | null (date-time) Opcional

data[].cargador_id integer | null Opcional

data[].transportista_id integer | null Opcional

data[].cargador object Opcional

data[].transportista object Opcional

data[].envios array Opcional

data[].envios[].carga_contacto_id integer | null Opcional

data[].envios[].carga_nombre string Opcional

Máximo: 255

data[].envios[].carga_direccion string Opcional

Máximo: 255

data[].envios[].carga_codigo_postal string Opcional

Máximo: 20

data[].envios[].carga_localidad string Opcional

Máximo: 255

data[].envios[].carga_provincia string | null Opcional

Máximo: 255

data[].envios[].carga_pais string Opcional

Máximo: 255

data[].envios[].fecha_carga string (date) Obligatorio

data[].envios[].descarga_contacto_id integer | null Opcional

data[].envios[].descarga_nombre string Opcional

Máximo: 255

data[].envios[].descarga_direccion string Opcional

Máximo: 255

data[].envios[].descarga_codigo_postal string Opcional

Máximo: 20

data[].envios[].descarga_localidad string Opcional

Máximo: 255

data[].envios[].descarga_provincia string | null Opcional

Máximo: 255

data[].envios[].descarga_pais string Opcional

Máximo: 255

data[].envios[].fecha_descarga string (date) Obligatorio

data[].envios[].naturaleza_mercancia string Obligatorio

Máximo: 10000

data[].envios[].peso_kg number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data[].envios[].magnitud_alternativa number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data[].envios[].unidad_magnitud string | null Opcional

Máximo: 30

data[].envios[].requiere_autorizacion_especial boolean Opcional

Indica que este transporte requiere autorización especial de circulación. Al emitir o rectificar exige su identificación.

data[].envios[].autorizacion_especial string | null Opcional

Máximo: 255

data[].envios[].observaciones string | null Opcional

Máximo: 10000

data[].envios[].vehiculo_id integer | null Opcional

data[].envios[].matricula string | null Opcional

Obligatoria para emitir. Editable sin vehiculo del catalogo.

Máximo: 30

data[].envios[].con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Si se omite, se copia o conserva según el vehículo y el envío.

data[].envios[].matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

data[].envios[].conductor_nombre string | null Opcional

Máximo: 255

data[].envios[].conductor_telefono string | null Opcional

Máximo: 30

data[].envios[].conductor_email string | null (email) Opcional

Máximo: 255

data[].envios[].id string (uuid) Opcional

data[].envios[].estado_servicio string Opcional

data[].envios[].inicio_efectivo_en string | null (date-time) Opcional

data[].envios[].fin_efectivo_en string | null (date-time) Opcional

data[].envios[].no_realizado_en string | null (date-time) Opcional

data[].envios[].motivo_cierre string | null Opcional

data[].versiones array Opcional

data[].versiones[].id string (uuid) Opcional

data[].versiones[].numero integer Opcional

data[].versiones[].tipo string Opcional

Valores: emision, correccion, rectificacion

data[].versiones[].motivo string | null Opcional

data[].versiones[].emitida_en string | null (date-time) Opcional

data[].versiones[].sha256 string | null Opcional

Patrón: ^[a-f0-9]{64}$

data[].versiones[].pdf_url string | null (uri) Opcional

data[].versiones[].correos array Opcional

meta object Opcional

meta.pagina integer Obligatorio

meta.por_pagina integer Obligatorio

meta.total integer Obligatorio

meta.ultima_pagina integer Obligatorio

{
    "data": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174001",
            "estado": "borrador",
            "estado_etiqueta": "Borrador",
            "referencia": "PED-2026-014",
            "version_actual": 0
        }
    ],
    "meta": {
        "pagina": 1,
        "por_pagina": 20,
        "total": 1,
        "ultima_pagina": 1
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

POST /api/v1/documentos

Crea un borrador con uno o varios envios del mismo cargador y transportista

No emite el DeCA. Cada envio requiere peso o magnitud alternativa, pero no ambos.

Capacidad requerida: deca:borradores:gestionar

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Cuerpo JSON

ParámetroTipoUsoDetalles

id_externo string | null Opcional

Identificador externo unico para esta integracion y empresa.

Máximo: 160

referencia string | null Opcional

Máximo: 80

transportista_id integer | null Opcional

Contacto vinculado como transportista. Omitir o null permite datos manuales sin acceso para equipos.

cargador_id integer | null Opcional

Contacto vinculado como cargador. Omitir o null permite datos manuales; no aplica ningun predeterminado en la API.

cargador object Opcional

Con ID se copian los campos omitidos y prevalecen los enviados. Sin ID se requieren nombre, identificacion_fiscal y domicilio. Los datos se congelan en el documento, sin modificar el contacto.

cargador.nombre string Opcional

Máximo: 255

cargador.identificacion_fiscal string Opcional

Máximo: 50

cargador.domicilio string Opcional

Máximo: 255

cargador.email string | null (email) Opcional

cargador.telefono string | null Opcional

Máximo: 30

transportista object Opcional

Con ID se copian los campos omitidos y prevalecen los enviados. Sin ID se requieren nombre, identificacion_fiscal y domicilio. Los datos se congelan en el documento, sin modificar el contacto.

transportista.nombre string Opcional

Máximo: 255

transportista.identificacion_fiscal string Opcional

Máximo: 50

transportista.domicilio string Opcional

Máximo: 255

transportista.email string | null (email) Opcional

transportista.telefono string | null Opcional

Máximo: 30

envios array Obligatorio

Mínimo elementos: 1 · Máximo elementos: 100

envios[].carga_contacto_id integer | null Opcional

envios[].carga_nombre string Opcional

Máximo: 255

envios[].carga_direccion string Opcional

Máximo: 255

envios[].carga_codigo_postal string Opcional

Máximo: 20

envios[].carga_localidad string Opcional

Máximo: 255

envios[].carga_provincia string | null Opcional

Máximo: 255

envios[].carga_pais string Opcional

Máximo: 255

envios[].fecha_carga string (date) Obligatorio

envios[].descarga_contacto_id integer | null Opcional

envios[].descarga_nombre string Opcional

Máximo: 255

envios[].descarga_direccion string Opcional

Máximo: 255

envios[].descarga_codigo_postal string Opcional

Máximo: 20

envios[].descarga_localidad string Opcional

Máximo: 255

envios[].descarga_provincia string | null Opcional

Máximo: 255

envios[].descarga_pais string Opcional

Máximo: 255

envios[].fecha_descarga string (date) Obligatorio

envios[].naturaleza_mercancia string Obligatorio

Máximo: 10000

envios[].peso_kg number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

envios[].magnitud_alternativa number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

envios[].unidad_magnitud string | null Opcional

Máximo: 30

envios[].requiere_autorizacion_especial boolean Opcional

Indica que este transporte requiere autorización especial de circulación. Al emitir o rectificar exige su identificación.

envios[].autorizacion_especial string | null Opcional

Máximo: 255

envios[].observaciones string | null Opcional

Máximo: 10000

envios[].vehiculo_id integer | null Opcional

envios[].matricula string | null Opcional

Obligatoria para emitir. Editable sin vehiculo del catalogo.

Máximo: 30

envios[].con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Si se omite, se copia o conserva según el vehículo y el envío.

envios[].matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

envios[].conductor_nombre string | null Opcional

Máximo: 255

envios[].conductor_telefono string | null Opcional

Máximo: 30

envios[].conductor_email string | null (email) Opcional

Máximo: 255

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/documentos' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ejemplo-crearBorrador' \
  --data '{
    "referencia": "PED-2026-014",
    "cargador": {
        "nombre": "Almacenes Ejemplo SL",
        "identificacion_fiscal": "B87654321",
        "domicilio": "Calle Mayor 20, Madrid"
    },
    "transportista": {
        "nombre": "Transportes Ejemplo SL",
        "identificacion_fiscal": "B12345678",
        "domicilio": "Calle del Puerto 12, Madrid"
    },
    "envios": [
        {
            "carga_nombre": "Almacén central",
            "carga_direccion": "Calle Mayor 20",
            "carga_codigo_postal": "28001",
            "carga_localidad": "Madrid",
            "carga_pais": "Espana",
            "fecha_carga": "2026-10-14",
            "descarga_nombre": "Centro de destino",
            "descarga_direccion": "Avenida del Mar 8",
            "descarga_codigo_postal": "46001",
            "descarga_localidad": "Valencia",
            "descarga_pais": "Espana",
            "fecha_descarga": "2026-10-15",
            "naturaleza_mercancia": "Material de embalaje",
            "peso_kg": 1250,
            "matricula": "1234 ABC",
            "con_remolque": false
        }
    ]
}'

JSON de ejemplo

{
    "referencia": "PED-2026-014",
    "cargador": {
        "nombre": "Almacenes Ejemplo SL",
        "identificacion_fiscal": "B87654321",
        "domicilio": "Calle Mayor 20, Madrid"
    },
    "transportista": {
        "nombre": "Transportes Ejemplo SL",
        "identificacion_fiscal": "B12345678",
        "domicilio": "Calle del Puerto 12, Madrid"
    },
    "envios": [
        {
            "carga_nombre": "Almacén central",
            "carga_direccion": "Calle Mayor 20",
            "carga_codigo_postal": "28001",
            "carga_localidad": "Madrid",
            "carga_pais": "Espana",
            "fecha_carga": "2026-10-14",
            "descarga_nombre": "Centro de destino",
            "descarga_direccion": "Avenida del Mar 8",
            "descarga_codigo_postal": "46001",
            "descarga_localidad": "Valencia",
            "descarga_pais": "Espana",
            "fecha_descarga": "2026-10-15",
            "naturaleza_mercancia": "Material de embalaje",
            "peso_kg": 1250,
            "matricula": "1234 ABC",
            "con_remolque": false
        }
    ]
}

Respuestas

201 Borrador creado application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id string (uuid) Opcional

data.estado string Opcional

Valores: incompleto, borrador, emitido, archivado, descartado

data.estado_etiqueta string Opcional

Valores: Incompleto, Borrador, Emitido, Cerrado

data.referencia string | null Opcional

data.version_actual integer Opcional

data.revision_edicion integer Opcional

Revision necesaria para sustituir un borrador.

data.payload_hash string | null Opcional

Huella de los datos enviados por la integracion.

data.version_emitida string | null (uuid) Opcional

data.creado_en string | null (date-time) Opcional

data.cargador_id integer | null Opcional

data.transportista_id integer | null Opcional

data.cargador object Opcional

data.transportista object Opcional

data.envios array Opcional

data.envios[].carga_contacto_id integer | null Opcional

data.envios[].carga_nombre string Opcional

Máximo: 255

data.envios[].carga_direccion string Opcional

Máximo: 255

data.envios[].carga_codigo_postal string Opcional

Máximo: 20

data.envios[].carga_localidad string Opcional

Máximo: 255

data.envios[].carga_provincia string | null Opcional

Máximo: 255

data.envios[].carga_pais string Opcional

Máximo: 255

data.envios[].fecha_carga string (date) Obligatorio

data.envios[].descarga_contacto_id integer | null Opcional

data.envios[].descarga_nombre string Opcional

Máximo: 255

data.envios[].descarga_direccion string Opcional

Máximo: 255

data.envios[].descarga_codigo_postal string Opcional

Máximo: 20

data.envios[].descarga_localidad string Opcional

Máximo: 255

data.envios[].descarga_provincia string | null Opcional

Máximo: 255

data.envios[].descarga_pais string Opcional

Máximo: 255

data.envios[].fecha_descarga string (date) Obligatorio

data.envios[].naturaleza_mercancia string Obligatorio

Máximo: 10000

data.envios[].peso_kg number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].magnitud_alternativa number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].unidad_magnitud string | null Opcional

Máximo: 30

data.envios[].requiere_autorizacion_especial boolean Opcional

Indica que este transporte requiere autorización especial de circulación. Al emitir o rectificar exige su identificación.

data.envios[].autorizacion_especial string | null Opcional

Máximo: 255

data.envios[].observaciones string | null Opcional

Máximo: 10000

data.envios[].vehiculo_id integer | null Opcional

data.envios[].matricula string | null Opcional

Obligatoria para emitir. Editable sin vehiculo del catalogo.

Máximo: 30

data.envios[].con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Si se omite, se copia o conserva según el vehículo y el envío.

data.envios[].matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

data.envios[].conductor_nombre string | null Opcional

Máximo: 255

data.envios[].conductor_telefono string | null Opcional

Máximo: 30

data.envios[].conductor_email string | null (email) Opcional

Máximo: 255

data.envios[].id string (uuid) Opcional

data.envios[].estado_servicio string Opcional

data.envios[].inicio_efectivo_en string | null (date-time) Opcional

data.envios[].fin_efectivo_en string | null (date-time) Opcional

data.envios[].no_realizado_en string | null (date-time) Opcional

data.envios[].motivo_cierre string | null Opcional

data.versiones array Opcional

data.versiones[].id string (uuid) Opcional

data.versiones[].numero integer Opcional

data.versiones[].tipo string Opcional

Valores: emision, correccion, rectificacion

data.versiones[].motivo string | null Opcional

data.versiones[].emitida_en string | null (date-time) Opcional

data.versiones[].sha256 string | null Opcional

Patrón: ^[a-f0-9]{64}$

data.versiones[].pdf_url string | null (uri) Opcional

data.versiones[].correos array Opcional

{
    "data": {
        "id": "123e4567-e89b-12d3-a456-426614174001",
        "estado": "borrador",
        "estado_etiqueta": "Borrador",
        "referencia": "PED-2026-014",
        "version_actual": 0,
        "revision_edicion": 1,
        "envios": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "fecha_carga": "2026-10-14",
                "fecha_descarga": "2026-10-15"
            }
        ]
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

POST /api/v1/documentos/{documento}/emitir

Emite un borrador como primera version inmutable con PDF y QR directos

La emision inicial consume una unidad; los reintentos con la misma clave no duplican version ni consumo.

Capacidad requerida: deca:emitir

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000/emitir' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Idempotency-Key: ejemplo-emitirDocumento'

Respuestas

200 Documento emitido application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id string (uuid) Opcional

data.estado string Opcional

Valores: incompleto, borrador, emitido, archivado, descartado

data.estado_etiqueta string Opcional

Valores: Incompleto, Borrador, Emitido, Cerrado

data.referencia string | null Opcional

data.version_actual integer Opcional

data.revision_edicion integer Opcional

Revision necesaria para sustituir un borrador.

data.payload_hash string | null Opcional

Huella de los datos enviados por la integracion.

data.version_emitida string | null (uuid) Opcional

data.creado_en string | null (date-time) Opcional

data.cargador_id integer | null Opcional

data.transportista_id integer | null Opcional

data.cargador object Opcional

data.transportista object Opcional

data.envios array Opcional

data.envios[].carga_contacto_id integer | null Opcional

data.envios[].carga_nombre string Opcional

Máximo: 255

data.envios[].carga_direccion string Opcional

Máximo: 255

data.envios[].carga_codigo_postal string Opcional

Máximo: 20

data.envios[].carga_localidad string Opcional

Máximo: 255

data.envios[].carga_provincia string | null Opcional

Máximo: 255

data.envios[].carga_pais string Opcional

Máximo: 255

data.envios[].fecha_carga string (date) Obligatorio

data.envios[].descarga_contacto_id integer | null Opcional

data.envios[].descarga_nombre string Opcional

Máximo: 255

data.envios[].descarga_direccion string Opcional

Máximo: 255

data.envios[].descarga_codigo_postal string Opcional

Máximo: 20

data.envios[].descarga_localidad string Opcional

Máximo: 255

data.envios[].descarga_provincia string | null Opcional

Máximo: 255

data.envios[].descarga_pais string Opcional

Máximo: 255

data.envios[].fecha_descarga string (date) Obligatorio

data.envios[].naturaleza_mercancia string Obligatorio

Máximo: 10000

data.envios[].peso_kg number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].magnitud_alternativa number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].unidad_magnitud string | null Opcional

Máximo: 30

data.envios[].requiere_autorizacion_especial boolean Opcional

Indica que este transporte requiere autorización especial de circulación. Al emitir o rectificar exige su identificación.

data.envios[].autorizacion_especial string | null Opcional

Máximo: 255

data.envios[].observaciones string | null Opcional

Máximo: 10000

data.envios[].vehiculo_id integer | null Opcional

data.envios[].matricula string | null Opcional

Obligatoria para emitir. Editable sin vehiculo del catalogo.

Máximo: 30

data.envios[].con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Si se omite, se copia o conserva según el vehículo y el envío.

data.envios[].matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

data.envios[].conductor_nombre string | null Opcional

Máximo: 255

data.envios[].conductor_telefono string | null Opcional

Máximo: 30

data.envios[].conductor_email string | null (email) Opcional

Máximo: 255

data.envios[].id string (uuid) Opcional

data.envios[].estado_servicio string Opcional

data.envios[].inicio_efectivo_en string | null (date-time) Opcional

data.envios[].fin_efectivo_en string | null (date-time) Opcional

data.envios[].no_realizado_en string | null (date-time) Opcional

data.envios[].motivo_cierre string | null Opcional

data.versiones array Opcional

data.versiones[].id string (uuid) Opcional

data.versiones[].numero integer Opcional

data.versiones[].tipo string Opcional

Valores: emision, correccion, rectificacion

data.versiones[].motivo string | null Opcional

data.versiones[].emitida_en string | null (date-time) Opcional

data.versiones[].sha256 string | null Opcional

Patrón: ^[a-f0-9]{64}$

data.versiones[].pdf_url string | null (uri) Opcional

data.versiones[].correos array Opcional

{
    "data": {
        "id": "123e4567-e89b-12d3-a456-426614174001",
        "estado": "emitido",
        "estado_etiqueta": "Emitido",
        "referencia": "PED-2026-014",
        "version_actual": 1,
        "version_emitida": "123e4567-e89b-12d3-a456-426614174002",
        "versiones": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174002",
                "numero": 1,
                "tipo": "emision",
                "pdf_url": "https://empresa.ejemplo.invalid/documentos/123e4567-e89b-12d3-a456-426614174001/versiones/123e4567-e89b-12d3-a456-426614174002/pdf"
            }
        ]
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

POST /api/v1/documentos/{documento}/rectificaciones

Emite una rectificacion completa versionada con motivo obligatorio

No requiere cierre previo ni hitos; conserva los envios originales y el historial de PDF. Genera una nueva URL y QR y prepara su distribucion; debe entregarse la nueva copia al conductor. Una integracion propietaria puede incluir origen_hash y version_esperada para registrar su huella de origen y evitar rectificaciones duplicadas.

Capacidad requerida: deca:corregir

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Cuerpo JSON

Los papeles omitidos conservan sus vinculos y datos anteriores. Un ID nuevo copia el contacto nuevo, con reemplazos inline. Enviar null desvincula el papel y requiere los datos manuales. Deben incluirse todos los envios originales.

ParámetroTipoUsoDetalles

motivo string Obligatorio

Mínimo: 5 · Máximo: 2000

origen_hash string Opcional

Huella opcional del contenido de origen; requiere version_esperada y ser la integracion que creo el documento.

Patrón: ^[a-f0-9]{64}$

version_esperada integer Opcional

Version actual esperada; requiere origen_hash.

Mínimo: 1

referencia string | null Opcional

Máximo: 80

cargador_id integer | null Opcional

transportista_id integer | null Opcional

cargador object Opcional

Con ID se copian los campos omitidos y prevalecen los enviados. Sin ID se requieren nombre, identificacion_fiscal y domicilio. Los datos se congelan en el documento, sin modificar el contacto.

cargador.nombre string Opcional

Máximo: 255

cargador.identificacion_fiscal string Opcional

Máximo: 50

cargador.domicilio string Opcional

Máximo: 255

cargador.email string | null (email) Opcional

cargador.telefono string | null Opcional

Máximo: 30

transportista object Opcional

Con ID se copian los campos omitidos y prevalecen los enviados. Sin ID se requieren nombre, identificacion_fiscal y domicilio. Los datos se congelan en el documento, sin modificar el contacto.

transportista.nombre string Opcional

Máximo: 255

transportista.identificacion_fiscal string Opcional

Máximo: 50

transportista.domicilio string Opcional

Máximo: 255

transportista.email string | null (email) Opcional

transportista.telefono string | null Opcional

Máximo: 30

envios array Obligatorio

Debe incluir exactamente los envios originales.

Mínimo elementos: 1 · Máximo elementos: 100

envios[].carga_contacto_id integer | null Opcional

envios[].carga_nombre string Opcional

Máximo: 255

envios[].carga_direccion string Opcional

Máximo: 255

envios[].carga_codigo_postal string Opcional

Máximo: 20

envios[].carga_localidad string Opcional

Máximo: 255

envios[].carga_provincia string | null Opcional

Máximo: 255

envios[].carga_pais string Opcional

Máximo: 255

envios[].fecha_carga string (date) Obligatorio

envios[].descarga_contacto_id integer | null Opcional

envios[].descarga_nombre string Opcional

Máximo: 255

envios[].descarga_direccion string Opcional

Máximo: 255

envios[].descarga_codigo_postal string Opcional

Máximo: 20

envios[].descarga_localidad string Opcional

Máximo: 255

envios[].descarga_provincia string | null Opcional

Máximo: 255

envios[].descarga_pais string Opcional

Máximo: 255

envios[].fecha_descarga string (date) Obligatorio

envios[].naturaleza_mercancia string Obligatorio

Máximo: 10000

envios[].peso_kg number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

envios[].magnitud_alternativa number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

envios[].unidad_magnitud string | null Opcional

Máximo: 30

envios[].requiere_autorizacion_especial boolean Opcional

Indica que este transporte requiere autorización especial de circulación. Al emitir o rectificar exige su identificación.

envios[].autorizacion_especial string | null Opcional

Máximo: 255

envios[].observaciones string | null Opcional

Máximo: 10000

envios[].vehiculo_id integer | null Opcional

envios[].matricula string | null Opcional

Obligatoria para emitir. Editable sin vehiculo del catalogo.

Máximo: 30

envios[].con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Si se omite, se copia o conserva según el vehículo y el envío.

envios[].matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

envios[].conductor_nombre string | null Opcional

Máximo: 255

envios[].conductor_telefono string | null Opcional

Máximo: 30

envios[].conductor_email string | null (email) Opcional

Máximo: 255

envios[].id string (uuid) Obligatorio

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000/rectificaciones' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ejemplo-rectificarDocumento' \
  --data '{
    "motivo": "Se corrige la fecha de descarga comunicada.",
    "envios": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "carga_nombre": "Almacén central",
            "carga_direccion": "Calle Mayor 20",
            "carga_codigo_postal": "28001",
            "carga_localidad": "Madrid",
            "carga_pais": "Espana",
            "fecha_carga": "2026-10-14",
            "descarga_nombre": "Centro de destino",
            "descarga_direccion": "Avenida del Mar 8",
            "descarga_codigo_postal": "46001",
            "descarga_localidad": "Valencia",
            "descarga_pais": "Espana",
            "fecha_descarga": "2026-10-16",
            "naturaleza_mercancia": "Material de embalaje",
            "peso_kg": 1250,
            "matricula": "1234 ABC"
        }
    ]
}'

JSON de ejemplo

{
    "motivo": "Se corrige la fecha de descarga comunicada.",
    "envios": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "carga_nombre": "Almacén central",
            "carga_direccion": "Calle Mayor 20",
            "carga_codigo_postal": "28001",
            "carga_localidad": "Madrid",
            "carga_pais": "Espana",
            "fecha_carga": "2026-10-14",
            "descarga_nombre": "Centro de destino",
            "descarga_direccion": "Avenida del Mar 8",
            "descarga_codigo_postal": "46001",
            "descarga_localidad": "Valencia",
            "descarga_pais": "Espana",
            "fecha_descarga": "2026-10-16",
            "naturaleza_mercancia": "Material de embalaje",
            "peso_kg": 1250,
            "matricula": "1234 ABC"
        }
    ]
}

Respuestas

200 Nueva version rectificada application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id string (uuid) Opcional

data.estado string Opcional

Valores: incompleto, borrador, emitido, archivado, descartado

data.estado_etiqueta string Opcional

Valores: Incompleto, Borrador, Emitido, Cerrado

data.referencia string | null Opcional

data.version_actual integer Opcional

data.revision_edicion integer Opcional

Revision necesaria para sustituir un borrador.

data.payload_hash string | null Opcional

Huella de los datos enviados por la integracion.

data.version_emitida string | null (uuid) Opcional

data.creado_en string | null (date-time) Opcional

data.cargador_id integer | null Opcional

data.transportista_id integer | null Opcional

data.cargador object Opcional

data.transportista object Opcional

data.envios array Opcional

data.envios[].carga_contacto_id integer | null Opcional

data.envios[].carga_nombre string Opcional

Máximo: 255

data.envios[].carga_direccion string Opcional

Máximo: 255

data.envios[].carga_codigo_postal string Opcional

Máximo: 20

data.envios[].carga_localidad string Opcional

Máximo: 255

data.envios[].carga_provincia string | null Opcional

Máximo: 255

data.envios[].carga_pais string Opcional

Máximo: 255

data.envios[].fecha_carga string (date) Obligatorio

data.envios[].descarga_contacto_id integer | null Opcional

data.envios[].descarga_nombre string Opcional

Máximo: 255

data.envios[].descarga_direccion string Opcional

Máximo: 255

data.envios[].descarga_codigo_postal string Opcional

Máximo: 20

data.envios[].descarga_localidad string Opcional

Máximo: 255

data.envios[].descarga_provincia string | null Opcional

Máximo: 255

data.envios[].descarga_pais string Opcional

Máximo: 255

data.envios[].fecha_descarga string (date) Obligatorio

data.envios[].naturaleza_mercancia string Obligatorio

Máximo: 10000

data.envios[].peso_kg number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].magnitud_alternativa number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].unidad_magnitud string | null Opcional

Máximo: 30

data.envios[].requiere_autorizacion_especial boolean Opcional

Indica que este transporte requiere autorización especial de circulación. Al emitir o rectificar exige su identificación.

data.envios[].autorizacion_especial string | null Opcional

Máximo: 255

data.envios[].observaciones string | null Opcional

Máximo: 10000

data.envios[].vehiculo_id integer | null Opcional

data.envios[].matricula string | null Opcional

Obligatoria para emitir. Editable sin vehiculo del catalogo.

Máximo: 30

data.envios[].con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Si se omite, se copia o conserva según el vehículo y el envío.

data.envios[].matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

data.envios[].conductor_nombre string | null Opcional

Máximo: 255

data.envios[].conductor_telefono string | null Opcional

Máximo: 30

data.envios[].conductor_email string | null (email) Opcional

Máximo: 255

data.envios[].id string (uuid) Opcional

data.envios[].estado_servicio string Opcional

data.envios[].inicio_efectivo_en string | null (date-time) Opcional

data.envios[].fin_efectivo_en string | null (date-time) Opcional

data.envios[].no_realizado_en string | null (date-time) Opcional

data.envios[].motivo_cierre string | null Opcional

data.versiones array Opcional

data.versiones[].id string (uuid) Opcional

data.versiones[].numero integer Opcional

data.versiones[].tipo string Opcional

Valores: emision, correccion, rectificacion

data.versiones[].motivo string | null Opcional

data.versiones[].emitida_en string | null (date-time) Opcional

data.versiones[].sha256 string | null Opcional

Patrón: ^[a-f0-9]{64}$

data.versiones[].pdf_url string | null (uri) Opcional

data.versiones[].correos array Opcional

{
    "data": {
        "id": "123e4567-e89b-12d3-a456-426614174001",
        "estado": "emitido",
        "estado_etiqueta": "Emitido",
        "version_actual": 2,
        "version_emitida": "123e4567-e89b-12d3-a456-426614174003",
        "versiones": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174003",
                "numero": 2,
                "tipo": "rectificacion"
            }
        ]
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

POST /api/v1/documentos/{documento}/cerrar

Cierra opcionalmente un documento emitido sin registrar hitos

Conserva PDF y enlaces. No acredita entregas, inicio ni fin del transporte. Devuelve estado archivado y estado_etiqueta Cerrado. No crea otra version ni consumo.

Capacidad requerida: deca:operar

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000/cerrar' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Idempotency-Key: ejemplo-cerrarDocumento'

Respuestas

200 Documento cerrado application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id string (uuid) Opcional

data.estado string Opcional

Valores: incompleto, borrador, emitido, archivado, descartado

data.estado_etiqueta string Opcional

Valores: Incompleto, Borrador, Emitido, Cerrado

data.referencia string | null Opcional

data.version_actual integer Opcional

data.revision_edicion integer Opcional

Revision necesaria para sustituir un borrador.

data.payload_hash string | null Opcional

Huella de los datos enviados por la integracion.

data.version_emitida string | null (uuid) Opcional

data.creado_en string | null (date-time) Opcional

data.cargador_id integer | null Opcional

data.transportista_id integer | null Opcional

data.cargador object Opcional

data.transportista object Opcional

data.envios array Opcional

data.envios[].carga_contacto_id integer | null Opcional

data.envios[].carga_nombre string Opcional

Máximo: 255

data.envios[].carga_direccion string Opcional

Máximo: 255

data.envios[].carga_codigo_postal string Opcional

Máximo: 20

data.envios[].carga_localidad string Opcional

Máximo: 255

data.envios[].carga_provincia string | null Opcional

Máximo: 255

data.envios[].carga_pais string Opcional

Máximo: 255

data.envios[].fecha_carga string (date) Obligatorio

data.envios[].descarga_contacto_id integer | null Opcional

data.envios[].descarga_nombre string Opcional

Máximo: 255

data.envios[].descarga_direccion string Opcional

Máximo: 255

data.envios[].descarga_codigo_postal string Opcional

Máximo: 20

data.envios[].descarga_localidad string Opcional

Máximo: 255

data.envios[].descarga_provincia string | null Opcional

Máximo: 255

data.envios[].descarga_pais string Opcional

Máximo: 255

data.envios[].fecha_descarga string (date) Obligatorio

data.envios[].naturaleza_mercancia string Obligatorio

Máximo: 10000

data.envios[].peso_kg number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].magnitud_alternativa number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].unidad_magnitud string | null Opcional

Máximo: 30

data.envios[].requiere_autorizacion_especial boolean Opcional

Indica que este transporte requiere autorización especial de circulación. Al emitir o rectificar exige su identificación.

data.envios[].autorizacion_especial string | null Opcional

Máximo: 255

data.envios[].observaciones string | null Opcional

Máximo: 10000

data.envios[].vehiculo_id integer | null Opcional

data.envios[].matricula string | null Opcional

Obligatoria para emitir. Editable sin vehiculo del catalogo.

Máximo: 30

data.envios[].con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Si se omite, se copia o conserva según el vehículo y el envío.

data.envios[].matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

data.envios[].conductor_nombre string | null Opcional

Máximo: 255

data.envios[].conductor_telefono string | null Opcional

Máximo: 30

data.envios[].conductor_email string | null (email) Opcional

Máximo: 255

data.envios[].id string (uuid) Opcional

data.envios[].estado_servicio string Opcional

data.envios[].inicio_efectivo_en string | null (date-time) Opcional

data.envios[].fin_efectivo_en string | null (date-time) Opcional

data.envios[].no_realizado_en string | null (date-time) Opcional

data.envios[].motivo_cierre string | null Opcional

data.versiones array Opcional

data.versiones[].id string (uuid) Opcional

data.versiones[].numero integer Opcional

data.versiones[].tipo string Opcional

Valores: emision, correccion, rectificacion

data.versiones[].motivo string | null Opcional

data.versiones[].emitida_en string | null (date-time) Opcional

data.versiones[].sha256 string | null Opcional

Patrón: ^[a-f0-9]{64}$

data.versiones[].pdf_url string | null (uri) Opcional

data.versiones[].correos array Opcional

{
    "data": {
        "id": "123e4567-e89b-12d3-a456-426614174001",
        "estado": "archivado",
        "estado_etiqueta": "Cerrado",
        "version_actual": 1,
        "version_emitida": "123e4567-e89b-12d3-a456-426614174002"
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

GET /api/v1/documentos/{documento}/versiones/{version}/pdf

Descarga directamente un PDF versionado dentro de la empresa autorizada

Capacidad requerida: deca:leer

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

version string (uuid) Obligatorio

Petición cURL

curl -X GET 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000/versiones/123e4567-e89b-12d3-a456-426614174000/pdf' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN'

Respuestas

200 Fichero PDF inline application/pdf

El cuerpo contiene el archivo PDF de la versión indicada.

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

503 El archivo falta o no coincide con su hash o formato registrado.

Esta respuesta no incluye cuerpo.

POST /api/v1/documentos/{documento}/versiones/{version}/distribuir

Solicita el envio manual por email de la version vigente

No hay correos automaticos al emitir o rectificar. Requiere destinatario explicito, envia el correo directamente tras confirmar la transaccion y no registra entrega al conductor.

Capacidad requerida: deca:operar

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

version string (uuid) Obligatorio

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Cuerpo JSON

ParámetroTipoUsoDetalles

destinatario_email string (email) Obligatorio

Máximo: 255

destinatario_nombre string | null Opcional

Máximo: 255

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000/versiones/123e4567-e89b-12d3-a456-426614174000/distribuir' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ejemplo-distribuirVersion' \
  --data '{
    "destinatario_email": "[email protected]"
}'

JSON de ejemplo

{
    "destinatario_email": "[email protected]"
}

Respuestas

202 Envio solicitado y procesado de forma directa; no acredita entrega ni lectura application/json

ParámetroTipoUsoDetalles

data object Obligatorio

data.id string (uuid) Obligatorio

data.estado string Obligatorio

Valores: pendiente

data.version_id string (uuid) Obligatorio

{
    "data": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "estado": "pendiente",
        "version_id": "123e4567-e89b-12d3-a456-426614174000"
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

GET /api/v1/documentos/{documento}

Consulta un documento, sus envios y el historial de versiones

Capacidad requerida: deca:leer

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

Petición cURL

curl -X GET 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN'

Respuestas

200 Documento application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id string (uuid) Opcional

data.estado string Opcional

Valores: incompleto, borrador, emitido, archivado, descartado

data.estado_etiqueta string Opcional

Valores: Incompleto, Borrador, Emitido, Cerrado

data.referencia string | null Opcional

data.version_actual integer Opcional

data.revision_edicion integer Opcional

Revision necesaria para sustituir un borrador.

data.payload_hash string | null Opcional

Huella de los datos enviados por la integracion.

data.version_emitida string | null (uuid) Opcional

data.creado_en string | null (date-time) Opcional

data.cargador_id integer | null Opcional

data.transportista_id integer | null Opcional

data.cargador object Opcional

data.transportista object Opcional

data.envios array Opcional

data.envios[].carga_contacto_id integer | null Opcional

data.envios[].carga_nombre string Opcional

Máximo: 255

data.envios[].carga_direccion string Opcional

Máximo: 255

data.envios[].carga_codigo_postal string Opcional

Máximo: 20

data.envios[].carga_localidad string Opcional

Máximo: 255

data.envios[].carga_provincia string | null Opcional

Máximo: 255

data.envios[].carga_pais string Opcional

Máximo: 255

data.envios[].fecha_carga string (date) Obligatorio

data.envios[].descarga_contacto_id integer | null Opcional

data.envios[].descarga_nombre string Opcional

Máximo: 255

data.envios[].descarga_direccion string Opcional

Máximo: 255

data.envios[].descarga_codigo_postal string Opcional

Máximo: 20

data.envios[].descarga_localidad string Opcional

Máximo: 255

data.envios[].descarga_provincia string | null Opcional

Máximo: 255

data.envios[].descarga_pais string Opcional

Máximo: 255

data.envios[].fecha_descarga string (date) Obligatorio

data.envios[].naturaleza_mercancia string Obligatorio

Máximo: 10000

data.envios[].peso_kg number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].magnitud_alternativa number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].unidad_magnitud string | null Opcional

Máximo: 30

data.envios[].requiere_autorizacion_especial boolean Opcional

Indica que este transporte requiere autorización especial de circulación. Al emitir o rectificar exige su identificación.

data.envios[].autorizacion_especial string | null Opcional

Máximo: 255

data.envios[].observaciones string | null Opcional

Máximo: 10000

data.envios[].vehiculo_id integer | null Opcional

data.envios[].matricula string | null Opcional

Obligatoria para emitir. Editable sin vehiculo del catalogo.

Máximo: 30

data.envios[].con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Si se omite, se copia o conserva según el vehículo y el envío.

data.envios[].matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

data.envios[].conductor_nombre string | null Opcional

Máximo: 255

data.envios[].conductor_telefono string | null Opcional

Máximo: 30

data.envios[].conductor_email string | null (email) Opcional

Máximo: 255

data.envios[].id string (uuid) Opcional

data.envios[].estado_servicio string Opcional

data.envios[].inicio_efectivo_en string | null (date-time) Opcional

data.envios[].fin_efectivo_en string | null (date-time) Opcional

data.envios[].no_realizado_en string | null (date-time) Opcional

data.envios[].motivo_cierre string | null Opcional

data.versiones array Opcional

data.versiones[].id string (uuid) Opcional

data.versiones[].numero integer Opcional

data.versiones[].tipo string Opcional

Valores: emision, correccion, rectificacion

data.versiones[].motivo string | null Opcional

data.versiones[].emitida_en string | null (date-time) Opcional

data.versiones[].sha256 string | null Opcional

Patrón: ^[a-f0-9]{64}$

data.versiones[].pdf_url string | null (uri) Opcional

data.versiones[].correos array Opcional

{
    "data": {
        "id": "123e4567-e89b-12d3-a456-426614174001",
        "estado": "borrador",
        "estado_etiqueta": "Borrador",
        "referencia": "PED-2026-014",
        "version_actual": 0,
        "revision_edicion": 1,
        "envios": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "fecha_carga": "2026-10-14",
                "fecha_descarga": "2026-10-15"
            }
        ]
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

PUT /api/v1/documentos/{documento}

Sustituye los datos de un borrador creado por esta integracion

Requiere la revision devuelta por GET. Una peticion sin cambios conserva la revision. Los documentos emitidos no se pueden sobrescribir.

Capacidad requerida: deca:borradores:gestionar

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Cuerpo JSON

ParámetroTipoUsoDetalles

id_externo string | null Opcional

Identificador externo unico para esta integracion y empresa.

Máximo: 160

referencia string | null Opcional

Máximo: 80

transportista_id integer | null Opcional

Contacto vinculado como transportista. Omitir o null permite datos manuales sin acceso para equipos.

cargador_id integer | null Opcional

Contacto vinculado como cargador. Omitir o null permite datos manuales; no aplica ningun predeterminado en la API.

cargador object Opcional

Con ID se copian los campos omitidos y prevalecen los enviados. Sin ID se requieren nombre, identificacion_fiscal y domicilio. Los datos se congelan en el documento, sin modificar el contacto.

cargador.nombre string Opcional

Máximo: 255

cargador.identificacion_fiscal string Opcional

Máximo: 50

cargador.domicilio string Opcional

Máximo: 255

cargador.email string | null (email) Opcional

cargador.telefono string | null Opcional

Máximo: 30

transportista object Opcional

Con ID se copian los campos omitidos y prevalecen los enviados. Sin ID se requieren nombre, identificacion_fiscal y domicilio. Los datos se congelan en el documento, sin modificar el contacto.

transportista.nombre string Opcional

Máximo: 255

transportista.identificacion_fiscal string Opcional

Máximo: 50

transportista.domicilio string Opcional

Máximo: 255

transportista.email string | null (email) Opcional

transportista.telefono string | null Opcional

Máximo: 30

envios array Obligatorio

Mínimo elementos: 1 · Máximo elementos: 100

envios[].carga_contacto_id integer | null Opcional

envios[].carga_nombre string Opcional

Máximo: 255

envios[].carga_direccion string Opcional

Máximo: 255

envios[].carga_codigo_postal string Opcional

Máximo: 20

envios[].carga_localidad string Opcional

Máximo: 255

envios[].carga_provincia string | null Opcional

Máximo: 255

envios[].carga_pais string Opcional

Máximo: 255

envios[].fecha_carga string (date) Obligatorio

envios[].descarga_contacto_id integer | null Opcional

envios[].descarga_nombre string Opcional

Máximo: 255

envios[].descarga_direccion string Opcional

Máximo: 255

envios[].descarga_codigo_postal string Opcional

Máximo: 20

envios[].descarga_localidad string Opcional

Máximo: 255

envios[].descarga_provincia string | null Opcional

Máximo: 255

envios[].descarga_pais string Opcional

Máximo: 255

envios[].fecha_descarga string (date) Obligatorio

envios[].naturaleza_mercancia string Obligatorio

Máximo: 10000

envios[].peso_kg number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

envios[].magnitud_alternativa number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

envios[].unidad_magnitud string | null Opcional

Máximo: 30

envios[].requiere_autorizacion_especial boolean Opcional

Indica que este transporte requiere autorización especial de circulación. Al emitir o rectificar exige su identificación.

envios[].autorizacion_especial string | null Opcional

Máximo: 255

envios[].observaciones string | null Opcional

Máximo: 10000

envios[].vehiculo_id integer | null Opcional

envios[].matricula string | null Opcional

Obligatoria para emitir. Editable sin vehiculo del catalogo.

Máximo: 30

envios[].con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Si se omite, se copia o conserva según el vehículo y el envío.

envios[].matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

envios[].conductor_nombre string | null Opcional

Máximo: 255

envios[].conductor_telefono string | null Opcional

Máximo: 30

envios[].conductor_email string | null (email) Opcional

Máximo: 255

revision_edicion integer Obligatorio

Mínimo: 0

Petición cURL

curl -X PUT 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ejemplo-actualizarBorrador' \
  --data '{
    "envios": [
        {
            "fecha_carga": "2026-10-14",
            "fecha_descarga": "2026-10-14",
            "naturaleza_mercancia": "ejemplo"
        }
    ],
    "revision_edicion": 1
}'

JSON de ejemplo

{
    "envios": [
        {
            "fecha_carga": "2026-10-14",
            "fecha_descarga": "2026-10-14",
            "naturaleza_mercancia": "ejemplo"
        }
    ],
    "revision_edicion": 1
}

Respuestas

200 Borrador actualizado application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id string (uuid) Opcional

data.estado string Opcional

Valores: incompleto, borrador, emitido, archivado, descartado

data.estado_etiqueta string Opcional

Valores: Incompleto, Borrador, Emitido, Cerrado

data.referencia string | null Opcional

data.version_actual integer Opcional

data.revision_edicion integer Opcional

Revision necesaria para sustituir un borrador.

data.payload_hash string | null Opcional

Huella de los datos enviados por la integracion.

data.version_emitida string | null (uuid) Opcional

data.creado_en string | null (date-time) Opcional

data.cargador_id integer | null Opcional

data.transportista_id integer | null Opcional

data.cargador object Opcional

data.transportista object Opcional

data.envios array Opcional

data.envios[].carga_contacto_id integer | null Opcional

data.envios[].carga_nombre string Opcional

Máximo: 255

data.envios[].carga_direccion string Opcional

Máximo: 255

data.envios[].carga_codigo_postal string Opcional

Máximo: 20

data.envios[].carga_localidad string Opcional

Máximo: 255

data.envios[].carga_provincia string | null Opcional

Máximo: 255

data.envios[].carga_pais string Opcional

Máximo: 255

data.envios[].fecha_carga string (date) Obligatorio

data.envios[].descarga_contacto_id integer | null Opcional

data.envios[].descarga_nombre string Opcional

Máximo: 255

data.envios[].descarga_direccion string Opcional

Máximo: 255

data.envios[].descarga_codigo_postal string Opcional

Máximo: 20

data.envios[].descarga_localidad string Opcional

Máximo: 255

data.envios[].descarga_provincia string | null Opcional

Máximo: 255

data.envios[].descarga_pais string Opcional

Máximo: 255

data.envios[].fecha_descarga string (date) Obligatorio

data.envios[].naturaleza_mercancia string Obligatorio

Máximo: 10000

data.envios[].peso_kg number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].magnitud_alternativa number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].unidad_magnitud string | null Opcional

Máximo: 30

data.envios[].requiere_autorizacion_especial boolean Opcional

Indica que este transporte requiere autorización especial de circulación. Al emitir o rectificar exige su identificación.

data.envios[].autorizacion_especial string | null Opcional

Máximo: 255

data.envios[].observaciones string | null Opcional

Máximo: 10000

data.envios[].vehiculo_id integer | null Opcional

data.envios[].matricula string | null Opcional

Obligatoria para emitir. Editable sin vehiculo del catalogo.

Máximo: 30

data.envios[].con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Si se omite, se copia o conserva según el vehículo y el envío.

data.envios[].matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

data.envios[].conductor_nombre string | null Opcional

Máximo: 255

data.envios[].conductor_telefono string | null Opcional

Máximo: 30

data.envios[].conductor_email string | null (email) Opcional

Máximo: 255

data.envios[].id string (uuid) Opcional

data.envios[].estado_servicio string Opcional

data.envios[].inicio_efectivo_en string | null (date-time) Opcional

data.envios[].fin_efectivo_en string | null (date-time) Opcional

data.envios[].no_realizado_en string | null (date-time) Opcional

data.envios[].motivo_cierre string | null Opcional

data.versiones array Opcional

data.versiones[].id string (uuid) Opcional

data.versiones[].numero integer Opcional

data.versiones[].tipo string Opcional

Valores: emision, correccion, rectificacion

data.versiones[].motivo string | null Opcional

data.versiones[].emitida_en string | null (date-time) Opcional

data.versiones[].sha256 string | null Opcional

Patrón: ^[a-f0-9]{64}$

data.versiones[].pdf_url string | null (uri) Opcional

data.versiones[].correos array Opcional

{
    "data": {
        "id": "123e4567-e89b-12d3-a456-426614174001",
        "estado": "borrador",
        "estado_etiqueta": "Borrador",
        "referencia": "PED-2026-014",
        "version_actual": 0,
        "revision_edicion": 1,
        "envios": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "fecha_carga": "2026-10-14",
                "fecha_descarga": "2026-10-15"
            }
        ]
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

GET /api/v1/documentos/{documento}/versiones

Consulta versiones inmutables del documento

Incluye correos con destinatario, estado pendiente/enviado/fallido y fecha de envio. Los correos no acreditan entrega al conductor.

Capacidad requerida: deca:leer

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

Petición cURL

curl -X GET 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000/versiones' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN'

Respuestas

200 Historial ordenado por version application/json

ParámetroTipoUsoDetalles

data array Obligatorio

data[].id string (uuid) Opcional

data[].numero integer Opcional

data[].tipo string Opcional

Valores: emision, correccion, rectificacion

data[].motivo string | null Opcional

data[].emitida_en string | null (date-time) Opcional

data[].sha256 string | null Opcional

Patrón: ^[a-f0-9]{64}$

data[].pdf_url string | null (uri) Opcional

data[].correos array Opcional

data[].correos[].id string (uuid) Opcional

data[].correos[].destinatario_email string (email) Opcional

data[].correos[].estado string Opcional

Valores: pendiente, enviado, fallido

data[].correos[].enviado_en string | null (date-time) Opcional

{
    "data": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "numero": 1,
            "tipo": "emision",
            "motivo": "ejemplo"
        }
    ]
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

POST /api/v1/documentos/{documento}/descartar

Descarta un borrador sin borrar registros emitidos

Capacidad requerida: deca:borradores:gestionar

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000/descartar' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Idempotency-Key: ejemplo-descartarBorrador'

Respuestas

200 Borrador descartado application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id string (uuid) Opcional

data.estado string Opcional

Valores: incompleto, borrador, emitido, archivado, descartado

data.estado_etiqueta string Opcional

Valores: Incompleto, Borrador, Emitido, Cerrado

data.referencia string | null Opcional

data.version_actual integer Opcional

data.revision_edicion integer Opcional

Revision necesaria para sustituir un borrador.

data.payload_hash string | null Opcional

Huella de los datos enviados por la integracion.

data.version_emitida string | null (uuid) Opcional

data.creado_en string | null (date-time) Opcional

data.cargador_id integer | null Opcional

data.transportista_id integer | null Opcional

data.cargador object Opcional

data.transportista object Opcional

data.envios array Opcional

data.envios[].carga_contacto_id integer | null Opcional

data.envios[].carga_nombre string Opcional

Máximo: 255

data.envios[].carga_direccion string Opcional

Máximo: 255

data.envios[].carga_codigo_postal string Opcional

Máximo: 20

data.envios[].carga_localidad string Opcional

Máximo: 255

data.envios[].carga_provincia string | null Opcional

Máximo: 255

data.envios[].carga_pais string Opcional

Máximo: 255

data.envios[].fecha_carga string (date) Obligatorio

data.envios[].descarga_contacto_id integer | null Opcional

data.envios[].descarga_nombre string Opcional

Máximo: 255

data.envios[].descarga_direccion string Opcional

Máximo: 255

data.envios[].descarga_codigo_postal string Opcional

Máximo: 20

data.envios[].descarga_localidad string Opcional

Máximo: 255

data.envios[].descarga_provincia string | null Opcional

Máximo: 255

data.envios[].descarga_pais string Opcional

Máximo: 255

data.envios[].fecha_descarga string (date) Obligatorio

data.envios[].naturaleza_mercancia string Obligatorio

Máximo: 10000

data.envios[].peso_kg number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].magnitud_alternativa number | string | null Opcional

Decimal positivo; la respuesta conserva precision mediante una cadena decimal.

Mayor que: 0

data.envios[].unidad_magnitud string | null Opcional

Máximo: 30

data.envios[].requiere_autorizacion_especial boolean Opcional

Indica que este transporte requiere autorización especial de circulación. Al emitir o rectificar exige su identificación.

data.envios[].autorizacion_especial string | null Opcional

Máximo: 255

data.envios[].observaciones string | null Opcional

Máximo: 10000

data.envios[].vehiculo_id integer | null Opcional

data.envios[].matricula string | null Opcional

Obligatoria para emitir. Editable sin vehiculo del catalogo.

Máximo: 30

data.envios[].con_remolque boolean Opcional

Exige matrícula del remolque o semirremolque. Si se omite, se copia o conserva según el vehículo y el envío.

data.envios[].matricula_remolque string | null Opcional

Obligatoria cuando con_remolque es true al guardar el vehículo o emitir una versión del DeCA.

Máximo: 30

data.envios[].conductor_nombre string | null Opcional

Máximo: 255

data.envios[].conductor_telefono string | null Opcional

Máximo: 30

data.envios[].conductor_email string | null (email) Opcional

Máximo: 255

data.envios[].id string (uuid) Opcional

data.envios[].estado_servicio string Opcional

data.envios[].inicio_efectivo_en string | null (date-time) Opcional

data.envios[].fin_efectivo_en string | null (date-time) Opcional

data.envios[].no_realizado_en string | null (date-time) Opcional

data.envios[].motivo_cierre string | null Opcional

data.versiones array Opcional

data.versiones[].id string (uuid) Opcional

data.versiones[].numero integer Opcional

data.versiones[].tipo string Opcional

Valores: emision, correccion, rectificacion

data.versiones[].motivo string | null Opcional

data.versiones[].emitida_en string | null (date-time) Opcional

data.versiones[].sha256 string | null Opcional

Patrón: ^[a-f0-9]{64}$

data.versiones[].pdf_url string | null (uri) Opcional

data.versiones[].correos array Opcional

{
    "data": {
        "id": "123e4567-e89b-12d3-a456-426614174001",
        "estado": "descartado",
        "estado_etiqueta": "Cerrado",
        "referencia": "PED-2026-014",
        "version_actual": 0
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

Referencia de operaciones

Envios

POST /api/v1/documentos/{documento}/envios/{envio}/entregas

Registra una entrega manual auditada para la version vigente

El acuse es opcional mediante confirmar_recepcion. No acredita identidad legal ni equivale a una confirmacion directa del conductor.

Capacidad requerida: deca:operar

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

envio string (uuid) Obligatorio

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Cuerpo JSON

ParámetroTipoUsoDetalles

destinatario_nombre string Obligatorio

Máximo: 255

destinatario_email string | null (email) Opcional

Obligatorio solo cuando canal es email_comprobado.

canal string Obligatorio

Valores: email_comprobado, entrega_transportista, papel

evidencia string Obligatorio

Mínimo: 5 · Máximo: 2000

confirmar_recepcion boolean Opcional

Registrar tambien un acuse de recepcion comprobado por el actor.

Predeterminado: false

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000/envios/123e4567-e89b-12d3-a456-426614174000/entregas' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ejemplo-registrarEntregaManual' \
  --data '{
    "destinatario_nombre": "Ana García",
    "canal": "entrega_transportista",
    "evidencia": "Copia vigente entregada en mano al conductor."
}'

JSON de ejemplo

{
    "destinatario_nombre": "Ana García",
    "canal": "entrega_transportista",
    "evidencia": "Copia vigente entregada en mano al conductor."
}

Respuestas

201 Entrega registrada application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id integer Opcional

data.envio_id string (uuid) Opcional

data.version_id string (uuid) Opcional

data.destinatario_nombre string Opcional

data.destinatario_email string | null (email) Opcional

data.canal string Opcional

data.estado string Opcional

data.confirmacion_tipo string | null Opcional

data.entregada_en string (date-time) Opcional

data.confirmada_en string | null (date-time) Opcional

{
    "data": {
        "id": 1,
        "envio_id": "123e4567-e89b-12d3-a456-426614174000",
        "version_id": "123e4567-e89b-12d3-a456-426614174002",
        "destinatario_nombre": "Ana García",
        "canal": "entrega_transportista",
        "estado": "registrada",
        "entregada_en": "2026-10-14T09:00:00+02:00"
    }
}

200 Entrega existente registrada o actualizada con acuse opcional application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id integer Opcional

data.envio_id string (uuid) Opcional

data.version_id string (uuid) Opcional

data.destinatario_nombre string Opcional

data.destinatario_email string | null (email) Opcional

data.canal string Opcional

data.estado string Opcional

data.confirmacion_tipo string | null Opcional

data.entregada_en string (date-time) Opcional

data.confirmada_en string | null (date-time) Opcional

{
    "data": {
        "id": 1,
        "envio_id": "123e4567-e89b-12d3-a456-426614174000",
        "version_id": "123e4567-e89b-12d3-a456-426614174002",
        "destinatario_nombre": "Ana García",
        "canal": "entrega_transportista",
        "estado": "registrada",
        "entregada_en": "2026-10-14T09:00:00+02:00"
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

POST /api/v1/documentos/{documento}/envios/{envio}/hitos/inicio

Registra el inicio efectivo del servicio

Exige entrega registrada de la version vigente a todos los destinatarios antes del inicio efectivo. El acuse de recepcion es opcional.

Capacidad requerida: deca:operar

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

envio string (uuid) Obligatorio

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Cuerpo JSON

ParámetroTipoUsoDetalles

ocurrido_en string (date-time) Obligatorio

motivo string Opcional

Máximo: 2000

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000/envios/123e4567-e89b-12d3-a456-426614174000/hitos/inicio' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ejemplo-registrarInicio' \
  --data '{
    "ocurrido_en": "2026-10-14T10:00:00+02:00"
}'

JSON de ejemplo

{
    "ocurrido_en": "2026-10-14T10:00:00+02:00"
}

Respuestas

201 Hito registrado application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id integer Opcional

data.tipo string Opcional

data.ocurrido_en string (date-time) Opcional

data.actor_tipo string Opcional

Valores: integracion

data.motivo string | null Opcional

data.estado_servicio string Opcional

{
    "data": {
        "id": 1,
        "tipo": "ejemplo",
        "ocurrido_en": "2026-10-14T10:00:00+02:00",
        "actor_tipo": "integracion"
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

POST /api/v1/documentos/{documento}/envios/{envio}/hitos/fin

Registra el fin efectivo del servicio

Capacidad requerida: deca:operar

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

envio string (uuid) Obligatorio

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Cuerpo JSON

ParámetroTipoUsoDetalles

ocurrido_en string (date-time) Obligatorio

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000/envios/123e4567-e89b-12d3-a456-426614174000/hitos/fin' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ejemplo-registrarFin' \
  --data '{
    "ocurrido_en": "2026-10-14T10:00:00+02:00"
}'

JSON de ejemplo

{
    "ocurrido_en": "2026-10-14T10:00:00+02:00"
}

Respuestas

201 Hito registrado application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id integer Opcional

data.tipo string Opcional

data.ocurrido_en string (date-time) Opcional

data.actor_tipo string Opcional

Valores: integracion

data.motivo string | null Opcional

data.estado_servicio string Opcional

{
    "data": {
        "id": 1,
        "tipo": "ejemplo",
        "ocurrido_en": "2026-10-14T10:00:00+02:00",
        "actor_tipo": "integracion"
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

POST /api/v1/documentos/{documento}/envios/{envio}/hitos/no-realizado

Cierra un servicio no realizado con su motivo

Capacidad requerida: deca:operar

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

envio string (uuid) Obligatorio

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Cuerpo JSON

ParámetroTipoUsoDetalles

ocurrido_en string (date-time) Obligatorio

motivo string Obligatorio

Máximo: 2000

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000/envios/123e4567-e89b-12d3-a456-426614174000/hitos/no-realizado' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ejemplo-registrarNoRealizado' \
  --data '{
    "ocurrido_en": "2026-10-14T10:00:00+02:00",
    "motivo": "El cargador canceló el transporte antes de iniciarlo."
}'

JSON de ejemplo

{
    "ocurrido_en": "2026-10-14T10:00:00+02:00",
    "motivo": "El cargador canceló el transporte antes de iniciarlo."
}

Respuestas

201 Hito registrado application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id integer Opcional

data.tipo string Opcional

data.ocurrido_en string (date-time) Opcional

data.actor_tipo string Opcional

Valores: integracion

data.motivo string | null Opcional

data.estado_servicio string Opcional

{
    "data": {
        "id": 1,
        "tipo": "ejemplo",
        "ocurrido_en": "2026-10-14T10:00:00+02:00",
        "actor_tipo": "integracion"
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

POST /api/v1/documentos/{documento}/envios/{envio}/hitos/interrupcion

Registra una interrupcion con su motivo

Capacidad requerida: deca:operar

Parámetros de ruta

ParámetroTipoUsoDetalles

documento string (uuid) Obligatorio

envio string (uuid) Obligatorio

Cabeceras de la operación

ParámetroTipoUsoDetalles

Idempotency-Key string Obligatorio

Clave de 1 a 120 caracteres. Repetir la misma clave y carga devuelve la respuesta original; reutilizarla con otra solicitud responde 409.

Mínimo: 1 · Máximo: 120

Cuerpo JSON

ParámetroTipoUsoDetalles

ocurrido_en string (date-time) Obligatorio

motivo string Obligatorio

Máximo: 2000

Petición cURL

curl -X POST 'https://EMPRESA.DOMINIO/api/v1/documentos/123e4567-e89b-12d3-a456-426614174000/envios/123e4567-e89b-12d3-a456-426614174000/hitos/interrupcion' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ejemplo-registrarInterrupcion' \
  --data '{
    "ocurrido_en": "2026-10-14T10:00:00+02:00",
    "motivo": "Incidencia técnica durante el transporte."
}'

JSON de ejemplo

{
    "ocurrido_en": "2026-10-14T10:00:00+02:00",
    "motivo": "Incidencia técnica durante el transporte."
}

Respuestas

201 Hito registrado application/json

ParámetroTipoUsoDetalles

data object Opcional

data.id integer Opcional

data.tipo string Opcional

data.ocurrido_en string (date-time) Opcional

data.actor_tipo string Opcional

Valores: integracion

data.motivo string | null Opcional

data.estado_servicio string Opcional

{
    "data": {
        "id": 1,
        "tipo": "ejemplo",
        "ocurrido_en": "2026-10-14T10:00:00+02:00",
        "actor_tipo": "integracion"
    }
}

401 Token ausente, invalido o no asociado a una integracion. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "No autenticado."
}

403 Integracion inactiva o capacidad no concedida. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Esta integración no tiene permiso para esta operación."
}

404 Recurso inexistente o fuera de la empresa resuelta por el host. application/json

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "Recurso no encontrado."
}

ParámetroTipoUsoDetalles

message string Opcional

codigo string Opcional

En errores 409 de creación o primera emisión, identifica el límite mensual agotado o el plazo de regularización vencido. Consultas, rectificaciones y descargas conservan acceso.

Valores: cupo_agotado, pago_pendiente

{
    "message": "El estado actual no permite completar la operación."
}

422 Datos de entrada no validos. application/json

ParámetroTipoUsoDetalles

message string Opcional

errors object Opcional

{
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "campo": [
            "El campo no es válido."
        ]
    }
}

Parámetros de ruta

Parámetros de consulta

Respuestas

Parámetros de ruta

Cabeceras de la operación

Cuerpo JSON

Respuestas

Parámetros de ruta

Respuestas

Parámetros de ruta

Cabeceras de la operación

Cuerpo JSON

Respuestas

Parámetros de ruta

Cabeceras de la operación

Cuerpo JSON

Respuestas

Parámetros de ruta

Cabeceras de la operación

Respuestas

Parámetros de consulta

Respuestas

Cabeceras de la operación

Cuerpo JSON

Respuestas

Parámetros de ruta

Cabeceras de la operación

Respuestas

Parámetros de ruta

Cabeceras de la operación

Cuerpo JSON

Respuestas

Parámetros de ruta

Cabeceras de la operación

Respuestas

Parámetros de ruta

Respuestas

Parámetros de ruta

Cabeceras de la operación

Cuerpo JSON

Respuestas

Parámetros de ruta

Respuestas

Parámetros de ruta

Cabeceras de la operación

Cuerpo JSON

Respuestas

Parámetros de ruta

Respuestas

Parámetros de ruta

Cabeceras de la operación

Respuestas

Parámetros de ruta

Cabeceras de la operación

Cuerpo JSON

Respuestas

Parámetros de ruta

Cabeceras de la operación

Cuerpo JSON

Respuestas

Parámetros de ruta

Cabeceras de la operación

Cuerpo JSON

Respuestas

Parámetros de ruta

Cabeceras de la operación

Cuerpo JSON

Respuestas

Parámetros de ruta

Cabeceras de la operación

Cuerpo JSON

Respuestas

Tu privacidad