Autenticación

Cómo pedir un token, cuánto dura, qué rol necesita tu usuario y cómo manejar el vencimiento sin refresh

Actualizado el 2026-08-16Para: Principiantes · Desarrolladores

Esta página es de la Transactions API v1, que se autentica con las credenciales de BistroWeb. Cuenta cómo obtener el token, cómo usarlo y —sobre todo— cómo convivir con que dure dos días y no exista forma de renovarlo sin volver a autenticarse.

La Catalog API y la Transactions API v2 no usan este esquema: se autentican con una API key y un secret contra la Authorization API, y su token no lleva comercios adentro. Todo lo que sigue vale para la v1.

El flujo completo

usuario + contraseña de BistroWeb
        │
        ▼
POST /api/v1.0/Token
        │
        ▼
JWT válido por 48 horas
        │
        ▼
Authorization: Bearer <token>  en cada request

Pedir el token

curl -X POST "https://$BISTRO_HOST/api/v1.0/Token" \
  -H "Content-Type: application/json" \
  -d '{"username": "integraciones@empresa.com", "password": "..."}'

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiration": "2026-08-18T13:04:22Z"
}

expiration viene en UTC. Guardalo junto al token: es lo que te permite pedir uno nuevo antes de que se caiga la integración, en vez de después.

Usar el token

GET /api/v1.0/sales?ShopCode=1001&From=2026-08-01T00:00:00&To=2026-08-02T00:00:00
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

El prefijo Bearer va sí o sí

El esquema de seguridad está declarado en el OpenAPI como una API key en el header Authorization, no como autenticación HTTP Bearer. La consecuencia práctica es que algunos generadores de código emiten el header sin el prefijo, y el servidor responde 401 sin decir por qué. El valor del header tiene que ser exactamente Bearer, un espacio, y el token.

El rol ApiUser

Las credenciales de la Transactions API son las mismas de BistroWeb, pero el permiso no. Un usuario que entra perfecto a BistroWeb puede recibir 403 en la API porque le falta el rol ApiUser.

Se lo asigna un administrador desde BistroWeb, en el perfil del usuario. Si estás armando la integración para un cliente, pedile este rol al principio: es la causa número uno de arranques trabados.

Un usuario dedicado para la integración

Conviene crear un usuario específico para la integración, con el rol ApiUser y los locales que necesite, en vez de reutilizar el usuario de una persona. Cuando esa persona se va de la empresa y le dan de baja el usuario, la integración no se cae con ella.

Qué locales ve tu token

El JWT de la v1 lleva adentro claims shop_code con los locales habilitados para el usuario. La API filtra por ellos en cada consulta, así que:

Pedir un local que no está en tu token no devuelve datos ajenos: devuelve vacío.
Agregarle un local nuevo al usuario en BistroWeb no cambia los tokens ya emitidos. Hay que pedir un token nuevo para que el local aparezca.

Ese segundo punto explica la mayoría de los "le di permiso y sigue sin verlo".

El access token de la Authorization API funciona al revés: no lleva comercios, solo el client_id y los scopes, y cada API resuelve qué comercios puede operar la credencial en cada pedido. Ahí agregar un comercio se ve sin pedir un token nuevo.

Vencimiento sin refresh

El token dura 2 días y no hay endpoint de refresh. El patrón correcto:

import time
import requests

_token = None
_expires_at = 0.0

def get_token(host: str, username: str, password: str) -> str:
    global _token, _expires_at
    # Se renueva 5 minutos antes del vencimiento real, para no quedar
    # a mitad de camino en un batch largo.
    if _token and time.time() < _expires_at - 300:
        return _token

    response = requests.post(
        f"https://{host}/api/v1.0/Token",
        json={"username": username, "password": password},
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    _token = payload["token"]
    _expires_at = time.time() + 2 * 24 * 60 * 60
    return _token

Tres reglas que se desprenden de esto:

No pidas un token por request. El endpoint de token es el más caro de todos y no está pensado para eso.
No guardes el token para siempre. A las 48 horas empieza a devolver 401 y el proceso nocturno se cae en silencio.
Reintentá una sola vez ante un 401, pidiendo token nuevo. Si el segundo intento también falla, el problema son las credenciales o el rol, y reintentar otra vez solo bloquea la cuenta.

Dónde no poner el token

No lo pongas en la URL como query param: queda en los logs de todos los proxies del camino.
No lo empaquetes en una aplicación web ni móvil. El token habilita a leer las ventas de todos los locales del usuario; vive en el backend.
No lo compartas entre clientes distintos: cada empresa integra con su propio usuario.