Convenciones
Autenticación
El contrato de autenticación de la Transactions API v1, endpoint por endpoint, con vencimientos y permisos
Actualizado el 2026-08-16Para: Desarrolladores
Esta página es el contrato de la Transactions API v1. Si buscás el paso a paso, está en la guía de Autenticación. La Catalog API y la Transactions API v2 tienen otro esquema: API key y secret contra la Authorization API, con un token que no lleva comercios adentro.
Esquema
| Concepto | Valor |
|---|---|
| Tipo | JWT firmado, emitido por la Transactions API |
| Endpoint de emisión | POST /api/v1.0/Token |
| Transporte | Header Authorization |
| Formato del header | Bearer + espacio + token |
| Vigencia | 2 días desde la emisión |
| Renovación | No hay refresh: se vuelve a emitir con usuario y contraseña |
| Permiso requerido | Rol ApiUser en BistroWeb |
| Alcance de los datos | Los shop_code presentes en los claims del token |
| Baja de credenciales | Dar de baja el usuario impide emitir tokens nuevos; el emitido sigue válido hasta vencer |
Todos los endpoints requieren token
Todos los endpoints de lectura exigen el header Authorization. El único endpoint
anónimo es POST /api/v1.0/Token, que es justamente el que lo emite.
No hay endpoints públicos y no hay autenticación por IP. Sí existen API keys, pero son de la Authorization API y sirven para la Catalog API y la Transactions API v2, no para esta.
Cuerpo del pedido de token
{
"username": "integraciones@empresa.com",
"password": "..."
}
Ambos campos son obligatorios y son las credenciales de BistroWeb, no una credencial aparte.
Respuesta
{
"token": "eyJ...",
"expiration": "2026-08-18T13:04:22Z"
}
expiration está en UTC y sigue el formato ISO 8601 descrito en
Fechas y zonas horarias.
El esquema declarado y el real
En el documento OpenAPI, la seguridad está declarada como
{"type": "apiKey", "in": "header", "name": "Authorization"} en lugar de
{"type": "http", "scheme": "bearer"}. Es una diferencia de declaración, no de
comportamiento: el servidor espera igual el prefijo Bearer. Importa porque los
generadores automáticos de clientes y de snippets emiten, a partir de esa
declaración, un header crudo sin prefijo. Si usás un cliente generado y recibís
401 con un token que sabés bueno, revisá el valor exacto del header.
Este portal normaliza el esquema al cargar el spec, así que los ejemplos de código que ves acá ya salen con el prefijo correcto.
Qué se puede probar desde el portal
- En preproducción, el portal puede pedirte usuario y contraseña para emitir un token de prueba.
- En producción, el portal nunca pide contraseña: solo acepta que pegues un token que ya tengas, y solo deja ejecutar métodos de lectura.
Es una decisión deliberada. Un sitio de documentación que pide credenciales de producción entrena a los usuarios a hacer exactamente lo que hace un phishing.