Skip to main content
Retrieve, update, and delete customer orders.

​
List All Orders

Retrieve all orders in the system.

​
Response

Returns an array of order objects. See Create Order for the full order object schema. 
curl https://api.example.com/pedido

[
  {
    "id": 1,
    "codigo": "PED-2024-001",
    "serie": "A001",
    "descripcion": "Customer bulk order",
    "estado": "PENDIENTE",
    "clienteId": 5,
    "fechaPedido": "2024-01-15T14:30:00",
    "fechaEntrega": "2024-01-22",
    "total": 3386.00,
    "detalle": [...]
  }
]

​
Get Order by ID

Retrieve a specific order by its ID.

​
Path Parameters

​
id
integer
required
The unique identifier of the order

​
Response

Returns a single order object or 404 if not found. 
curl https://api.example.com/pedido/1

{
  "id": 1,
  "codigo": "PED-2024-001",
  "serie": "A001",
  "descripcion": "Customer bulk order",
  "estado": "PENDIENTE",
  "clienteId": 5,
  "cliente": {
    "id": 5,
    "dni": "12345678",
    "nombre": "Juan",
    "apellido": "Perez"
  },
  "detalle": [
    {
      "id": 1,
      "productoId": 20,
      "cantidad": 100.0,
      "precio": 15.50
    }
  ],
  "fechaPedido": "2024-01-15T14:30:00",
  "fechaEntrega": "2024-01-22",
  "baseImponible": 2869.49,
  "igv": 516.51,
  "total": 3386.00
}

​
Update Order

Update an existing order, including its state and details.

​
Path Parameters

​
id
integer
required
The unique identifier of the order to update

​
Request Body

Provide the complete order object with updated fields. See Create Order for the full schema.
​
estado
string
Update the order state (e.g., “PROCESANDO”, “COMPLETADO”, “CANCELADO”)
​
fechaEntrega
string
Update the expected delivery date
​
detalle
array
Update order items (replaces all existing detail items)

​
Response

Returns the updated order object. 
curl -X PUT https://api.example.com/pedido/1 \
  -H "Content-Type: application/json" \
  -d '{
    "codigo": "PED-2024-001",
    "serie": "A001",
    "descripcion": "Customer bulk order",
    "estado": "PROCESANDO",
    "clienteId": 5,
    "formapagoId": 1,
    "fechaEntrega": "2024-01-20",
    "detalle": [
      {
        "productoId": 20,
        "cantidad": 120,
        "precio": 15.50
      }
    ],
    "baseImponible": 3442.37,
    "igv": 619.83,
    "total": 4062.20
  }'

{
  "id": 1,
  "codigo": "PED-2024-001",
  "serie": "A001",
  "descripcion": "Customer bulk order",
  "estado": "PROCESANDO",
  "clienteId": 5,
  "fechaPedido": "2024-01-15T14:30:00",
  "fechaEntrega": "2024-01-20",
  "total": 4062.20,
  "detalle": [...]
}

​
Delete Order

Delete an order and all associated detail items.

​
Path Parameters

​
id
integer
required
The unique identifier of the order to delete

​
Response

Returns 204 No Content on successful deletion. 
curl -X DELETE https://api.example.com/pedido/1

​
Order State Management

Orders follow a state-based workflow. Common state transitions include:

​
Common States

​
PENDIENTE
string
Initial state when order is created. Order is awaiting processing.
​
PROCESANDO
string
Order is being prepared or fulfilled.
​
COMPLETADO
string
Order has been completed and delivered.
​
CANCELADO
string
Order has been cancelled.

​
State Transition Example

​
Updating Order State

To change an order’s state, use the PUT endpoint with the new estado value: 
curl -X PUT https://api.example.com/pedido/1 \
  -H "Content-Type: application/json" \
  -d '{
    "codigo": "PED-2024-001",
    "serie": "A001",
    "estado": "COMPLETADO",
    "clienteId": 5,
    "formapagoId": 1,
    "detalle": [...],
    "baseImponible": 2869.49,
    "igv": 516.51,
    "total": 3386.00
  }'
When updating an order, you must provide the complete order object including all required fields and the full detalle array.

​
Best Practices

​
Managing Order Lifecycle

  1. Create: Orders are created with “PENDIENTE” state
  2. Process: Update to “PROCESANDO” when fulfillment begins
  3. Complete: Update to “COMPLETADO” when delivered
  4. Track: Use fechaEntrega to manage delivery expectations
  5. Modify: Update order details and quantities as needed before processing

​
Handling Cancellations

To cancel an order:
  1. Update the estado to “CANCELADO”
  2. Optionally add cancellation reason in descripcion
  3. Ensure inventory adjustments are handled separately

​
Delivery Date Management

  • Default delivery is 1 week after order date
  • Update fechaEntrega based on inventory availability
  • Consider estado when calculating realistic delivery dates

Build docs developers (and LLMs) love

Get started for freeTalk to us