La autorización

Una autorización es el permiso que habilita a un transportista concreto a acceder a una instalación (grupo de totems) para cargar o descargar una cantidad determinada de un producto. Es la entidad central del modelo DigiAnt: todo flujo operativo empieza con una autorización activa.

Ciclo de vida

El modelo de estados es deliberadamente simple: dos estados, sin intermedios.

Estado	Significado
Active	La autorización está vigente y puede generar operaciones en el totem.
Finished	La autorización ha finalizado (completada, cancelada u otro motivo). Ya no es operable.

Una autorización creada vía Partner API nace directamente en estado Active. No hay flujo de aprobación — si llega al sistema es porque ya está autorizada.

Campos principales

Campos de negocio (inmutables tras la creación)

Definen qué se mueve, cuánto, dónde y con quién.

Campo	Tipo	Descripción
externalId	string	ID del registro en el ERP. Obligatorio — garantiza idempotencia en reintentos. No se devuelve en la respuesta.
productId	uuid	UUID del producto del catálogo DigiAnt. La respuesta devuelve el nombre resuelto como product.
quantity	number	Cantidad autorizada (en la unidad que corresponda a tu operativa).
warehouseId	uuid	UUID del almacén del catálogo DigiAnt. La respuesta devuelve la referencia resuelta como warehouse.
totemGroupId	uuid	Grupo de totems (instalación física).
operationType	"loading" / "unloading"	Tipo de operación. Ver Tipos de operación.
batch	string?	Número de lote/partida (opcional).
format	string?	Formato del producto, p. ej. "Bulk" (opcional).
scheduledDate	datetime?	Fecha de inicio de validez (opcional).
endDate	datetime?	Fecha de fin de validez (opcional).

Campos de partes (inmutables tras la creación)

Identifican a los agentes involucrados.

Campo	Tipo	Descripción
carrierTaxId	string	NIF/CIF del transportista. DigiAnt lo resuelve a un carrierId interno.
partnerName / partnerCif / …	string	Datos de la parte operativa (expedidor en carga, destinatario en descarga). Ver Entidades clave.
productOwnerName / productOwnerCif / …	string	Datos del propietario de la mercancía.

Campos operativos (asignables a posteriori)

Se pueden incluir en el push inicial o actualizar después vía PATCH /authorizations/{id}.

Campo (creación)	Tipo	Descripción
driverNif	string?	NIF del conductor. DigiAnt lo resuelve a un UUID interno.
tractorPlate	string?	Matrícula del tractor. 1-8 caracteres alfanuméricos, se normaliza a mayúsculas.
trailerPlates	string[]	Matrículas de los remolques. Mismas reglas que tractorPlate.

tip

Si incluyes driverNif y tractorPlate en el push, DigiAnt puede generar la operación de forma totalmente automática cuando el vehículo llegue al totem.

Modos de validez por fecha

El comportamiento de las fechas depende de los campos que incluyas:

scheduledDate	endDate	Comportamiento
—	—	Sin restricción de fecha. Válida cualquier día (autorización por peso).
✅	—	Válida desde scheduledDate en adelante.
✅	✅	Válida únicamente dentro del rango [scheduledDate, endDate].

Una autorización sin fechas no expira automáticamente — finaliza cuando se consume la cantidad o se marca como Finished manualmente.

Transportista identificado por NIF/CIF

A diferencia de otras entidades, el transportista no se pasa como UUID en el push. DigiAnt resuelve el carrierTaxId (NIF/CIF) a su UUID interno. El transportista debe estar registrado en DigiAnt previamente — si el NIF/CIF no existe, el push devuelve 422.

Qué ocurre tras crear una autorización

1. DigiAnt crea la autorización en estado Active.
2. La autorización queda disponible en los totems del grupo totemGroupId.
3. Cuando el conductor llega y se identifica, el totem valida la autorización y registra la operación.
4. Si no se incluyeron datos del conductor o vehículo, puedes asignarlos después vía PATCH /authorizations/{id}, o el equipo de operaciones los asigna desde la app DigiAnt.

Gestión de autorizaciones

Consultar

Lista todas las autorizaciones de tu empresa logística, con filtros opcionales por estado, rango de fechas y paginación:

GET /partner/authorizations?status=Active&scheduledDateFrom=2026-06-01&limit=50&offset=0
X-Partner-API-Key: dpk_live_...

Consulta una autorización concreta por su UUID:

GET /partner/authorizations/{id}
X-Partner-API-Key: dpk_live_...

Actualizar campos operativos

Actualiza cualquier campo mutable de una autorización Active. Todos los campos son opcionales — omite los que no quieras cambiar:

PATCH /partner/authorizations/{id}
X-Partner-API-Key: dpk_live_...
Content-Type: application/json

{
  "driverNif": "12345678Z",
  "tractorPlate": "1234ABC",
  "trailerPlates": ["R5678TRL"]
}

Solo funciona en autorizaciones Active.

Cancelar

Marca la autorización como Finished. Devuelve la autorización actualizada, o 409 si ya estaba finalizada.

POST /partner/authorizations/{id}/cancel
X-Partner-API-Key: dpk_live_...

Webhook de eventos

Emite un evento de dominio en el pipeline DigiAnt. Útil para re-disparar lógica interna sin necesidad de recrear la autorización.

POST /partner/authorizations/{id}/webhook
X-Partner-API-Key: dpk_live_...
Content-Type: application/json

{ "eventType": "synced" }

Evento	Cuándo usarlo
synced	Tras actualizar campos operativos vía PATCH: re-ejecuta la generación de operaciones si se cumplen las condiciones.
fetch_requested_from_erp	Solo válido para autorizaciones sincronizadas desde un ERP externo. Pide a DigiAnt que obtenga el estado actualizado del ERP de forma asíncrona.