Orders API: Create, Track, and Cancel Restaurant Orders

The Orders API is the central nervous system of Tradiciones y Sabores. Every order placed — whether at a table, picked up at the counter, or sent out for delivery — flows through these five endpoints. Orders are created with full client information and line items, automatically generating an associated invoice with 16% IVA. All endpoints are available under both /api/ordenes and the /api/pedidos alias for backward compatibility.

GET /api/ordenes

Retrieves all orders in the system, sorted by ticket number descending (newest first). Pass estatus=activo to narrow results to only orders that are currently in-progress. Alias: GET /api/pedidos

Query Parameters

estatus

string

Filter orders by activity state. The only recognized value is activo, which returns only orders whose estado_orden is recibido or preparando. Omit this parameter to return all orders regardless of status.

Response

Returns an array of order objects. Each object contains:

id_pedido

integer

Ticket number, mirrored from num_ticket for compatibility with older clients.

num_ticket

integer

Primary identifier for the order. Used as the path parameter in all other endpoints.

hora_creacion

string

ISO 8601 timestamp of when the order was created (UTC), e.g. "2024-11-15T19:30:00".

cliente_nombre

string

Full name of the customer. Defaults to "Cliente General" if the client record is missing.

cliente_cedula

string

National ID (cédula) of the customer, e.g. "V-12345678".

cliente_telefono

string

Phone number on file for the customer.

tipo

string

Order type string. Same value as tipo_pedido, included for compatibility.

tipo_pedido

string

Order fulfillment type. One of mesa, pickup, or delivery.

mesa

integer | null

Table number assigned to the order. Same value as id_mesa.

id_mesa

integer | null

Foreign key referencing the mesa table. null for pickup and delivery orders.

direccion

string | null

Delivery address. Same value as direccion_envio. null for mesa and pickup orders.

direccion_envio

string | null

Full delivery address string. Only populated when tipo_pedido is delivery.

items

array

Line items attached to the order. Each element contains:

items[].id_producto

integer

Dish ID, mirrored from id_plato.

items[].id_plato

integer

Primary key of the plato record.

items[].nombre

string

Dish name resolved from the plato table. Falls back to "Plato #<id>" if the record is missing.

items[].cantidad

integer

Quantity ordered.

items[].precio_unitario

number

Unit price at the time of ordering, sourced from plato.precio.

items[].subtotal

number

Line total (precio_unitario × cantidad), rounded to two decimal places.

subtotal

number

Sum of all line item subtotals before tax.

iva

number

Value-added tax at 16% (subtotal × 0.16), rounded to two decimal places.

total

number

Final amount due (subtotal + iva), rounded to two decimal places.

Estatus_Orden

string

Capitalized status string for display purposes, e.g. "Recibido". Same state as estado_orden.

estado_orden

string

Lowercase status string. One of recibido, preparando, listo, or entregado.

# All orders
curl -X GET http://localhost:5000/api/ordenes \
  -H "Accept: application/json"

# Only active orders (recibido or preparando)
curl -X GET "http://localhost:5000/api/ordenes?estatus=activo" \
  -H "Accept: application/json"

GET /api/ordenes/

Retrieves a single order by its ticket number. Returns the identical object shape as the list endpoint. Alias: GET /api/pedidos/{num_ticket}

Path Parameters

num_ticket

integer

required

The ticket number of the order to retrieve. This is the num_ticket value returned when the order was created.

Response

Returns a single order object with all the fields described in GET /api/ordenes. Returns 404 with {"detail": "Orden / Pedido no encontrado"} if no order with that ticket number exists.

curl -X GET http://localhost:5000/api/ordenes/42 \
  -H "Accept: application/json"

POST /api/ordenes

Creates a new order. The server resolves or auto-creates the customer by cedula_cliente, assigns estado_orden = recibido, builds DetallePedido rows for every item, and generates an associated Factura with 16% IVA — all in a single atomic transaction. Alias: POST /api/pedidos Response status: 201 Created

Request Body

cedula_cliente

string

Customer national ID (cédula). Also accepted as cliente_cedula. Defaults to "V-00000000" if omitted. If a Cliente record with this cédula already exists, it is reused; otherwise a new one is created automatically.

cliente_nombre

string

Customer full name. Also accepted as nombre_cliente. Defaults to "Cliente Consumidor". Only used when creating a new client record.

cliente_telefono

string

Customer phone number. Also accepted as telefono. Defaults to "0000000000".

tipo_pedido

string

required

Fulfillment type. Also accepted as tipo. Must be one of mesa, pickup, or delivery. Unrecognized values silently fall back to mesa.

id_mesa

integer

Table number for dine-in orders. Also accepted as mesa. Pass null or omit for pickup and delivery.

