Track shipments and delivery

Create shipments for approved orders, choose between standard or express delivery, and advance each shipment through its tracking lifecycle.

Once an order is approved, you create a shipment to move it toward delivery. Shipments track the physical movement of goods from warehouse to destination, with a lifecycle that mirrors the handoff between your team and the carrier. The shipment type you choose determines the estimated delivery window, and the guide number (guiaDespecho) from the carrier gives you and your customers a reference for external tracking.

Shipment types

TERRESTRE

Standard ground delivery. Estimated delivery in 5 days. Suitable for domestic shipments where speed is not the primary concern.

EXPRESS

Priority delivery. Estimated delivery in 1 day. Use for time-sensitive orders or high-priority customers.

Shipment lifecycle

1. CREADO — Shipment created

   A new shipment record is created and linked to the order. The carrier and destination are recorded. The estimated delivery date is calculated from the shipment type.

2. ASIGNADO — Carrier assigned

   The shipment has been assigned to a specific driver or carrier route. The guiaDespecho (carrier guide number) is typically recorded at this stage.

   curl -X PATCH "http://localhost:8080/api/envios/1/status?status=ASIGNADO" \
     -H "Authorization: Bearer <your-token>"
   
3. EN_RUTA — In transit

   The shipment is on its way to the destination.

   curl -X PATCH "http://localhost:8080/api/envios/1/status?status=EN_RUTA" \
     -H "Authorization: Bearer <your-token>"
   
4. ENTREGADO — Delivered

   The shipment has been delivered to the destination. This is the terminal status.

   curl -X PATCH "http://localhost:8080/api/envios/1/status?status=ENTREGADO" \
     -H "Authorization: Bearer <your-token>"
   

Create a shipment

Send a POST request to /api/envios with the order ID, shipment type, carrier name, and destination. The shipment is linked to the order via pedidoId — this is a logical reference, not a database foreign key, since each service maintains its own data store.

curl -X POST http://localhost:8080/api/envios \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pedidoId": 42,
    "tipoEnvio": "TERRESTRE",
    "transportista": "TransChile Ltda.",
    "destino": "Valparaíso, Chile"
  }'

For an express shipment:

curl -X POST http://localhost:8080/api/envios \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pedidoId": 43,
    "tipoEnvio": "EXPRESS",
    "transportista": "RapidEx S.A.",
    "destino": "Santiago, Chile"
  }'

A 201 Created response returns the shipment object. The initial status is CREADO and fechaEstimadaEntrega is calculated automatically based on the tipoEnvio.

Required fields

Field	Type	Description
pedidoId	integer	ID of the approved order this shipment belongs to
tipoEnvio	string	TERRESTRE (5-day delivery) or EXPRESS (1-day delivery)
transportista	string	Name of the carrier company
destino	string	Delivery destination

Advance shipment status

Move a shipment to the next stage using PATCH /api/envios/{id}/status. Pass the target status as a query parameter.

curl -X PATCH "http://localhost:8080/api/envios/1/status?status=EN_RUTA" \
  -H "Authorization: Bearer <your-token>"

Status must be one of ASIGNADO, EN_RUTA, or ENTREGADO. Attempting to skip stages or set an invalid status returns a 400 Bad Request.

The guide number field

The guiaDespecho field stores the carrier’s tracking or guide number — the reference code issued by the carrier when the shipment is picked up. This value is auto-generated when the shipment is created. Include it when communicating with customers or when cross-referencing with the carrier’s own tracking system.

List all shipments

curl http://localhost:8080/api/envios \
  -H "Authorization: Bearer <your-token>"

Each shipment in the response includes its pedidoId, status, tipoEnvio, transportista, guiaDespecho, destino, and fechaEstimadaEntrega.

Endpoint reference

Method	Path	Description
POST	/api/envios	Create a new shipment
GET	/api/envios	List all shipments
GET	/api/envios/{id}	Get a shipment by ID
PATCH	/api/envios/{id}/status?status=	Advance shipment status