Totem Groups

A totem group (totem_group) is the set of physical access points — scales, barriers, screens — that manage entries and exits at a specific facility. It represents the physical "where" of each authorization: every authorization is linked to exactly one totem group.

What is a totem

A totem is a physical device installed at the entrance or exit of a facility (warehouse, cooperative, grain silo, port…). When a driver arrives, they interact with the totem to identify themselves and register the operation. The totem validates in real time whether an active authorization exists for that carrier and records the corresponding operation.

What is a totem group

A facility may have multiple totems (e.g. several scales or access lanes). A totem group bundles all access points of a single facility under one identifier — the totemGroupId. When you create an authorization for that group, the driver can operate it at any totem within the group.

Each group belongs to a single logistics company (logistics_company_id). You cannot access groups belonging to other logistics companies with your API Key.

How to get the totemGroupId

Use the listing endpoint to retrieve the groups available to your logistics company:

GET /partner/totem-groups
X-Partner-API-Key: dpk_live_...

The response includes the id (UUID) and descriptive name of each group. Store those UUIDs in your system — they are what you pass as totemGroupId when creating authorizations.

You can also fetch a specific group by UUID:

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

TotemGroupDto fields

Field	Type	Description
id	uuid	Unique group identifier. Use this as totemGroupId in authorizations.
name	string	Descriptive name of the facility (e.g. "Northern Seville Warehouse").
logisticsCompanyId	uuid	Logistics company that owns the group.
createdAt	datetime	Creation timestamp (ISO 8601).
updatedAt	datetime	Last update timestamp (ISO 8601).

Use in the integration flow

totemGroupId is a required field when creating an authorization. The recommended flow for your ERP integration is:

1. During setup (once), call GET /partner/totem-groups and map each group to the corresponding warehouse or facility in your ERP.
2. Store the mapping ERP facility → totemGroupId in your configuration.
3. When creating each authorization, use the totemGroupId that matches the operation's facility.

tip

Totem groups change rarely — they are created when DigiAnt installs new equipment at a facility. You do not need to fetch them on every push; syncing periodically or when the facility notifies you of a change is enough.

Logistics company isolation

The API automatically filters by your logistics company: you will only see groups that belong to you. It is not possible to list or use groups from other logistics companies, even if you know their UUID.

If you try to create an authorization with a totemGroupId that does not belong to your logistics company, you will receive a 422 error.

See also Key Entities and Authorization.