The Authorization

An authorization is the permit that allows a specific carrier to access a facility (totem group) to load or unload a given quantity of a product. It is the central entity in the DigiAnt model: every operational flow starts with an active authorization.

Lifecycle

The state model is deliberately simple: two states, no intermediates.

State	Meaning
Active	The authorization is valid and can generate operations at the totem.
Finished	The authorization has ended (completed, cancelled, or any other reason). No longer operable.

An authorization created via the Partner API is born directly in Active state. There is no approval flow — if it reaches the system, it is already authorized.

Core fields

Business fields (immutable after creation)

Define what moves, how much, where, and with whom.

Field	Type	Description
externalId	string	Record ID in the ERP. Required — ensures idempotency on retries. Not returned in responses.
productId	uuid	UUID of the product in the DigiAnt catalog. The response returns the resolved name as product.
quantity	number	Authorized quantity (in your operational unit).
warehouseId	uuid	UUID of the warehouse in the DigiAnt catalog. The response returns the resolved reference as warehouse.
totemGroupId	uuid	Totem group (physical installation).
operationType	"loading" / "unloading"	Operation type. See Operation Types.
batch	string?	Batch/lot number (optional).
format	string?	Product format, e.g. "Bulk" (optional).
scheduledDate	datetime?	Validity start date (optional).
endDate	datetime?	Validity end date (optional).

Party fields (immutable after creation)

Identify the agents involved.

Field	Type	Description
carrierTaxId	string	Carrier NIF/CIF. DigiAnt resolves it to an internal carrierId.
partnerName / partnerCif / …	string	Operation party data (sender for loading, receiver for unloading). See Key Entities.
productOwnerName / productOwnerCif / …	string	Product owner data.

Operational fields (assignable after creation)

Can be included in the initial push or updated later via PATCH /authorizations/{id}.

Field (creation)	Type	Description
driverNif	string?	Driver NIF. DigiAnt resolves it to an internal UUID.
tractorPlate	string?	Tractor license plate. 1–8 alphanumeric characters, normalized to uppercase.
trailerPlates	string[]	Trailer license plates. Same rules as tractorPlate.

tip

If you include driverNif and tractorPlate in the push, DigiAnt can generate the operation fully automatically when the vehicle arrives at the totem.

Date validity modes

Date behavior depends on which fields you include:

scheduledDate	endDate	Behavior
—	—	No date restriction. Valid any day (weight-based authorization).
✅	—	Valid from scheduledDate onward.
✅	✅	Valid only within the range [scheduledDate, endDate].

A dateless authorization does not expire automatically — it ends when the quantity is consumed or it is manually marked as Finished.

Carrier identified by tax ID

Unlike other entities, the carrier is not passed as a UUID in the push. DigiAnt resolves the carrierTaxId (NIF/CIF) to its internal UUID. The carrier must be registered in DigiAnt beforehand — if the NIF/CIF does not exist, the push returns 422.

What happens after creating an authorization

1. DigiAnt creates the authorization in Active state.
2. The authorization becomes available at the totems in group totemGroupId.
3. When the driver arrives and identifies themselves, the totem validates the authorization and records the operation.
4. If driver or vehicle data were not included, you can assign them later via PATCH /authorizations/{id}, or the operations team can do so from the DigiAnt app.

Managing authorizations

Query

List all authorizations for your logistics company, with optional filters by status, date range, and pagination:

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

Fetch a specific authorization by its UUID:

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

Update operational fields

Update any mutable field on an Active authorization. All fields are optional — omit what you want to keep unchanged:

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

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

Only works on Active authorizations.

Cancel

Marks the authorization as Finished. Returns the updated authorization, or 409 if it was already finished.

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

Event webhook

Emits a domain event into the DigiAnt event pipeline. Useful for re-triggering internal logic without recreating the authorization.

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

{ "eventType": "synced" }

Event	When to use
synced	After updating operational fields via PATCH: re-runs operation generation if conditions are met.
fetch_requested_from_erp	Only valid for authorizations synced from an external ERP. Asks DigiAnt to fetch the latest state from the ERP asynchronously.