Orders API: Create, Track, and Deliver

The Orders API covers the full lifecycle of a dining order in La Comanda — from the moment a waiter submits items at the table through kitchen preparation, service delivery, and the final admin-level audit trail. Each endpoint enforces role-based access so that only the appropriate staff can perform each action.

All endpoints in this section require an active PHP session cookie (PHPSESSID). Missing or expired sessions receive an HTTP redirect to views/login.php instead of a JSON error response.

POST /public/api/guardarOrden.php

Creates a new order, resolves each product name against the catalog, splits items into kitchen and barista sub-orders, and persists everything to MySQL via OrdenesSync::guardarEnBase(). Method: POST Auth: rol_id IN (1 Admin, 2 Mesero) Content-Type: application/json

Request Body

Send the body as a JSON object.

mesa

string

required

The table number as a string (e.g. "3"). Must be castable to an integer greater than zero; "0" or non-numeric values return 400.

items

string

required

Newline-separated list of items, each in the format "Product Name x Quantity". Example:

Cappuccino x 2\nTarta de queso x 1

Each product name is looked up in the productos table. An unrecognized name returns 400.

notas

string

Free-text notes for the kitchen or barista. Optional; defaults to an empty string if omitted.

Response

status

string

"OK" on success.

numero

integer

The auto-assigned order number (numero_orden) for the new order. Use this value to reference the order in subsequent calls.

{ "status": "OK", "numero": 42 }

Error responses:

HTTP Status	Condition
`400 Bad Request`	Request body is not valid JSON
`400 Bad Request`	`mesa` is `0` or non-numeric
`400 Bad Request`	`items` is empty after normalization
`400 Bad Request`	A product name in `items` is not found in the catalog
`500 Internal Server Error`	Database exception during insert

Example

curl -X POST http://localhost:8080/public/api/guardarOrden.php \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=<your-session-id>" \
  -d '{
    "mesa": "3",
    "items": "Cappuccino x 2\nTarta de queso x 1",
    "notas": "Sin azúcar en los cafés"
  }'

Success:

{ "status": "OK", "numero": 42 }

Invalid table:

{ "status": "ERROR", "message": "Mesa inválida" }

Empty items:

{ "status": "ERROR", "message": "La orden no tiene productos" }

GET /public/api/obtenerOrdenes.php

Returns all active kitchen orders — items that belong to non-barista categories and have not yet reached estado_item = 'entregado'. This endpoint powers the live kitchen display. Method: GET Auth: rol_id IN (1 Admin, 3 Cocina)

Response

boolean

true on success.

ordenes

array

Array of order objects, each containing:

id_orden (integer) — internal database ID
numero (integer) — human-readable order number shown on kitchen tickets
mesa (string) — table number
items (array) — line items with product name, quantity, and estado_item
estado (string) — aggregate order status: pendiente, en_preparacion, or listo

{
  "ok": true,
  "ordenes": [
    {
      "id_orden": 5,
      "numero": 42,
      "mesa": "3",
      "items": [
        { "nombre": "Tarta de queso", "cantidad": 1, "estado_item": "pendiente" }
      ],
      "estado": "pendiente"
    }
  ]
}

Error response (500):

{ "ok": false, "message": "..." }

Example

curl http://localhost:8080/public/api/obtenerOrdenes.php \
  -H "Cookie: PHPSESSID=<your-session-id>"

POST /public/api/entregarOrden.php

Marks the active sub-order for a given table and preparation area as delivered. Used by waiters to confirm that food or drinks have reached the table, freeing the table for new orders when both areas are delivered. Method: POST Auth: rol_id IN (1 Admin, 2 Mesero) Content-Type: application/x-www-form-urlencoded

Request Parameters

mesa

integer

required

The table number. Must be greater than zero; missing or zero values return 400.

area

string

The preparation area for the sub-order: "cocina" or "barista". When omitted, the delivery applies to all areas for the table.

Response

status

string

"OK" on success.

message

string

Confirmation message: "Sub-orden entregada correctamente".

