Orders API: List and Update Order Status

The Orders API gives a restaurant owner three endpoints to manage the orders their establishment has received. All three require JWT authentication — the server filters every query by restaurante__propietario=request.user so owners only ever see their own orders. When an order’s status is updated, the server pushes a real-time notification over Django Channels WebSocket groups: the client is always notified, and when an order transitions to enviado an available delivery driver is also notified via their dedicated WebSocket channel.

All three endpoints require a valid JWT Bearer token. Session authentication is accepted but JWT is recommended for programmatic clients. An unauthenticated request returns 401 Unauthorized.

Order State Machine

Orders move through the following states. Cancellation is allowed at any point.

pendiente → aceptado → preparando → enviado → entregado
     └──────────────────────────────────────→ cancelado

Estado	Meaning
`pendiente`	Order placed, awaiting restaurant acknowledgement
`aceptado`	Restaurant accepted the order
`preparando`	Kitchen is actively preparing the order
`enviado`	Order dispatched; delivery driver notified
`entregado`	Order successfully delivered to the customer
`cancelado`	Order cancelled at any stage

List All Orders

Returns every order ever placed with the authenticated restaurant, sorted from newest to oldest. GET /api/pedidos/

Example Request

curl -s https://gastromovil.online/api/pedidos/ \
  -H "Authorization: Bearer <access_token>"

Response

200 OK — array of order objects.

integer

Unique database identifier of the order.

cliente_nombre

string

Full name of the customer, falling back to their username if no full name is set.

total

string

Order total as a decimal string (e.g. "45000.00").

estado

string

Current status code: pendiente, aceptado, preparando, enviado, entregado, or cancelado.

fecha

string

ISO-8601 date string of when the order was placed (e.g. "2025-06-15").

notas

string

Optional customer notes (e.g. allergy information or special instructions).

direccion

string

Human-readable delivery address string, or an empty string if none was provided.

productos

array

Show productos[]

nombre

string

Product name at the time the order was placed.

cantidad

integer

Number of units ordered.

precio

string

Unit price at the time of the order as a decimal string.

[
  {
    "id": 101,
    "cliente_nombre": "Ana García",
    "total": "45000.00",
    "estado": "preparando",
    "fecha": "2025-06-15",
    "notas": "Sin cebolla por favor",
    "direccion": "Calle 10 #5-20, apto 301",
    "productos": [
      { "nombre": "Burger Clásica", "cantidad": 2, "precio": "18500.00" },
      { "nombre": "Papas Fritas", "cantidad": 1, "precio": "8000.00" }
    ]
  }
]

List Active Orders

Returns only orders that are still in progress — those with status pendiente, aceptado, preparando, or enviado. Use this endpoint to power a live kitchen dashboard. GET /api/pedidos/activos/

Example Request

curl -s https://gastromovil.online/api/pedidos/activos/ \
  -H "Authorization: Bearer <access_token>"

Response

200 OK — array of active order objects, newest first.

integer

Unique database identifier of the order.

cliente_nombre

string

Full name or username of the customer.

total

string

Order total as a decimal string.

estado

string

One of pendiente, aceptado, preparando, or enviado.

detalles_count

integer

Number of distinct product lines in the order.

direccion_entrega

string

Delivery address string, or "Sin dirección" if none was recorded.

notas

string

Optional customer notes.

[
  {
    "id": 105,
    "cliente_nombre": "Carlos Pérez",
    "total": "32000.00",
    "estado": "aceptado",
    "detalles_count": 3,
    "direccion_entrega": "Carrera 80 #45-12",
    "notas": ""
  }
]

Update Order Status

Changes the status of a single order and triggers real-time WebSocket notifications to the affected parties. POST /api/pedidos/<pk>/estado/

Path Parameters

integer

required

Primary key of the order to update. Must belong to the authenticated user’s restaurant.

Request Body

estado

string

required

The new status code. Must be one of: pendiente, aceptado, preparando, enviado, entregado, cancelado.

Example Request

curl -s -X POST https://gastromovil.online/api/pedidos/105/estado/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"estado": "preparando"}'

WebSocket Notifications

Every status change dispatches a message to the customer’s WebSocket group cliente_<customer_id> with a human-readable status message:

Estado	Message sent to client
`aceptado`	`✅ ¡Tu pedido fue aceptado! El restaurante lo está preparando.`
`preparando`	`👨‍🍳 Tu pedido está siendo preparado.`
`enviado`	`🛵 ¡Tu pedido está en camino!`
`entregado`	`🎉 ¡Tu pedido fue entregado!`
`cancelado`	`❌ Tu pedido fue cancelado.`

When estado is set to "enviado", the server additionally looks up the first available delivery driver (estado='disponible', activo=True) and sends a pedido_disponible event to their WebSocket group repartidor_<driver_user_id> containing the order ID, restaurant name, and delivery address.

Responses

200 OK — status updated and notifications dispatched.

{
  "ok": true,
  "estado": "preparando"
}

400 Bad Request — the supplied status value is not in the valid list.

{
  "ok": false,
  "error": "Estado inválido"
}

404 Not Found — order not found or belongs to a different restaurant.

{
  "detail": "No Pedido matches the given query."
}

There is no server-side guard preventing state regressions (e.g. moving from entregado back to pendiente). Implement transition validation in your client application to enforce the intended state machine.

Authentication

Endpoints

Real-Time

Orders API: List and Update Order Status

Order State Machine

List All Orders

Example Request

Response

List Active Orders

Example Request

Response

Update Order Status

Path Parameters

Request Body

Example Request

WebSocket Notifications

Responses

Build docs developers (and LLMs) love

Authentication

Endpoints

Real-Time

Documentation Index

​Order State Machine

​List All Orders

​Example Request

​Response

​List Active Orders

​Example Request

​Response

​Update Order Status

​Path Parameters

​Request Body

​Example Request

​WebSocket Notifications

​Responses

Build docs developers (and LLMs) love

Order State Machine

List All Orders

Example Request

Response

List Active Orders

Example Request

Response

Update Order Status

Path Parameters

Request Body

Example Request

WebSocket Notifications

Responses