Autenticación y alcance

Credencial	Cabecera	Quién la tiene	Para qué
Clave API	X-API-Key: <43 caracteres>	Tu servidor, nunca el navegador	Según su alcance: /api/v1/checkout/** (crear, consultar, cancelar sesiones, probar webhook), /api/v1/pagos/** (INTEGRACION y COMPLETO), /api/v1/pos/devices/activar y el feed (EQUIPOS y COMPLETO), /api/v1/tms/** (COMPLETO)
Token de sesión	Authorization: Bearer <token> (o ?t=)	El navegador o la app del cliente, por una sesión	GET/POST /api/v1/checkout/sesiones/{id}/{medio,estado,cancelar}
Token de dispositivo	Authorization: Bearer <deviceToken>	El terminal (AuroraPOS)	/api/v1/pos/** (órdenes, comandos, latido, parámetros, licencias)
Token OAuth2 del portal	Authorization: Bearer	Un usuario de tu comercio tras iniciar sesión	/api/v1/portal/** (lo que ves en este portal)

Clave API

Pertenece a tu comercio: 32 bytes aleatorios en base64url (43 caracteres). Se muestra una sola vez al crearla en Claves API (o con «Crear clave sandbox» en el Centro de desarrolladores); el Merchant guarda solo su SHA-256 y los primeros caracteres para reconocerla. Quien la pierde la revoca y crea otra. Cada clave tiene un alcance (INTEGRACION, EQUIPOS o COMPLETO), una caducidad y, opcionalmente, una sucursal: ver Enrolar un equipo y alcances de clave. Un equipo del mostrador no lleva clave API: se enrola con un código.

Alcance (regla D9). La clave identifica al comercio que llama y de ahí se deriva sobre qué comercios puede actuar:

Clave de…	Puede actuar sobre
Un comercio PRINCIPAL	Él mismo y sus agencias
Una AGENCIA	Solo la agencia

Se aplica en todos los endpoints: el merchantCode del cuerpo, el comercio de la intención o el del terminal tienen que estar en el alcance. Violación → 403 CLAVE_SIN_ACCESO_AL_COMERCIO (o DESPACHO_NO_PERMITIDO al empujar a un terminal ajeno).

curl -s https://pos.finoracore.com/api/v1/pagos/rieles?merchantCode=COM00042 -H "X-API-Key: $FINORA_API_KEY"

peligro

Nunca pongas la clave en el navegador, en una app móvil ni en un repositorio. Una clave filtrada compromete tu comercio (no la plataforma): revócala de inmediato y crea otra.

Token de sesión

Lo devuelve POST /api/v1/checkout/sesiones y solo viaja en esa respuesta. Sirve para esa sesión: no puede crear otras ni cambiar el monto, y vence con ella. CORS abierto para esas rutas, 60 peticiones por minuto por sesión (429 DEMASIADAS_PETICIONES). Token ausente, inválido o de otra sesión: 401 TOKEN_INVALIDO.

Token de dispositivo

Lo recibe AuroraPOS al activar el terminal; identifica terminal, comercio y serial. El terminal nunca manda terminalId: se usa el del token, así que un equipo no puede sondear, aceptar ni reportar por otro. Si desarrollas software para el terminal (por ejemplo, un plugin ECR), el token lo gestiona la app; tu software habla con el terminal por la API ECR local en la LAN de la tienda.

OAuth2 del portal

Este portal entra con authorization code + PKCE contra el servidor de identidad del Merchant (https://pos.finoracore.com/.well-known/openid-configuration). Si construyes tu propia herramienta administrativa sobre /api/v1/portal/**, usa el mismo flujo con tu propio cliente OAuth2 registrado por el operador; los permisos (portal.comandos, portal.comandos.cobrar, portal.claves-api, portal.usuarios) salen de GET /api/v1/portal/yo.

Buenas prácticas

• Una clave por sistema (caja, ERP, tienda web) con etiqueta clara: revocar una no tumba las demás.
• idempotencyKey en cada intención y referencia única por sesión: reintenta sin miedo tras un corte de red.
• Verifica siempre la firma del webhook; el JavaScript del navegador no es una fuente de verdad.
• Guarda sesionId junto a tu pedido: GET /api/v1/checkout/sesiones/{id} con tu clave responde el estado real en cualquier momento.