Orders API — Create and Manage Restaurant Orders

The Orders API is the core of Ordervista’s order lifecycle management. It exposes two distinct access paths: customers (role 3) can browse their own order history, view individual order details, and place new online orders (delivery or takeaway); administrators (role 1) and operators (role 2) access a separate /manage subtree to view all orders across the system, drill into any order’s full detail, update statuses, and register in-person orders at the counter. All routes require a valid JWT passed in the Authorization header.

GET /api/orders

Returns the complete order history for the authenticated customer. Results are scoped to the current user — customers cannot see other users’ orders. Auth required: Yes — role 3 (Customer)

Response

Array of order rows joined with address and item-count information.

[].id_pedido

integer

Unique order identifier.

[].id_tipo_pedido

integer

Order type: 1 = Delivery, 2 = Retiro, 3 = Consumo Local.

[].id_direccion

integer | null

Delivery address ID. null for takeaway and in-person orders.

[].id_estado

integer

Current status: 1 = Pendiente, 2 = En preparación, 3 = Listo, 4 = Entregado.

[].fecha_pedido

string

ISO 8601 datetime the order was placed.

[].total

number

Order total as a decimal value (e.g. 17000.00).

[].observacion

string | null

Optional customer note attached to the order.

[].direccion

string | null

Street address from the linked DIRECCIONES row. null when no delivery address is attached.

[].comuna

string | null

Municipality from the linked DIRECCIONES row. null when no delivery address is attached.

[].ciudad

string | null

City from the linked DIRECCIONES row. null when no delivery address is attached.

[].total_items

integer

Count of distinct line items in the order.

curl https://ordervista-backend.onrender.com/api/orders \
  -H "Authorization: Bearer <token>"

Error responses

Status	`mensaje`
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — insufficient role
`500`	`"Error al obtener el historial de pedidos"`

GET /api/orders/:id

Returns the full detail of a single order belonging to the authenticated customer, including every line item. Returns 404 if the order does not exist or belongs to a different user. Auth required: Yes — role 3 (Customer)

Path parameters

integer

required

The numeric ID of the order to retrieve.

Response

id_pedido

integer

Unique order identifier.

id_tipo_pedido

integer

Order type: 1 = Delivery, 2 = Retiro, 3 = Consumo Local.

id_direccion

integer | null

Delivery address ID, or null.

id_estado

integer

Current order status (1–4).

fecha_pedido

string

ISO 8601 datetime the order was placed.

total

number

Order total.

observacion

string | null

Optional note.

direccion

string | null

Street address from the linked delivery address row. null when no address is attached.

comuna

string | null

Municipality from the linked delivery address row. null when no address is attached.

ciudad

string | null

City from the linked delivery address row. null when no address is attached.

items

array

Line items for the order. Each element contains id_detalle, id_producto, nombre, descripcion, imagen, cantidad, precio_unitario, and subtotal.

curl https://ordervista-backend.onrender.com/api/orders/42 \
  -H "Authorization: Bearer <token>"

Error responses

Status	`mensaje`
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — insufficient role
`404`	`"Pedido no encontrado"`
`500`	`"Error al obtener el detalle del pedido"`

POST /api/orders

Creates a new online order (delivery or takeaway) for the authenticated customer. The server validates each product’s existence, availability, and stock, then calculates all prices from the database — client-supplied precio_unitario, subtotal, and total values are ignored and recalculated server-side. A row is inserted into PEDIDOS, one DETALLE_PEDIDO row is created per item, stock is decremented, and a COMANDAS record is generated automatically. Auth required: Yes — role 3 (Customer)

Request body

id_tipo_pedido

integer

required

Order type: 1 = Delivery, 2 = Retiro.

id_direccion

integer

ID of a saved delivery address from DIRECCIONES. Required when id_tipo_pedido is 1 (Delivery).

observacion

string

Optional free-text note for the kitchen or delivery driver (max 255 characters).

items

array

required

Array of one or more order line items. Each object must include:

