Skip to main content
El POS Bridge conecta un sistema de punto de venta con el módulo de pedidos por WhatsApp de Xenda. El bot toma pedidos conversando con el cliente final, los valida y cotiza contra el catálogo que tu sistema mantiene sincronizado, y tu POS los levanta para que el local los acepte, prepare y entregue.

​
Cómo fluye la información

Todo el tráfico lo origina tu sistema. Xenda nunca llama a tu POS ni accede a tus bases: tu sistema empuja el catálogo, consulta los pedidos y informa los cambios de estado, siempre contra esta API.
Un intervalo de polling de 1 a 2 minutos es suficiente; la respuesta está pensada para ser liviana.

​
Autenticación: una key por sucursal

Cada sucursal tiene su propia API key (xnd_...). La key es la sucursal: todo lo que hagas con ella queda scopeado a ese local, y no puede tocar ningún otro. Se envía en todas las llamadas:
Base URL:
El campo store_id del body es opcional y funciona como verificación cruzada: si lo mandás y no coincide con la sucursal de la key, la llamada se rechaza con 403. Sirve para detectar el clásico error de configuración de “pegué la key del local equivocado”.
Tratá cada key como una credencial sensible. Si una key se compromete, avisanos: emitimos una nueva y revocamos la anterior. Solo afecta a esa sucursal. Ver Pasar una sucursal a producción.

​
Límite de requests

Cada key admite hasta 120 requests por minuto — muy por encima del uso normal (un poll cada 1-2 minutos + eventos de catálogo). Si te pasás, recibís 403 con rate_limited: retry in Xs; esperá ese tiempo y reintentá. Si tu integración necesita más, hablemos: el límite es configurable por sucursal.

​
Identificadores: tus códigos mandan

Los productos y opciones se identifican por el codigo: un string estable que define tu sistema (el ID interno de tu base). Xenda guarda el mapeo codigo ↔ producto por sucursal, y los pedidos vuelven con esos mismos códigos — tu POS nunca necesita conocer IDs de Xenda. Reglas del codigo:
  • Estable en el tiempo (si cambia, se interpreta como un producto nuevo).
  • Único dentro de la sucursal por tipo (producto u opción).
  • Cualquier string te sirve: "1001", "HEL-KILO", un hash — lo que ya uses.
  • Eventos durante el día: cambio de precio, alta de producto, baja de un sabor — empujás el evento en el momento y el bot deja de ofrecer lo que ya no está.
  • Sincronización de cierre/apertura: podés empujar el catálogo completo como un lote grande; los ítems sin cambios simplemente se re-aplican.
  • Idempotencia: cada request lleva un event_id único. Si reintentás con el mismo event_id, devolvemos duplicate: true y no se reprocesa nada — reintentar es siempre seguro.
  • Orden de eventos: cada request lleva occurred_at (cuándo ocurrió el cambio en tu sistema). Si un evento llega tarde y hay uno más nuevo ya aplicado, el viejo se descarta (skipped_stale) — un cierre de caja demorado nunca pisa un cambio de precio posterior.
  • Errores por ítem: un ítem inválido no rechaza el lote. La respuesta indica accepted y rejected[{codigo, error}] para que reproceses solo lo que falló.
  • Bajas: action: "delete" desactiva el ítem (deja de ofrecerse). Nunca se borra físicamente: los pedidos históricos siguen siendo legibles.

​
Lo que NO tenés que construir

La integración está pensada para que tu lado sea lo más chico posible:
  • Sin webhooks: no exponés ningún endpoint ni URL pública. Tu POS llama, nunca es llamado.
  • Sin OAuth ni tokens que renovar: una key estática por sucursal en un header.
  • Sin IDs de Xenda: trabajás siempre con tus propios códigos. El mapeo lo mantenemos nosotros.
  • Sin manejo de conversaciones: el bot, WhatsApp, las notificaciones al cliente final y la plataforma de gestión son 100% lado Xenda.
Tu integración completa son 3 llamadas en el camino crítico: empujar catálogo, consultar pedidos, informar estados.

​
Sandbox

Te entregamos una key de sandbox apuntada a una sucursal demo con catálogo y pedidos de prueba. Es un entorno real (misma API, misma URL) pero aislado: todo lo que hagas queda contenido en esa sucursal. Podés empujar catálogo, aceptar y rechazar pedidos, probar reintentos y romper lo que necesites. Empezá por el Quickstart: en 10 minutos recorrés el ciclo completo. Cuando el piloto pase a producción, la sucursal real recibe su propia key — mismo contrato, cero cambios de código.

​
Pasar una sucursal a producción

El alta de cada sucursal la hace Xenda. Esto es lo que recibís y lo que hay que dejar listo antes de que el bot empiece a tomar pedidos.

​
1. Credenciales

Por cada sucursal te entregamos tres datos:
  • La key se muestra una sola vez. Xenda no guarda el valor: si se pierde, se emite otra.
  • Una sucursal puede tener varias keys activas a la vez (por ejemplo, una por computadora). Cada una tiene su propio límite de requests y se revoca por separado.
Dos caminos, a elección:
  • Empujás el catálogo completo por la API, como un lote grande de productos y otro de opciones.
  • Nos mandás un CSV de productos (Codigo, Nombre, Categoria, Precio, Deshabilitado) y otro de sabores (Codigo, Nombre, NoUsar) y lo cargamos nosotros con tu key, por el mismo camino que usaría tu sistema.

​
3. Qué productos llevan sabores

Empujar opciones no las asocia a ningún producto: POST /v1/catalog/options carga el listado de sabores de la sucursal, y max_opciones en el producto dice cuántos admite. Qué productos llevan opciones, de qué grupo y cuántas como mínimo se configura del lado Xenda. Es un paso de la puesta en marcha que hacemos con el local después de la carga inicial. Si más adelante sumás un producto nuevo que lleva sabores, avisanos o avisale al local: hasta que se configure, ese producto no ofrece sabores.

​
4. Prueba de punta a punta

POST /v1/test/orders también funciona con la key de una sucursal real, y es la forma más directa de validar la instalación. Tené en cuenta que ahí el pedido es real: aparece en la plataforma del local, y cada cambio de estado intenta avisarle por WhatsApp al telefono que mandes. Usá un teléfono tuyo y cerrá el pedido al terminar.

​
5. Cambiar una key

  1. Pedinos una key nueva para la sucursal.
  2. Instalala. La anterior sigue funcionando mientras tanto: no hay corte.
  3. Avisanos y revocamos la anterior. La revocación es inmediata: la siguiente llamada con esa key recibe 403 Invalid API key.
La deduplicación por event_id es por key. Después de cambiar de key, un evento viejo reenviado con la key nueva se procesa como si fuera nuevo: no reenvíes lotes anteriores al cambio. El orden por occurred_at sigue protegiendo el catálogo (un evento más viejo que el dato vigente se descarta).