mesa

string

The table number echoed back as a string.

area

string

The area echoed back ("cocina", "barista", or empty string).

{
  "status": "OK",
  "message": "Sub-orden entregada correctamente",
  "mesa": "3",
  "area": "cocina"
}

Error responses:

HTTP Status	Condition
`400 Bad Request`	`mesa` is missing or zero
`400 Bad Request`	No active order found for the given table / area
`405 Method Not Allowed`	Request method is not `POST`

Example

curl -X POST http://localhost:8080/public/api/entregarOrden.php \
  -H "Cookie: PHPSESSID=<your-session-id>" \
  -d 'mesa=3&area=cocina'

POST /public/api/marcarEntrega.php

Marks an entire order as entregada and frees the associated table. Called from the kitchen view when the kitchen confirms that an order is fully complete. On success (and on most error conditions), the server issues an HTTP redirect to views/cocina.php. Method: POST Auth: rol_id IN (1 Admin, 3 Cocina) Content-Type: application/x-www-form-urlencoded

Request Parameters

numero

integer

required

The order number (numero_orden) to mark as delivered. Values ≤ 0 result in a redirect to views/cocina.php without processing.

Response

This endpoint does not return JSON. All outcomes redirect to views/cocina.php:

HTTP/1.1 302 Found
Location: {BASE_URL}views/cocina.php

Because the response is always an HTTP redirect, this endpoint is not suitable for AJAX/fetch() calls that expect a JSON body. Use adminCambiarEstadoOrden.php for programmatic state changes from JavaScript.

Example

curl -X POST http://localhost:8080/public/api/marcarEntrega.php \
  -H "Cookie: PHPSESSID=<your-session-id>" \
  -d 'numero=42' \
  -L

GET /public/api/ordenesAdminData.php

Returns the complete order history for the admin panel, with each order’s items, per-area sub-order statuses, computed aggregate status, and aggregated sales statistics. Method: GET Auth: rol_id = 1 (Admin only)

Response

boolean

true on success.

stats

object

Aggregated statistics across all returned orders:

total_ordenes (integer) — total number of orders
entregadas (integer) — orders with estado_normalizado = "entregada"
pendientes (integer) — orders still in pendiente state
en_proceso (integer) — orders in en_proceso or lista state
total_vendido (float) — sum of all order totals

ordenes

array

Array of order objects sorted by numero_orden descending, each containing:

id_mostrado (integer) — the numero_orden shown in the UI
mesa (string) — table number
usuario_nombre (string) — full name of the waiter who placed the order
total (float) — order total in local currency
fecha_formateada (string) — display date/time (DD/MM/YYYY hh:mm AM/PM), derived from fecha_entrega → fecha_lista → fecha_creacion
notas (string) — order notes, or "Sin notas" if empty
items_detalle (array) — each line item with nombre, cantidad, precio_unitario, subtotal, estado_item, area
estado_normalizado (string) — calculated from all item states: pendiente, en_proceso, lista, or entregada
estado_subordenes (object) — separate cocina and barista status strings using the same normalization logic

{
  "ok": true,
  "stats": {
    "total_ordenes": 18,
    "entregadas": 14,
    "pendientes": 2,
    "en_proceso": 2,
    "total_vendido": 342.50
  },
  "ordenes": [
    {
      "id_mostrado": 42,
      "mesa": "3",
      "usuario_nombre": "Ana García",
      "total": 21.50,
      "fecha_formateada": "25/06/2025 02:30 PM",
      "notas": "Sin azúcar",
      "items_detalle": [
        {
          "nombre": "Cappuccino",
          "cantidad": 2,
          "precio_unitario": 4.50,
          "subtotal": 9.00,
          "estado_item": "entregado",
          "area": "barista"
        }
      ],
      "estado_normalizado": "entregada",
      "estado_subordenes": {
        "cocina": "entregada",
        "barista": "entregada"
      }
    }
  ]
}

Status normalization logic:

