Especificación Técnica REST v1

Documentación de la API REST v1

Referencia completa de endpoints, métodos HTTP, cabeceras requeridas, catálogo de scopes y contratos de respuesta en formato JSON.

Autenticación y Cabeceras

Todas las peticiones a la API REST v1 deben incluir tu llave secreta en la cabecera HTTP X-Api-Key o mediante Authorization: Bearer <llave>. Las llaves se crean y administran en /sistema/api-integraciones.

Content-Type: application/json

X-Api-Key: tu_llave_secreta_aqui

Catálogo de Permisos y Scopes

Scope	Descripción	Tipo
inventory.products.view	Consultar catálogo de productos, precios y existencias.	Lectura
inventory.products.ia_editar	Crear, actualizar y archivar productos del inventario.	Escritura
sales.orders.view	Consultar cola de cocina (KDS) y órdenes pendientes.	Lectura
sales.orders.ia_cocina	Avanzar estados de preparación en KDS y cancelar órdenes.	Escritura
sales.customers.view	Consultar padrón de clientes, saldos y puntos de lealtad.	Lectura
invoicing.documents.view	Consultar facturas electrónicas timbradas y ventas facturables.	Lectura
pos.cotizador.access	Consultar cotizaciones vigentes y generar PDFs públicos.	Lectura

Endpoints REST v1

GET /api/v1/kitchen/queue Scope: sales.orders.view

Obtiene la cola de comandas y platillos en estado de preparación para pantallas KDS de cocina.

Ejemplo de Respuesta (200 OK):

{
  "orders": [
    {
      "id": "c7a840e6-857e-46e3-99b8-dfb9281a8c3d",
      "session": { "custom_code": "MESA-04", "type": "dine-in" },
      "total_amount": "280.00",
      "status": "processing",
      "items": [
        { "product_name": "Pizza Margarita", "quantity": 1, "notes": "Sin orégano" }
      ],
      "inserted_at": "2026-09-15T12:30:00Z"
    }
  ],
  "count": 1
}

POST /api/v1/kitchen/orders/:id/advance Scope: sales.orders.ia_cocina

Avanza la orden al estado siguiente (ready o delivered), notificando a meseros.

Cuerpo de la Petición (JSON):

{
  "action": "ready"
}

POST /api/v1/delivery/orders/webhook Scope: sales.orders.ia_cocina

Webhook receptor para inyectar pedidos de UberEats, DiDi Food o Rappi directo a la pantalla KDS.

Payload de Integración (JSON):

{
  "provider": "ubereats",
  "external_order_id": "UBER-98214",
  "customer_name": "Valeria M.",
  "items": [
    { "sku": "HAMB-01", "name": "Hamburguesa Clásica", "quantity": 2, "unit_price": "140.00" }
  ]
}

Códigos de Estado HTTP

200 OK: La petición se completó exitosamente.
201 Created: El recurso fue creado correctamente.
401 Unauthorized: Llave API ausente, malformada o inválida.
403 Forbidden: La llave no cuenta con el scope requerido para la acción.
404 Not Found: El recurso especificado por ID no existe o está archivado.
422 Unprocessable Entity: Parámetros de validación fallidos en el cuerpo JSON.
429 Too Many Requests: Límite de peticiones por minuto excedido (rate-limit).

Explora el resto del sistema

Continúa conociendo la arquitectura de integración y las herramientas de desarrollo.

Punto de Venta y Control de Stock

Facturación y Cobro Multidivisa

Servidor MCP & E-Commerce

Asistencia de Voz y Visual