Enrolar un equipo y alcances de clave

Un equipo del mostrador (la caja, el PC del autoservicio, el terminal Android) no lleva una clave API de tu comercio. Se enrola con un código de un solo uso que emites en Equipos; el Merchant le entrega su propia credencial de dispositivo, acotada a ese equipo y a su sucursal. Las claves API quedan para sistemas: tu ERP, tu tienda web, tu facturación.

Cómo enrolar un equipo

1. En el portal, entra en Equipos → Enrolar equipo. Elige la sucursal, el tipo (PC Windows = Toolbox + Caja + Pago, o Android = AuroraPOS) y ponle un nombre («Caja 2 Mercedes»).
2. Obtienes un código como K7QM-2R9X (8 caracteres sin 0/O/1/I/L): vence en 24 horas y sirve una sola vez. Al emitirlo, el Merchant ya reserva los TID (TBOX/CAJA/PAGO para un PC; MOTO para AuroraPOS): aparecen en Flota como inactivos hasta que el equipo canjea el código.
3. En el equipo:
   • PC Windows: descarga FINORA Toolbox (Windows 10 o superior; se instala por usuario, sin permisos de administrador), ábrelo y pega el código en «Enrolar este equipo». El Toolbox recibe los tres TID (TBOX, CAJA, PAGO) bajo el mismo serial, escribe los .conf e instala FINORA Caja y FINORA Pago.
   • Android: abre AuroraPOS → «Enrolar» y escribe el código. El terminal recibe su TID y queda vinculado a la sucursal.
4. El código pasa a Usado (y deja de mostrarse) y el equipo aparece en Equipos con su primer latido. Si el código vence o se filtra, revócalo y emite otro: los TID reservados quedan inactivos, listos para otro código.

Lo que el portal llama al Merchant, por si lo integras desde tu software (permiso portal.equipos):

# PC Windows completo (usuario del portal con token OAuth2; no con X-API-Key). `sucursal` = id de GET /yo.sucursales
curl -s -X POST https://pos.finoracore.com/api/v1/portal/flota/enrolar \
  -H "Authorization: Bearer $TOKEN_PORTAL" -H "Content-Type: application/json" \
  -d '{"sucursal": 41, "perfil": "PC_COMPLETO", "crear": {"nombre": "Caja 2 Mercedes"}, "ttlHoras": 24}'
# → 201 { "id": 7, "codigo": "K7QM-2R9X", "expiraEn": "…", "estado": "PENDIENTE", "perfil": "PC_COMPLETO",
#         "app": "FINORA-TOOLBOX", "terminalId": "TBOX0003", "equipos": {"toolbox": "TBOX0003", "caja": "CAJA0004", "pago": "PAGO0002"}, … }

# Un terminal Android nuevo con AuroraPOS
curl -s -X POST https://pos.finoracore.com/api/v1/portal/flota/enrolar \
  -H "Authorization: Bearer $TOKEN_PORTAL" -H "Content-Type: application/json" \
  -d '{"sucursal": 41, "perfil": "TERMINAL", "app": "AURORAPOS", "crear": {"tipo": "ANDROID", "nombre": "Tablet mostrador"}}'

curl -s "https://pos.finoracore.com/api/v1/portal/flota/enrolamientos?estado=PENDIENTE&max=50" -H "Authorization: Bearer $TOKEN_PORTAL"
curl -s -X POST https://pos.finoracore.com/api/v1/portal/flota/enrolamientos/7/revocar -H "Authorization: Bearer $TOKEN_PORTAL"

Estados de un código: PENDIENTE (único estado en el que viaja codigo) → USADO (con usadoEn, usadoPorSerial, usadoPorHostname) | VENCIDO | REVOCADO. Revocar uno que ya no está pendiente responde 409 CODIGO_USADO / 410 CODIGO_VENCIDO / 409 CODIGO_REVOCADO. También se puede reenrolar un TID existente con {"terminalId": "CAJA0002", "app": "FINORA-CAJA"} en lugar de crear.

nota

Un equipo enrolado se ve en Equipos agrupado por serial (un PC = tres TID) y en Flota terminal a terminal. Desde Flota se reasigna de sucursal, se suspende o se le mandan comandos; desde Equipos se enrola y se revocan códigos.

Quién puede hacer qué

Rol del portal	Ve	Descarga del marketplace	Enrola equipos	Claves API y usuarios
Operador (portal-comercio)	Panel, Monitoreo, Flota, Ventas, Lotes, Liquidaciones, Licencias	No	No	No
Autorizado a instalar (portal-comercio-equipos)	Lo anterior + Marketplace con descarga + Equipos	Sí (portal.descargas)	Sí (portal.equipos)	No
Gerente (portal-comercio-admin)	Todo	Sí	Sí	Sí (portal.claves-api, portal.usuarios) y cobrar

Cuando entras a una sección que tu rol no alcanza, el portal te dice qué permiso falta (por ejemplo portal.equipos) y te da el mensaje para pedírselo al administrador de tu comercio. El administrador asigna el rol en Usuarios.

Alcances de una clave API

Al crear una clave en Claves API eliges su alcance, su caducidad (30, 90, 365 días o sin caducidad; el Merchant admite hasta 2 años) y, solo para el alcance EQUIPOS, una sucursal.

Alcance	Qué puede hacer	Para qué sirve
INTEGRACION	/api/v1/pagos/** (intenciones, despacho, devoluciones), /api/v1/checkout/** y el feed del marketplace	ERP, tienda web, sistema de delivery o facturación: cobra y consulta, no gobierna equipos. Es el que casi siempre necesitas.
EQUIPOS	/api/v1/pos/devices/activar y el feed del marketplace (/api/v1/marketplace/feed/**). Rechazada en todo lo demás.	Instalación por IT/GPO sin código de enrolamiento; queda dentro del PC con daño acotado. Para un equipo suelto usa Enrolar equipo.
COMPLETO	Todo lo que acepta X-API-Key, incluidas las agencias del comercio.	ERP central o integrador de confianza. Una clave completa filtrada compromete todo el comercio.

Una clave EQUIPOS con sucursal solo activa terminales de esa sucursal (403 CLAVE_SIN_ACCESO_A_SUCURSAL para los demás). Una ruta fuera del alcance responde 403 CLAVE_SIN_ALCANCE; una clave vencida, 401 CLAVE_VENCIDA en cualquier ruta (sigue en la lista como «Vencida» hasta que la revoques).

curl -s -X POST https://pos.finoracore.com/api/v1/portal/claves-api \
  -H "Authorization: Bearer $TOKEN_PORTAL" -H "Content-Type: application/json" \
  -d '{"etiqueta": "ERP Odoo · cobros", "alcance": "INTEGRACION", "expiraEn": "2027-09-14T00:00:00Z"}'
# → 201 { "detalle": { "prefijo": "Qx7Lm2Pa", "alcance": "INTEGRACION", "expiraEn": "…", "vencida": false, "sucursal": null, … }, "clave": "<43 caracteres, una sola vez>" }
# Clave de equipos acotada a una sucursal: "alcance": "EQUIPOS", "sucursal": 41  (id de GET /yo.sucursales)

peligro

Nunca pongas una clave API en un equipo del mostrador, en el navegador ni en un repositorio. Para el mostrador está el código de enrolamiento; para el navegador, el token de sesión del checkout.