API de Integración TPV Externo → Odoo

Introducción

Este documento describe la integración entre el TPV externo y el ERP Odoo 18 gestionado por AdemWeb. La integración es unidireccional: el TPV externo envía los datos de ventas a Odoo. Odoo no envía catálogo, precios ni empleados al TPV externo (al menos en esta primera versión).

Resumen de endpoints

Autenticación

Cada establecimiento tiene un PdV (pos.config) en Odoo con su propia API Key. El software del TPV debe incluirla en la cabecera X-API-Key de todas las peticiones.

Adicionalmente, Odoo usa autenticación de sesión estándar. El software del TPV externo debe autenticarse primero con las credenciales del usuario de servicio, obtener la cookie de sesión y usarla en las llamadas.

Paso 1 — Obtener cookie de sesión

POST https://odoo.ejemplo.com/web/session/authenticate
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "db": "nombre_base_datos",
    "login": "tpv_service_user",
    "password": "contraseña_usuario_servicio"
  }
}

La respuesta incluye una cookie session_id. Incluirla en todas las llamadas siguientes.

Paso 2 — Cabeceras de cada llamada

POST /pos/ext/orders HTTP/1.1
Host: odoo.ejemplo.com
Content-Type: application/json
Cookie: session_id=<cookie-de-sesion>
X-API-Key: <api-key-del-establecimiento>

Formato de las peticiones

• Todas las peticiones usan HTTP POST.
• El body siempre es JSON con Content-Type: application/json.
• Las respuestas son también JSON plano (no JSON-RPC).
• Las fechas usan formato ISO 8601: 2026-05-14T21:30:00.
• Los importes son números decimales en euros: 12.50.

Códigos de respuesta

Todos los errores incluyen un campo "error" en el body con la descripción: {"error": "Descripción del problema"}.

POST /pos/ext/sessions/open

Abre una sesión de caja en Odoo al inicio del turno. Si la sesión con ese ext_session_uid ya existe y está abierta, se devuelve la misma (idempotente).

{
  "config_code": "SALA_1",
  "ext_session_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "opening_cash": 150.00,
  "date_open": "2026-05-14T09:00:00"
}

{
  "session_id": 42,
  "name": "TPV Externo/E00001",
  "state": "opened"
}

POST /pos/ext/sessions/close

Cierra la sesión de caja al final del turno. Odoo genera el asiento de cierre de forma automática. Si la sesión ya estaba cerrada, devuelve "already_closed": true sin error (idempotente).

{
  "config_code": "SALA_1",
  "ext_session_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "closing_cash": 187.50,
  "date_close": "2026-05-14T23:30:00"
}

{
  "ok": true,
  "session_id": 42,
  "name": "TPV Externo/E00001"
}

{
  "ok": true,
  "session_id": 42,
  "name": "TPV Externo/E00001",
  "already_closed": true
}

POST /pos/ext/orders

Envía un pedido ya cobrado a Odoo. Se crea la venta con sus líneas y pagos y queda en estado paid (listo para contabilidad). Si el ext_order_uid ya existe, se devuelve el registro existente sin duplicar.

{
  "config_code": "SALA_1",
  "ext_order_uid": "f7e3a1b0-1234-5678-9abc-def012345678",
  "ext_session_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "date_order": "2026-05-14T21:32:00",
  "table_name": "Mesa 5",
  "waiter_name": "Ana García",
  "lines": [
    {
      "product_ref": "CARNE-001",
      "product_name": "Carne a la brasa",
      "qty": 2,
      "price_unit": 14.50,
      "discount_pct": 0
    },
    {
      "product_ref": "BEBIDA-COLA",
      "product_name": "Coca-Cola 33cl",
      "qty": 2,
      "price_unit": 2.50,
      "discount_pct": 0
    }
  ],
  "payments": [
    { "method_code": "CASH", "method_name": "Efectivo", "amount": 20.00 },
    { "method_code": "CARD", "method_name": "Tarjeta",  "amount": 14.00 }
  ]
}

{
  "order_id": 1523,
  "name": "POS/2026/05/0127",
  "state": "paid"
}

{
  "order_id": 1523,
  "name": "POS/2026/05/0127",
  "state": "paid",
  "already_existed": true
}

Matching de productos

Odoo busca el producto en este orden de prioridad:

1. product_ref → busca por default_code (código interno) en productos disponibles en POS. Método recomendado.
2. product_ref → busca por barcode.
3. product_name → busca por nombre (case-insensitive).
4. Auto-creación → si ningún criterio coincide, Odoo crea automáticamente un producto stub con el nombre y precio de la línea del TPV externo.

Matching de métodos de pago

Cada pago puede enviarse con method_code y/o method_name. Odoo aplica la siguiente prioridad:

Mesas

El campo table_name es opcional pero recomendado para restaurantes con distribución de sala. Odoo extrae los dígitos del nombre y busca la mesa con ese número en el suelo vinculado al PdV.

Ejemplos de valores aceptados: "Mesa 5", "T5", "5", "mesa5". Si la mesa no se encuentra, el pedido se crea igualmente sin asignación de mesa.

Flujo completo de un turno

1. [TPV externo] Inicio de turno
       POST /pos/ext/sessions/open  →  session_id: 42

2. [TPV externo] Pedidos durante el turno (uno a uno, en tiempo real o en batch)
       POST /pos/ext/orders  →  order_id: 1520  (pedido 1)
       POST /pos/ext/orders  →  order_id: 1521  (pedido 2)
       POST /pos/ext/orders  →  order_id: 1522  (pedido 3)
       ...

3. [TPV externo] Fin de turno
       POST /pos/ext/sessions/close  →  ok: true

4. [Odoo] Genera automáticamente:
       - Asientos contables de cada venta
       - Movimiento de cierre de caja
       - Informe de sesión (Z)

Idempotencia y reintentos

Todos los endpoints son idempotentes: enviar la misma petición varias veces produce el mismo resultado sin duplicar datos en Odoo.