Requisitos de API para POS y ERP

1. Alcance

Beliberi consulta la API del comercio cada 15 minutos y reconstruye su catálogo completo: productos, precios, existencias por sede, categorías y fotos. El comercio no instala nada: expone la API, entrega una credencial y Beliberi la conecta desde su consola con el conector "API REST genérica".

La API es de solo lectura desde el punto de vista del POS: Beliberi lee, nunca escribe en el inventario. El envío de pedidos hacia el POS es opcional y se describe en la sección de endpoints opcionales.

Un ERP que ya expone una API estructurada (Odoo, Revel, KLK) se conecta con su conector propio; este documento cubre el caso general de un sistema que aún no tiene integración con Beliberi.

2. Autenticación y transporte

La API se sirve por HTTPS con certificado válido, en JSON codificado en UTF-8, y acepta una credencial propia por comercio que el comercio puede revocar sin afectar a otros clientes de su sistema.

• La credencial la guarda Beliberi en su gestor de secretos; nunca aparece en la consola ni en registros. El comercio entrega el valor una vez, por un canal seguro, y puede rotarlo cuando quiera.
• Un token con caducidad corta (menos de 24 horas) o que exija renovarse con un flujo OAuth no es compatible con el conector genérico; en ese caso se acuerda un token de servicio de larga duración.
• Si la API restringe por IP, Beliberi comunica las direcciones de salida de su plataforma antes de la puesta en marcha.
• Las peticiones llevan Accept: application/json y User-Agent: Beliberi-Catalog-Sync/1. Las respuestas deben ser Content-Type: application/json.
• Sin credencial válida la API responde 401; con credencial válida pero sin permiso, 403. Beliberi muestra ambos como "credencial rechazada" en la consola del comercio.

3. Catálogo de productos

Un endpoint GET /productos devuelve todos los productos vendibles con estos campos por ítem. Los nombres de los campos y su ubicación en el JSON pueden ser los del sistema del comercio: Beliberi los mapea desde la consola con rutas por puntos (precio.usd, categoria.codigo). Lo que no puede faltar es el dato.

Reglas del catálogo

• Un SKU aparece una sola vez por sede. Si el POS maneja variantes (talla, color), cada variante es un producto con su propio SKU y su código de barras.
• El precio es el vigente para venta al detal en la sede consultada. Los descuentos por promoción se reflejan en el precio o en el campo opcional precio_descuento (número, precio final ya rebajado).
• La moneda del catálogo es una sola para todo el comercio y se declara en la puesta en marcha (USD o VES). Beliberi convierte a bolívares con la tasa del día.
• Los productos con stock en 0 o activo en false deben seguir apareciendo en la respuesta durante al menos 30 días; si un SKU desaparece de la lista, Beliberi lo marca como no disponible.
• Las fotos se descargan una vez y se vuelven a pedir solo si cambia la URL; una URL que cambia con cada consulta (firmas con caducidad) hace que se descarguen en cada sincronización.

4. Existencias por sede o almacén

Cada sede de Beliberi vende el stock de un almacén del POS, así que la API tiene que poder responder por almacén. Se acepta cualquiera de estas tres formas, de la más simple a la más completa.

• El código de almacén es estable y lo define el comercio; Beliberi lo asigna a cada sede en la consola. Varios almacenes pueden sumar existencias para una misma sede.
• El stock es la cantidad vendible ahora (descontadas reservas y mermas), no el físico. Si el POS reserva al vender en tienda, la cifra debe reflejarlo.
• Un producto sin fila de existencias para un almacén se toma como stock 0 en esa sede.
• Si el precio varía por sede, la forma 1 o la forma 3 (con precio en la fila) lo resuelven; la forma 2 asume un precio único.

5. Paginación y cambios incrementales

Hasta 2.000 productos la respuesta puede venir completa en una sola página. Por encima, la API pagina con uno de estos modos, todos soportados por el conector.

Beliberi lee como máximo 500 páginas o 10 minutos por sincronización; un catálogo que no cabe en eso se acuerda con paginación de 1.000 ítems o con un endpoint de existencias aparte.

6. Formato de respuesta y errores

La respuesta es un objeto JSON con la lista de productos y, si hay paginación, un bloque meta. La lista puede estar en la raíz o en cualquier ruta (data.productos); Beliberi la indica al configurar la conexión.