id_producto (integer, required) — product ID from PRODUCTOS
cantidad (integer, required) — quantity ordered (must be greater than 0 and not exceed available stock)

Response

mensaje

string

"Pedido creado correctamente"

id_pedido

integer

The newly created order’s ID.

curl -X POST https://ordervista-backend.onrender.com/api/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_tipo_pedido": 1,
    "id_direccion": 7,
    "observacion": "Sin cebolla por favor",
    "items": [
      {
        "id_producto": 3,
        "cantidad": 2
      }
    ]
  }'

Error responses

Status	`mensaje`
`400`	`"El pedido no contiene productos."` — empty items array
`400`	`"Cantidad de producto inválida."` — zero or negative quantity
`400`	`"Uno de los productos del pedido no existe."` — unknown product ID
`400`	`"El producto \"…\" no está disponible."` — inactive product
`400`	`"El producto \"…\" no tiene stock disponible."` — zero stock
`400`	`"Stock insuficiente para \"…\"."` — requested quantity exceeds stock
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — insufficient role
`500`	`"Error al crear el pedido"`

GET /api/orders/manage

Returns all orders in the system regardless of which customer placed them. Used by the operator dashboard to monitor and act on incoming orders. Auth required: Yes — role 1 (Admin) or 2 (Operator)

Response

Array of PEDIDOS rows joined with customer, address, and summarised item information.

[].id_pedido

integer

Unique order identifier.

[].id_usuario

integer

ID of the customer who placed the order.

[].cliente_nombre

string

Full name of the customer from USUARIOS.nombre.

[].cliente_email

string

Email address of the customer from USUARIOS.email.

[].id_tipo_pedido

integer

Order type: 1 = Delivery, 2 = Retiro, 3 = Consumo Local.

[].id_direccion

integer | null

Delivery address ID, or null.

[].id_estado

integer

Current status code (1–4).

[].fecha_pedido

string

ISO 8601 datetime the order was placed.

[].total

number

Order total.

[].observacion

string | null

Optional note.

[].direccion

string | null

Street address from the linked delivery address row. null when no address is attached.

[].comuna

string | null

Municipality from the linked delivery address row. null when no address is attached.

[].ciudad

string | null

City from the linked delivery address row. null when no address is attached.

[].total_items

integer

Count of distinct line items in the order.

[].items_text

string | null

Pipe-separated summary of all line items (e.g. "2x Hamburguesa Clásica||1x Papas Fritas").

curl https://ordervista-backend.onrender.com/api/orders/manage \
  -H "Authorization: Bearer <token>"

Error responses

Status	`mensaje`
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — insufficient role
`500`	`"Error al obtener la gestión de pedidos"`

GET /api/orders/manage/:id

Returns the full detail of any single order by ID, including its line items. Available to admins and operators regardless of which customer owns the order. Auth required: Yes — role 1 (Admin) or 2 (Operator)

Path parameters

integer

required

The numeric ID of the order to retrieve.

Response

id_pedido

integer

Unique order identifier.

id_usuario

integer

Customer who placed the order.

cliente_nombre

string

Full name of the customer from USUARIOS.nombre.

cliente_email

string

Email address of the customer from USUARIOS.email.

id_tipo_pedido

integer

Order type (1–3).

id_direccion

integer | null

Delivery address ID, or null.

id_estado

integer

Current status code (1–4).

fecha_pedido

string

ISO 8601 order timestamp.

total

number

Order total.

observacion

string | null

Optional note.

direccion

string | null

Street address from the linked delivery address row. null when no address is attached.

comuna

string | null

Municipality from the linked delivery address row. null when no address is attached.

ciudad

string | null

City from the linked delivery address row. null when no address is attached.

items

array

Array of DETALLE_PEDIDO rows joined with product data: id_detalle, id_producto, nombre, descripcion, imagen, cantidad, precio_unitario, subtotal.

curl https://ordervista-backend.onrender.com/api/orders/manage/42 \
  -H "Authorization: Bearer <token>"

Error responses

