Orders API — REST Endpoints for Restaurant Equis

The Orders API is the core transaction layer of Restaurant Equis. Every order lifecycle — from the moment a customer places a request to the moment it is delivered — flows through these endpoints. Each order automatically creates an associated factura (invoice) with a 16% IVA tax computation. All endpoints are available under both /api/ordenes and /api/pedidos; the two prefixes are fully equivalent aliases registered in the FastAPI router.

All endpoints described below are mirrored verbatim at /api/pedidos/*. For example, POST /api/ordenes and POST /api/pedidos behave identically. Use whichever prefix fits your client naming conventions.

List All Orders

curl -X GET https://your-api.com/api/ordenes

Returns all orders sorted by num_ticket descending (most recent first). Pass ?estatus=activo to restrict results to orders in recibido or preparando states — useful for the kitchen dashboard view.

Query Parameters

estatus

string

When set to activo, filters results to orders whose estado_orden is either recibido or preparando. Any other value (or omitting the parameter) returns all orders regardless of status.

Response

Returns an array of order objects. Each object contains the following fields:

id_pedido

integer

Alias for num_ticket. Included for frontend compatibility.

num_ticket

integer

The auto-incremented primary key and unique identifier for this order.

hora_creacion

string (ISO 8601)

UTC timestamp of when the order was created, e.g. "2024-03-15T14:32:00".

cliente_nombre

string

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

cliente_cedula

string

National ID of the customer, e.g. "V-12345678".

cliente_telefono

string

Customer’s phone number.

tipo

string

Alias for tipo_pedido. One of mesa, pickup, or delivery.

tipo_pedido

string

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

mesa

integer | null

Alias for id_mesa. Table number for dine-in orders; null otherwise.

id_mesa

integer | null

Table number for mesa-type orders; null for pickup/delivery.

direccion

string | null

Alias for direccion_envio. Delivery address; null for non-delivery orders.

direccion_envio

string | null

Delivery address used when tipo_pedido is delivery; null otherwise.

items

array

Line items belonging to this order.

Show Item object fields

id_producto

integer

Alias for id_plato. Dish identifier.

id_plato

integer

Primary key of the plato (dish) record.

nombre

string

Dish name at time of order.

cantidad

integer

Number of units ordered.

precio_unitario

number

Unit price at time of order.

subtotal

number

precio_unitario × cantidad for this line item.

subtotal

number

Sum of all line-item subtotals before tax.

iva

number

Value-added tax computed as subtotal × 0.16 (16%), rounded to 2 decimal places.

total

number

Final amount due: subtotal + iva, rounded to 2 decimal places.

Estatus_Orden

string

Capitalized display label for the order status, e.g. "Recibido", "Preparando", "Listo", "Entregado".

estado_orden

string

Lowercase machine-readable status. One of recibido, preparando, listo, entregado.

Get Single Order

curl -X GET https://your-api.com/api/ordenes/42

Retrieves a single order by its ticket number. Returns the same object shape as the list endpoint. Raises 404 if no order with that num_ticket exists.

Path Parameters

num_ticket

integer

required

The unique ticket number of the order to retrieve.

Create Order

curl -X POST https://your-api.com/api/ordenes \
  -H "Content-Type: application/json" \
  -d '{
    "cedula_cliente": "V-12345678",
    "cliente_nombre": "María López",
    "cliente_telefono": "0414-1234567",
    "tipo_pedido": "delivery",
    "id_mesa": null,
    "direccion_envio": "Av. Principal, Edificio Sol, Piso 3",
    "items": [
      { "id_plato": 3, "cantidad": 2 },
      { "id_plato": 7, "cantidad": 1 }
    ]
  }'

Creates a new order, auto-registers the customer if their cedula_cliente is not yet in the database, creates the detalle_pedido (line items), and generates a linked factura with computed subtotal, impuesto (16% IVA), and total. Returns 201 Created with the full order response body.

Request Body

cedula_cliente

string

required

National ID of the customer, e.g. "V-12345678". If no customer record exists for this ID, one is created automatically using the cliente_nombre, cliente_telefono, and direccion_envio values supplied.

cliente_nombre

string

Full name of the customer. Used when auto-creating a new customer record. Alias: nombre_cliente.

cliente_telefono

string

Phone number of the customer. Used when auto-creating a new customer record. Alias: telefono.

tipo_pedido

string

required

Fulfillment type for the order. Accepted values: mesa, pickup, delivery. Defaults to mesa if an unrecognised value is supplied. Alias: tipo.

id_mesa

integer

Table number. Required when tipo_pedido is mesa; omit or set to null for pickup/delivery. Alias: mesa.

direccion_envio

string

Delivery address. Stored on the order only when tipo_pedido is delivery; otherwise ignored. Alias: direccion.

items

array

required

List of dishes to include in the order. Must contain at least one item. Alias: detalles.

Show Item object fields

id_plato

integer

required

Primary key of the dish to order. Alias: id_producto.

cantidad

integer

required

Number of units to order. Defaults to 1 if omitted.

Response

Returns 201 Created with the full order object (same shape as the list response), including computed subtotal, iva, total, and an initial estado_orden of recibido.

Update Order Status

curl -X PUT https://your-api.com/api/ordenes/42 \
  -H "Content-Type: application/json" \
  -d '{ "estado_orden": "preparando" }'

Transitions an existing order to a new status. The request body accepts any of the three field names: estado_orden, Estatus_Orden, or estatus — all are normalised to lowercase before matching. Returns a lightweight confirmation object.

Path Parameters

num_ticket

integer

required

The ticket number of the order to update.

Request Body

estado_orden

string

required

New status for the order. Accepted values: recibido, preparando, listo, entregado (case-insensitive). Aliases: Estatus_Orden, estatus.

Response

status

string

Always "ok" on success.

num_ticket

integer

The ticket number of the updated order, echoed back.

There is no enforced state machine — you can transition an order to any status from any other status. Implement ordering constraints in your client if you need a strict workflow (e.g. preventing entregado → recibido).

Cancel / Delete Order

curl -X DELETE https://your-api.com/api/ordenes/42

Permanently removes an order and all associated records. The deletion cascades in this relational order: factura → detalle_pedido → pedido. This operation is irreversible.

Path Parameters

num_ticket

integer

required

The ticket number of the order to cancel and delete.

Response

status

string

Always "deleted" on success.

num_ticket

integer

The ticket number of the deleted order, echoed back.

Deletion is permanent. The associated factura and all detalle_pedido line items are also removed. There is no soft-delete or archive mechanism.

Overview

Endpoints

Data Models

Orders API — REST Endpoints for Restaurant Equis

List All Orders

Query Parameters

Response

Get Single Order

Path Parameters

Create Order

Request Body

Response

Update Order Status

Path Parameters

Request Body

Response

Cancel / Delete Order

Path Parameters

Response

Build docs developers (and LLMs) love

Overview

Endpoints

Data Models

Documentation Index

​List All Orders

​Query Parameters

​Response

​Get Single Order

​Path Parameters

​Create Order

​Request Body

​Response

​Update Order Status

​Path Parameters

​Request Body

​Response

​Cancel / Delete Order

​Path Parameters

​Response

Build docs developers (and LLMs) love

List All Orders

Query Parameters

Response

Get Single Order

Path Parameters

Create Order

Request Body

Response

Update Order Status

Path Parameters

Request Body

Response

Cancel / Delete Order

Path Parameters

Response