{
  "data": [
    {
      "sku": "A-10493",
      "nombre": "Aceite de oliva 500 ml",
      "precio": 6.50,
      "precio_descuento": null,
      "iva": 16,
      "stock": 12,
      "codigo_barras": "7591234567890",
      "categoria_codigo": "ACE",
      "categoria_nombre": "Aceites y vinagres",
      "subcategoria_codigo": "ACE-OLI",
      "subcategoria_nombre": "Aceite de oliva",
      "marca": "Marca de ejemplo",
      "imagen_url": "https://cdn.comercio.com/a10493.jpg",
      "activo": true,
      "unidad": "unidad",
      "peso_gramos": 520,
      "actualizado_en": "2026-09-24T13:05:00-04:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 500,
    "total": 1834,
    "next": "https://api.comercio.com/productos?page=2&per_page=500"
  }
}

Los errores llevan cuerpo JSON {"error": {"code": "...", "message": "..."}} con un mensaje legible: se muestra tal cual al personal del comercio.

Reglas de formato

• Números como números JSON (6.50), no como texto con coma ("6,50"). Si el sistema solo puede devolver texto, se acuerda y Beliberi lo convierte.
• Fechas en ISO 8601 con zona horaria.
• Campos ausentes o null cuentan como vacíos; no hace falta enviar los opcionales que no se usan.
• Codificación UTF-8 sin BOM; acentos y eñes correctos en nombres y categorías.

7. Endpoints opcionales

Con el endpoint de productos basta para vender. Estos endpoints mejoran la experiencia o cubren casos concretos; se activan uno a uno en la consola.

Envío de pedidos al POS, si se activa

• Beliberi lo llama al aprobarse el pago (o al aceptar el pedido, en comercios que preparan ellos mismos) y reintenta hasta 5 veces con espera creciente si el POS no responde.
• La petición lleva una clave de idempotencia (Idempotency-Key, el número de pedido de Beliberi): el mismo pedido enviado dos veces no debe crear dos ventas.
• El POS responde 201 con {"pedido_pos": "F-000123"}; ese número se muestra en la consola y en la app del picker.
• Los cambios posteriores (línea sin stock, sustitución aceptada, cancelación) se envían como PATCH /pedidos/{pedido_pos} con el estado y las líneas finales.

Avisos del POS a Beliberi, si se activan

Llevan una firma HMAC en la cabecera X-Beliberi-Signature con un secreto compartido, y Beliberi responde 202 y aplica el cambio en menos de un minuto. Un aviso no sustituye a la sincronización periódica, que sigue cuadrando todo.

8. Requisitos no funcionales

9. Puesta en marcha

El comercio entrega cuatro cosas y Beliberi conecta en la consola sin desarrollo adicional.

1. URL base de la API (pruebas y producción) y la ruta del endpoint de productos.
2. Credencial por un canal seguro y el modo de autenticación (Bearer, cabecera, Basic o parámetro).
3. Un ejemplo real de respuesta (una página completa) para preparar el mapeo de campos.
4. Lista de sedes con el código de almacén de cada una y la moneda del catálogo.

En la consola de Beliberi, en Comercios › Conexión de datos, se elige "API REST genérica", se pegan la URL y el nombre del secreto, se mapea cada campo canónico a su ruta en el JSON, se indica la paginación y se pulsa "Probar conexión": Beliberi lee la primera página y muestra los productos tal como los entiende. Cada sede recibe su almacén en la pestaña "Por sede".

Checklist de aceptación

• La primera página responde en menos de 5 s con credencial válida y 401 sin ella.
• Todos los productos vendibles tienen SKU, nombre, precio y stock; ningún SKU se repite en la misma sede.
• El stock de una sede coincide con el del POS para 10 productos elegidos al azar.
• Un cambio de precio o de stock en el POS se ve en Beliberi en la siguiente sincronización (máximo 15 minutos).
• Un producto desactivado en el POS deja de venderse en Beliberi sin borrar su historial.
• Las fotos abren desde una red externa (no solo desde la red del comercio).
• La paginación recorre el catálogo completo: el total de productos leídos coincide con el del POS.
• Si se activa el envío de pedidos, un pedido de prueba llega al POS una sola vez aunque Beliberi lo reintente.

El historial de cada sincronización (productos leídos, creados, actualizados, errores) queda en Catálogo › Sincronizaciones de la consola, al alcance del comercio y de Beliberi.

10. Mapeo a Beliberi

Estos son los campos canónicos que el conector de Beliberi rellena a partir de la respuesta del POS. En la consola, cada uno recibe la ruta donde vive en el JSON del comercio; los nombres sugeridos en este documento son solo eso, una sugerencia.

El resto de campos sugeridos (activo, descripcion, unidad, peso_gramos, actualizado_en, precio_descuento, modificadores, sedes) no los lee todavía el conector genérico: quedan documentados para que el comercio los exponga desde el principio y no haya que cambiar su API cuando Beliberi los use. Mientras tanto, un producto desactivado se retira dejándolo con stock 0 o quitándolo de la lista.

Preguntas abiertas para cerrar con cada comercio

• Moneda del catálogo y si el precio incluye IVA.
• Si el precio o el stock varían por sede.
• Si la API admite actualizado_desde o solo lectura completa.
• Si quieren recibir los pedidos en el POS y quién factura.