Skip to main content
The shipments service (ms-envios) manages the physical dispatch of orders. When a shipment is created, EnvioFactory selects the appropriate concrete creator based on tipoEnvio: TERRESTRE shipments receive an estimated delivery date of now + 5 days; EXPRESS shipments receive now + 1 day. A route description and guide number (guiaDespecho) are generated automatically. Shipments maintain their own status lifecycle, independent of the parent order. All endpoints require a valid JWT token in the Authorization header.

​
GET /api/envios

Return the complete list of all shipments.

​
Status codes

CodeMeaning
200Success. Returns an array of EnvioDTO objects.

​
Response fields

​
id
number
required
Auto-generated shipment identifier.
​
pedidoId
number
required
ID of the order this shipment fulfills.
​
status
string
required
Current shipment status. One of CREADO, ASIGNADO, EN_RUTA, or ENTREGADO.
​
tipoEnvio
string
required
Shipment type: TERRESTRE or EXPRESS.
​
transportista
string
Name of the carrier company handling this shipment.
​
guiaDespecho
string
Auto-generated tracking or dispatch guide number.
​
rutaDescripcion
string
Auto-generated route description based on tipoEnvio and destino.
​
destino
string
Destination city or address.
​
fechaEstimadaEntrega
string
ISO-8601 estimated delivery timestamp. now + 5 days for TERRESTRE; now + 1 day for EXPRESS.
​
creadoEn
string
required
ISO-8601 timestamp of when the shipment record was created.

​
Example

curl --request GET \
  --url http://localhost:8080/api/envios \
  --header 'Authorization: Bearer <token>'

​
POST /api/envios

Create a new shipment for a given order. EnvioFactory uses the tipoEnvio value to instantiate the correct fulfillment strategy. The service auto-generates rutaDescripcion, guiaDespecho, and fechaEstimadaEntrega. The initial status is always CREADO.

​
Request body

​
pedidoId
number
required
ID of the order to fulfil with this shipment.
​
tipoEnvio
string
required
Shipment type. Must be TERRESTRE or EXPRESS. Determines the carrier strategy and delivery date.
​
transportista
string
required
Name of the carrier company (e.g. "Servientrega", "DHL").
​
destino
string
required
Destination city or address for delivery.

​
Status codes

CodeMeaning
201Shipment created. Returns the new EnvioDTO.
400Validation failed or invalid tipoEnvio value.

​
Example

curl --request POST \
  --url http://localhost:8080/api/envios \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "pedidoId": 7,
    "tipoEnvio": "TERRESTRE",
    "transportista": "Servientrega",
    "destino": "Medellín"
  }'

​
GET /api/envios/

Retrieve a single shipment by its numeric ID.

​
Path parameters

​
id
number
required
The shipment’s auto-generated identifier.

​
Status codes

CodeMeaning
200Shipment found. Returns an EnvioDTO.
404No shipment with the given ID.

​
Example

curl --request GET \
  --url http://localhost:8080/api/envios/3 \
  --header 'Authorization: Bearer <token>'

​
PATCH /api/envios//status

Update the status of an existing shipment. Valid status transitions follow the lifecycle: CREADO → ASIGNADO → EN_RUTA → ENTREGADO. The service does not enforce transition order, so any of the four values can be set directly.
Setting a shipment to ENTREGADO does not automatically update the parent order status in ms-pedidos. Update the order separately via that service if needed.

​
Path parameters

​
id
number
required
The shipment’s auto-generated identifier.

​
Query parameters

​
status
string
required
New status value. Must be one of: CREADO, ASIGNADO, EN_RUTA, ENTREGADO.

​
Status codes

CodeMeaning
200Status updated. Returns the updated EnvioDTO.
400Invalid status value.
404No shipment with the given ID.

​
Example

curl --request PATCH \
  --url 'http://localhost:8080/api/envios/3/status?status=EN_RUTA' \
  --header 'Authorization: Bearer <token>'