Item states	`estado_normalizado`
All items `entregado`	`entregada`
All items `listo` or `entregado`	`lista`
At least one item `en_preparacion`	`en_proceso`
Everything else	`pendiente`

Example

curl http://localhost:8080/public/api/ordenesAdminData.php \
  -H "Cookie: PHPSESSID=<your-session-id>"

POST /public/api/adminCambiarEstadoOrden.php

Admin-only override that forces all items in a given preparation area of an order to a specific status. Useful for correcting stuck orders or testing the UI without waiting for kitchen actions. Method: POST Auth: rol_id = 1 (Admin only) Content-Type: application/x-www-form-urlencoded

Request Parameters

numero

integer

required

The order number (numero_orden) to update.

estado

string

required

The target order status. Must be one of the values in the first column of the mapping table below.

area

string

required

The preparation area whose items will be updated: "cocina" or "barista". Items in the other area are not affected.

Status mapping (request estado → detalle_orden.estado_item):

`estado` (request)	`estado_item` (stored)
`pendiente`	`pendiente`
`en_proceso`	`en_preparacion`
`lista`	`listo`
`entregada`	`entregado`

When estado is en_proceso, lista, or entregada, the endpoint also backfills the corresponding timestamp column (fecha_inicio_preparacion, fecha_lista, fecha_entrega) with COALESCE(current, NOW()) — so the first time a status is set, the timestamp is recorded; subsequent overrides to the same status do not overwrite it.

Response

status

string

"OK" when the update was committed successfully.

{ "status": "OK" }

Error responses:

HTTP Status	Condition
`400 Bad Request`	`numero`, `estado`, or `area` is missing
`400 Bad Request`	`estado` is not one of the four valid values
`400 Bad Request`	`area` is not `"cocina"` or `"barista"`
`405 Method Not Allowed`	Request method is not `POST`
`500 Internal Server Error`	Database error (transaction rolled back)

Example

curl -X POST http://localhost:8080/public/api/adminCambiarEstadoOrden.php \
  -H "Cookie: PHPSESSID=<your-session-id>" \
  -d 'numero=42&estado=en_proceso&area=cocina'

Success:

{ "status": "OK" }

Invalid estado:

{ "status": "ERROR", "message": "Estado no válido" }

Incomplete payload:

{ "status": "ERROR", "message": "Datos incompletos" }

Overview

Authentication

Orders

Products & Categories

Users & Sessions

Tables & Kitchen

Orders API: Create, Track, and Deliver

POST /public/api/guardarOrden.php

Request Body

Response

Example

GET /public/api/obtenerOrdenes.php

Response

Example

POST /public/api/entregarOrden.php

Request Parameters

Response

Example

POST /public/api/marcarEntrega.php

Request Parameters

Response

Example

GET /public/api/ordenesAdminData.php

Response

Example

POST /public/api/adminCambiarEstadoOrden.php

Request Parameters

Response

Example

Build docs developers (and LLMs) love

Overview

Authentication

Orders

Products & Categories

Users & Sessions

Tables & Kitchen

Documentation Index

​POST /public/api/guardarOrden.php

​Request Body

​Response

​Example

​GET /public/api/obtenerOrdenes.php

​Response

​Example

​POST /public/api/entregarOrden.php

​Request Parameters

​Response

​Example

​POST /public/api/marcarEntrega.php

​Request Parameters

​Response

​Example

​GET /public/api/ordenesAdminData.php

​Response

​Example

​POST /public/api/adminCambiarEstadoOrden.php

​Request Parameters

​Response

​Example

Build docs developers (and LLMs) love

POST /public/api/guardarOrden.php

Request Body

Response

Example

GET /public/api/obtenerOrdenes.php

Response

Example

POST /public/api/entregarOrden.php

Request Parameters

Response

Example

POST /public/api/marcarEntrega.php

Request Parameters

Response

Example

GET /public/api/ordenesAdminData.php

Response

Example

POST /public/api/adminCambiarEstadoOrden.php

Request Parameters

Response

Example