Primeros pasos con BistroApi

BistroApi es la API pública de Bistrosoft, la plataforma de gestión de punto de venta. Permite consultar el detalle de transacciones de los comercios asociados a una cuenta, para integrar los datos operativos (ventas, cierres, ítems consumidos) con sistemas externos: ERPs, plataformas de BI, herramientas de conciliación contable, y cualquier otro consumidor que necesite acceso programático.

Esta guía recorre paso a paso lo necesario para pasar de cero a tu primera consulta exitosa contra la API.

Visión general

La integración con BistroApi sigue tres fases:

1. Autenticación — El consumidor obtiene un JWT válido a partir de un usuario de BistroWeb.
2. Consulta — Con el token, se realizan llamadas a los endpoints de reportes para obtener información filtrada por comercio y rango de fechas.
3. Procesamiento — La respuesta, en formato JSON paginado, se integra al sistema consumidor según su lógica específica.

Prerrequisitos

Antes de comenzar, verifica que dispones de:

• Una cuenta en BistroWeb con acceso a los comercios que necesitas consultar.
• El rol ApiUser o Administrador asignado al usuario en la plataforma. Determina qué versión de la API puede consumirse (v1 o v2 respectivamente).
• Un cliente HTTP con soporte para TLS 1.2+ y parseo de JSON. Cualquier lenguaje moderno lo cumple (C#, Java, Python, Node.js, Go, etc.).

Tu primera consulta

Paso 1: Obtener un token

El endpoint de autenticación acepta las credenciales de BistroWeb y devuelve un JWT con validez de 2 días:

curl -X POST https://preprod-mx-api.bistrosoft.com/api/v1/Token \
  -H "Content-Type: application/json" \
  -d '{"username":"[email protected]","password":"tu-contraseña"}'

Respuesta típica:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiration": "2026-04-25T18:32:00Z"
}

Guarda el valor de token; lo necesitas en cada llamada posterior.

Paso 2: Consultar un endpoint de reporte

Con el token obtenido, ya puedes consultar los endpoints de reportes. Por ejemplo, el detalle de transacciones entre dos fechas:

curl "https://preprod-mx-api.bistrosoft.com/api/v1/TransactionDetailReport?fromDate=2026-04-01&toDate=2026-04-22" \
  -H "Authorization: Bearer <tu-token>"

La API devuelve las transacciones de todos los comercios habilitados para el usuario asociado al token. No es necesario especificar los códigos de comercio: están presentes como claim dentro del JWT y se aplican automáticamente como filtro.

Paso 3: Procesar la respuesta

Las respuestas se entregan en formato JSON paginado. Consulta la referencia de TransactionDetailReport para ver el esquema exacto de la respuesta según la versión utilizada.

Desde aquí, el sistema consumidor puede iterar las páginas de resultado, persistir los datos, o aplicar las transformaciones que requiera el caso de uso.

Versiones: v1 vs v2

BistroApi ofrece dos versiones en paralelo:

• v1 es la versión estable. Devuelve los montos como strings y no incluye el detalle de ítems vendidos por transacción.
• v2 es la versión ampliada. Devuelve montos numéricos, incluye los ítems consumidos por cada transacción, y permite filtrar por múltiples comercios separados por coma en una sola llamada.

La elección depende del caso:

• Si solo se necesitan totales por transacción, v1 es suficiente.
• Si se requiere detalle de ítems (por ejemplo, para reportería de productos o conciliación de inventario), usar v2.

Para acceder a v2, el usuario debe tener el rol Administrador.

Siguientes pasos

• Autenticación — Detalle completo del flujo JWT, estructura del token y errores comunes.
• Introducción (API Reference) — Resumen técnico en 3 pasos.
• Endpoints — Catálogo completo con Try It interactivo.