Skip to main content
POST
/
api
/
v1
/
envios
/
retirar
Retrieve Package
curl --request POST \
  --url https://api.example.com/api/v1/envios/retirar \
  --header 'Content-Type: application/json' \
  --data '
{
  "codigoSeguimiento": "<string>",
  "contrasenaEntrega": "<string>",
  "fechaEntrega": "<string>"
}
'
{
  "mensaje": "<string>",
  "codigoSeguimiento": "<string>"
}

​
Endpoint

POST /api/v1/envios/retirar
Process the package pickup by the recipient. This endpoint validates the delivery password and marks the shipment as delivered.

​
Request Body

​
codigoSeguimiento
string
required
The tracking code of the shipment to retrieve
​
contrasenaEntrega
string
required
The delivery password provided when the shipment was created. This is used to verify the recipient’s identity.
​
fechaEntrega
string
Delivery date in ISO format (YYYY-MM-DD). If null or not provided, uses the current date.

​
Response

​
mensaje
string
Success message confirming the package was delivered
​
codigoSeguimiento
string
The tracking code of the delivered shipment

​
Example Request

curl -X POST http://localhost:8080/api/v1/envios/retirar \
  -H "Content-Type: application/json" \
  -d '{
    "codigoSeguimiento": "ENV-20260309-ABCD1234",
    "contrasenaEntrega": "SEGURA123",
    "fechaEntrega": "2026-03-12"
  }'

​
Example Response

{
  "mensaje": "Paquete entregado exitosamente",
  "codigoSeguimiento": "ENV-20260309-ABCD1234"
}

​
Error Responses

​
Shipment Not Found

{
  "error": "EnvioNotFoundException",
  "message": "Envío no encontrado con código: ENV-20260309-ABCD1234"
}

​
Invalid Password

{
  "error": "InvalidPasswordException",
  "message": "Contraseña de entrega incorrecta"
}

​
Shipment Not Available

{
  "error": "InvalidStateException",
  "message": "El envío debe estar en estado DISPONIBLE para ser retirado"
}
The delivery password must match exactly. This endpoint automatically updates the shipment status to ENTREGADO and sets the delivery timestamp.

​
Workflow

  1. Recipient arrives at the destination branch office
  2. Recipient provides the tracking code and delivery password
  3. Branch office staff calls this endpoint
  4. System validates the password
  5. System checks that the shipment is in DISPONIBLE status
  6. System marks the shipment as ENTREGADO
  7. System records the delivery date and time
Before calling this endpoint, ensure the shipment is in DISPONIBLE status. Use the PUT /api/v1/envios//disponible endpoint to mark a shipment as available for pickup.

​
Security Considerations

  • The delivery password should be communicated securely to the recipient
  • Only the person with the correct password can retrieve the package
  • The password is case-sensitive
  • Failed attempts should be logged for security monitoring

Build docs developers (and LLMs) love

Get started for freeTalk to us