Status	`mensaje`
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — insufficient role
`404`	`"Pedido no encontrado"`
`500`	`"Error al obtener el detalle del pedido"`

PATCH /api/orders/manage/:id/status

Updates the status of an existing order. The id_estado value must be one of the recognised status codes. Supplying an out-of-range or missing value returns a 400 immediately without touching the database. Auth required: Yes — role 1 (Admin) or 2 (Operator)

Path parameters

integer

required

The numeric ID of the order whose status should be updated.

Request body

id_estado

integer

required

New status code. Accepted values:

Value	Name
`1`	Pendiente
`2`	En preparación
`3`	Listo
`4`	Entregado

Response

mensaje

string

"Estado del pedido actualizado correctamente"

curl -X PATCH https://ordervista-backend.onrender.com/api/orders/manage/42/status \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"id_estado": 2}'

Error responses

Status	`mensaje`
`400`	`"Estado de pedido inválido"` — value absent or outside 1–5
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — insufficient role
`404`	`"Pedido no encontrado"`
`500`	`"Error al actualizar el estado del pedido"`

POST /api/orders/in-person

Creates a presencial (in-person / at-counter) order. The id_tipo_pedido is automatically fixed to 3 (Consumo Local) by the server — callers must not supply it. id_direccion is always null. If observacion is omitted the server defaults it to "Pedido presencial". The same stock validation and price recalculation logic used by POST /api/orders applies here. Auth required: Yes — role 1 (Admin) or 2 (Operator)

Request body

observacion

string

Optional kitchen note. Defaults to "Pedido presencial" if not supplied.

items

array

required

Array of line items, each containing:

id_producto (integer, required)
cantidad (integer, required)

Response

mensaje

string

"Pedido presencial creado correctamente"

id_pedido

integer

The newly created order’s ID.

curl -X POST https://ordervista-backend.onrender.com/api/orders/in-person \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "observacion": "Mesa 4",
    "items": [
      {
        "id_producto": 5,
        "cantidad": 1
      }
    ]
  }'

Error responses

Status	`mensaje`
`400`	`"El pedido no contiene productos."` — empty items array
`400`	`"Cantidad de producto inválida."` — zero or negative quantity
`400`	`"Uno de los productos del pedido no existe."` — unknown product ID
`400`	`"El producto \"…\" no está disponible."` — inactive product
`400`	`"El producto \"…\" no tiene stock disponible."` — zero stock
`400`	`"Stock insuficiente para \"…\"."` — requested quantity exceeds stock
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — insufficient role
`500`	`"Error al crear el pedido presencial"`

Overview

Endpoints

Orders API — Create and Manage Restaurant Orders

GET /api/orders

Response

Error responses

GET /api/orders/:id

Path parameters

Response

Error responses

POST /api/orders

Request body

Response

Error responses

GET /api/orders/manage

Response

Error responses

GET /api/orders/manage/:id

Path parameters

Response

Error responses

PATCH /api/orders/manage/:id/status

Path parameters

Request body

Response

Error responses

POST /api/orders/in-person

Request body

Response

Error responses

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/orders

​Response

​Error responses

​GET /api/orders/:id

​Path parameters

​Response

​Error responses

​POST /api/orders

​Request body

​Response

​Error responses

​GET /api/orders/manage

​Response

​Error responses

​GET /api/orders/manage/:id

​Path parameters

​Response

​Error responses

​PATCH /api/orders/manage/:id/status

​Path parameters

​Request body

​Response

​Error responses

​POST /api/orders/in-person

​Request body

​Response

​Error responses

Build docs developers (and LLMs) love

GET /api/orders

Response

Error responses

GET /api/orders/:id

Path parameters

Response

Error responses

POST /api/orders

Request body

Response

Error responses

GET /api/orders/manage

Response

Error responses

GET /api/orders/manage/:id

Path parameters

Response

Error responses

PATCH /api/orders/manage/:id/status

Path parameters

Request body

Response

Error responses

POST /api/orders/in-person

Request body

Response

Error responses