direccion_envio

string

Full delivery address. Also accepted as direccion. Required when tipo_pedido is delivery; ignored for other types.

items

array

required

Line items for the order. Also accepted as detalles. Each element must contain:

items[].id_plato

integer

required

ID of the dish being ordered. Also accepted as id_producto.

items[].cantidad

integer

required

Quantity of this dish. Defaults to 1 if omitted.

items[].precio_unitario

number

Override unit price. If the id_plato resolves to a Plato record, plato.precio is used and this field is ignored. Only applied when the plato cannot be found.

Response

Returns the full order object (same shape as GET) with the newly assigned num_ticket and invoice totals pre-calculated.

The invoice (Factura) is created automatically with estado_pago = pendiente. There is no dedicated billing endpoint in the REST API — to update payment status (e.g. to pagado or anulado), update the factura.estado_pago field directly in the database.

# Mesa order
curl -X POST http://localhost:5000/api/ordenes \
  -H "Content-Type: application/json" \
  -d '{
    "cedula_cliente": "V-12345678",
    "cliente_nombre": "María González",
    "cliente_telefono": "0414-5551234",
    "tipo_pedido": "mesa",
    "id_mesa": 5,
    "items": [
      {"id_plato": 3, "cantidad": 2},
      {"id_plato": 7, "cantidad": 1}
    ]
  }'

# Delivery order
curl -X POST http://localhost:5000/api/ordenes \
  -H "Content-Type: application/json" \
  -d '{
    "cedula_cliente": "E-87654321",
    "cliente_nombre": "Carlos Romero",
    "cliente_telefono": "0212-5559876",
    "tipo_pedido": "delivery",
    "direccion_envio": "Av. Principal de Los Ruices, Torre Norte, Piso 4, Caracas",
    "items": [
      {"id_plato": 1, "cantidad": 1},
      {"id_plato": 9, "cantidad": 3}
    ]
  }'

PUT /api/ordenes/

Updates the estado_orden of an existing order. This is the primary endpoint used by kitchen and delivery staff to advance an order through its lifecycle. Alias: PUT /api/pedidos/{num_ticket}

Path Parameters

num_ticket

integer

required

The ticket number of the order to update.

Request Body

estado_orden

string

required

New order status. Also accepted as Estatus_Orden or estatus. Must be one of:

recibido — Order received, awaiting preparation
preparando — Kitchen is actively preparing the order
listo — Order is ready for pickup or delivery
entregado — Order has been delivered to the customer

Values are matched case-insensitively. Unrecognized values leave the status unchanged.

Response

status

string

Always "ok" on success.

num_ticket

integer

The ticket number of the updated order, echoed back for confirmation.

Returns 404 if the order does not exist.

curl -X PUT http://localhost:5000/api/ordenes/42 \
  -H "Content-Type: application/json" \
  -d '{"estado_orden": "preparando"}'

DELETE /api/ordenes/

Permanently removes an order and all of its associated records. The deletion is performed in relational order — Factura first, then DetallePedido rows, then the Pedido itself — to respect foreign key constraints. Alias: DELETE /api/pedidos/{num_ticket}

This operation is irreversible. The linked invoice and all line items are deleted along with the order. Consider updating estado_orden to entregado instead of deleting if you need an audit trail.

Path Parameters

num_ticket

integer

required

The ticket number of the order to delete.

Response

status

string

Always "deleted" on success.

num_ticket

integer

The ticket number of the deleted order, echoed back for confirmation.

Returns 404 with {"detail": "Orden / Pedido no encontrado"} if no order with that ticket number exists.

curl -X DELETE http://localhost:5000/api/ordenes/42 \
  -H "Accept: application/json"

API Overview

Endpoints

Orders API: Create, Track, and Cancel Restaurant Orders

GET /api/ordenes

Query Parameters

Response

GET /api/ordenes/

Path Parameters

Response

POST /api/ordenes

Request Body

Response

PUT /api/ordenes/

Path Parameters

Request Body

Response

DELETE /api/ordenes/

Path Parameters

Response

Build docs developers (and LLMs) love

API Overview

Endpoints

Documentation Index

​GET /api/ordenes

​Query Parameters

​Response

​GET /api/ordenes/

​Path Parameters

​Response

​POST /api/ordenes

​Request Body

​Response

​PUT /api/ordenes/

​Path Parameters

​Request Body

​Response

​DELETE /api/ordenes/

​Path Parameters

​Response

Build docs developers (and LLMs) love

GET /api/ordenes

Query Parameters

Response

GET /api/ordenes/

Path Parameters

Response

POST /api/ordenes

Request Body

Response

PUT /api/ordenes/

Path Parameters

Request Body

Response

DELETE /api/ordenes/

Path Parameters

Response