Qué puede hacer cada usuario

Guía operativa por capacidad — con cURLs. Cada sección lista los comandos para ejecutar esa capacidad y un que indica que ya está implementado y verificado en el código.

Tabla de Permisos por Rol

Capacidad	Proveedor				Distribuidor (Dealer)
	owner	storekeeper	lead_creator	sales	owner	buyer	monitor	integration
Ver todos los tags (`/suntech/devices`)	✅	—	—	—	—	—	—	—
Ver posiciones (`/live`, `/historical`, SSE)	✅	403	403	403	su org	403	su org	403
Crear órdenes (`POST /orders`)	✅	—	—	✅	—	✅	—	—
Gestionar estado de órdenes (`PATCH /orders/:id/status`)	✅	✅	—	—	—	—	—	—
Crear leads (`POST /leads`)	✅	—	✅	—	—	—	—	—
Gestionar roles (`/memberships/grant`)	sub-roles	403	403	403	sub-roles dealer	403	403	403
API de integración (`/integration/v1/*`)	—	—	—	—	—	—	—	✅
Webhooks (`POST /integration/v1/webhook`)	—	—	—	—	—	—	—	✅

Ver todos los usuarios → Crear usuario y asignar rol →

Usuarios de mi organización

Miembros y roles registrados en tu cuenta.

0. Preparación — login + variables

Obtén el accessToken y define las variables base reutilizables en todos los ejemplos.

El Proveedor

Roles sobre el proveedor: owner storekeeper lead_creator sales — asignados con /memberships (scope suntech, sin organizationId).

owner

1. Owner del Proveedor — ve todos los tags

GET /suntech/devices devuelve los dispositivos agrupados por dealer (con bucket unassigned para inventario sin org). El owner además ve todas las posiciones vía el grant comodín asset:* viewer provider:#owner.

storekeeper

2. Almacenista — todo lo de envíos. Sin mapa

Recibe el correo de la orden y la surte como un todo (advance status + reporta seriales). Scopeado a las órdenes del proveedor. No ve posiciones (/live responde 403).

lead_creator

3. Creadores de Leads — no ven posiciones

Solo POST /leads (gate require_lead_creator: su / tagora / tag_provider / lead_creator|owner del proveedor). Sin grant de posiciones.

sales

4. Vendedores — órdenes a nombre de un Dealer

POST /orders. Puede ordenar para cualquier dealer. Solo-alta: no ve ni cambia el estado de las órdenes (eso es del storekeeper/owner). Manda exactamente uno de organizationId / organizationName. Cantidad múltiplo de 100.

solo owner

5. Solo el Owner del Proveedor ve posiciones

/live, /historical y /sse chequean viewer por asset. El owner lo cumple vía el comodín. storekeeper, lead_creator y sales no tienen ningún grant de posiciones → 403.

Distribuidores (Dealer) — minimizar permisos (fail-closed)

Roles sobre la org dealer: owner | buyer | monitor | integration. Un usuario sin rol no puede hacer nada (fail-closed) — el cliente final no tiene acceso hasta que un owner le conceda un rol.

owner

6. Owner del Dealer — crea usuarios de todo

El owner es superset (puede todo lo de buyer/monitor/integration). Da de alta a los usuarios con la macro /memberships/grant (find-or-create por email + correo de alta).

Roles dealer válidos para el owner: buyer | monitor | integration. Conceder owner está restringido a superuser / tagora (anti-escalada).

buyer

6b. Comprador — realiza pedidos para su org

Puede crear órdenes para su propia organización. No gestiona roles ni ve posiciones.

integration

7. Integración — credenciales de API

Al conceder role:"integration", la macro acuña api-key + secret (el secret se devuelve una sola vez). Esos usuarios consumen /integration/v1/* (login api-key → scope=integration).

monitor

8. Monitorista — ve posiciones de sus tags

monitor → viewer está cableado en el motor; los grants por asset apuntan al userset #viewer de la org. El monitor alcanza las posiciones de su org (no de otras).

sin rol

9. Cliente final (sin rol) — no puede nada

Un usuario logueado pero sin tupla ReBAC falla cerrado en todo: /live → 403, /orders → 403, /suntech/* → 403, /memberships/grant → 403. No hay acción que pueda ejecutar hasta que un owner le conceda un rol.

Macros de gestión de roles — /memberships

Componen los servicios atómicos (users + permissions + integration). Los owners de cada nivel administran sus propios sub-roles; conceder/revocar owner es sólo superuser/tagora.

Método y ruta	Para qué
GET /memberships/me	mis orgs + roles + nivel (post-login)
POST /memberships/grant	conceder un rol (find-or-create del usuario por userEmail, o userId)
POST /memberships/revoke	revocar un rol
GET /memberships?scope=&organizationId=	listar miembros + roles de una org/provider
POST /memberships/dealer	marcar/quitar una org como dealer del proveedor

¿Cómo "editar" un rol? No hay PATCH de rol: revoca el rol anterior y concede el nuevo. grant/revoke son idempotentes (granted/revoked=false si no hubo cambio), así que es seguro repetirlos.

Autorización (callback authorize en el router)

superuser / tagora owner → todo.
owner del dealer → conceder/revocar buyer|monitor|integration en su org.
owner del proveedor → conceder/revocar lead_creator|storekeeper|sales y manejar links de dealer.
conceder/revocar owner → sólo superuser / tagora.