API: cuenta y operaciones

Todo lo de esta página está acotado a la cuenta de la key. Contrato general en Cómo funciona la API.

La cuenta no se crea con una key

POST /accounts existe, pero exige un actor de nivel global o cliente: una key es de cuenta, así que recibe 403 accounts.actor_scope_not_allowed. Lo mismo con DELETE /accounts/:id y con activar/desactivar la propia cuenta (shared.self_scope_mutation).

Leer la cuenta

GET /accounts
GET /accounts/:id

GET /accounts devuelve una sola cuenta: la de la key. Query admitida: businessLine (eas/vending), isActive, search, page, pageSize (máx. 1000); clientId y accountId se ignoran.

Respuesta 200:

{
  "items": [
    {
      "id": "665f0f1c2e8a4b0012a3b4c6",
      "clientId": "665f0f1c2e8a4b0012a3b4c5",
      "taxId": "900123456",
      "companyName": "ACME Bogotá",
      "location": { "country": "Colombia" },
      "contact": { "name": "Juan Pérez", "phone": "6015551234", "mobile": "3001234567", "email": "juan@acme.co" },
      "businessLines": ["vending", "eas"],
      "currency": "COP",
      "consumerTagKeys": ["departamento", "cargo"],
      "isActive": true,
      "createdAt": "2026-01-15T14:02:11.000Z",
      "updatedAt": "2026-08-01T09:31:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

Editar la cuenta

PATCH /accounts/:id

Campo	Tipo	Obligatorio	Notas
companyName	string	no	mín. 2 caracteres
location.country	string	no	nombre del país (Colombia), no ISO
contact.name / .phone / .mobile	string	no	—
contact.email	string	no	correo válido

No se pueden cambiar taxId, currency ni businessLines. Respuesta 200 con la cuenta completa; 400 si el cuerpo trae campos no declarados.

Etiquetas de usuarios (tags)

Hasta 4 por cuenta. Definen qué claves aceptan los tags de un usuario.

POST   /accounts/:accountId/consumer-tag-keys      { "key": "Departamento" }
PATCH  /accounts/:accountId/consumer-tag-keys/:key { "newKey": "Sucursal" }
DELETE /accounts/:accountId/consumer-tag-keys/:key

POST devuelve 201 con la cuenta. Renombrar propaga el nombre a todos los usuarios que ya tenían la etiqueta; eliminar la borra de todos ellos. Errores: 409 consumers.duplicate_tag_key, 400 consumers.too_many_tags, 404 consumers.unknown_tag_key.

Operaciones

POST   /operations
GET    /operations
GET    /operations/:id
PATCH  /operations/:id
PATCH  /operations/:id/deactivate
PATCH  /operations/:id/activate
DELETE /operations/:id

Crear (201):

Campo	Tipo	Obligatorio	Notas
clientId	string	sí	debe ser el de la key
accountId	string	sí	debe ser el de la key
name	string	sí	mín. 2
location	objeto	sí	country, city, address, sublocation?, coordinates?
contact	objeto	sí	name, phone, mobile, email
businessLines	string[]	sí	subconjunto no vacío de las de la cuenta

{
  "clientId": "665f0f1c2e8a4b0012a3b4c5",
  "accountId": "665f0f1c2e8a4b0012a3b4c6",
  "name": "Sede Norte",
  "location": { "country": "Colombia", "city": "Bogotá", "address": "Cra 15 # 3-17" },
  "contact": { "name": "Ana Ruiz", "phone": "6015551234", "mobile": "3009876543", "email": "ana@acme.co" },
  "businessLines": ["vending"]
}

PATCH /operations/:id acepta name, location y contact (mismos campos, todos opcionales). Activar y desactivar responden 204 sin cuerpo. DELETE responde 204 y cascadea: dispositivos, perfiles, códigos de esa operación y operadores de ese ámbito; el ledger se conserva.

Query de listado: businessLine, isActive, search (nombre, ciudad o contacto), page, pageSize.

Errores propios: 404 operations.not_found, 403 operations.actor_scope_not_allowed, 400 operations.business_line_not_in_account.