Skip to main content
POST
/
api
/
v1
/
envios
Create Shipment
curl --request POST \
  --url https://api.example.com/api/v1/envios \
  --header 'Content-Type: application/json' \
  --data '
{
  "remitenteId": 123,
  "nombreDestinatario": "<string>",
  "dniDestinatario": "<string>",
  "sucursalOrigenId": 123,
  "sucursalDestinoId": 123,
  "precio": 123,
  "contrasenaEntrega": "<string>",
  "fechaEnvio": "<string>",
  "encomienda": {
    "encomienda.peso": 123,
    "encomienda.dimensiones": "<string>",
    "encomienda.descripcion": "<string>"
  }
}
'
{
  "id": 123,
  "codigoSeguimiento": "<string>",
  "estado": "<string>",
  "remitente": {
    "remitente.id": 123,
    "remitente.dni": "<string>",
    "remitente.nombreCompleto": "<string>",
    "remitente.correo": "<string>",
    "remitente.telefono": "<string>"
  },
  "encomienda": {},
  "nombreDestinatario": "<string>",
  "dniDestinatario": "<string>",
  "precio": 123,
  "fechaEnvio": "<string>",
  "sucursalOrigen": {},
  "sucursalDestino": {}
}

​
Endpoint

POST /api/v1/envios
Creates a new shipment with sender, recipient, package, and route information.

​
Request Body

​
remitenteId
number
required
ID of the sender client
​
nombreDestinatario
string
required
Full name of the recipient
​
dniDestinatario
string
required
DNI (national ID) of the recipient
​
sucursalOrigenId
number
required
ID of the origin branch office
​
sucursalDestinoId
number
required
ID of the destination branch office
​
precio
number
required
Shipment price
​
contrasenaEntrega
string
required
Delivery password for package pickup verification
​
fechaEnvio
string
Shipment date in ISO format (YYYY-MM-DD). If null, uses current date.
​
encomienda
object
required
Package information
​
encomienda.peso
number
required
Package weight in kilograms
​
encomienda.dimensiones
string
required
Package dimensions (e.g., “30x40x20 cm”)
​
encomienda.descripcion
string
required
Package description

​
Response

​
id
number
Unique shipment ID
​
codigoSeguimiento
string
Unique tracking code for the shipment
​
estado
string
Current shipment status (default: “PENDIENTE”)
​
remitente
object
Sender client information
​
remitente.id
number
Client ID
​
remitente.dni
string
Client DNI
​
remitente.nombreCompleto
string
Client full name
​
remitente.correo
string
Client email
​
remitente.telefono
string
Client phone
​
encomienda
object
Package details
​
nombreDestinatario
string
Recipient name
​
dniDestinatario
string
Recipient DNI
​
precio
number
Shipment price
​
fechaEnvio
string
Shipment creation date and time
​
sucursalOrigen
object
Origin branch office details
​
sucursalDestino
object
Destination branch office details

​
Example Request

curl -X POST http://localhost:8080/api/v1/envios \
  -H "Content-Type: application/json" \
  -d '{
    "remitenteId": 1,
    "nombreDestinatario": "Juan Pérez",
    "dniDestinatario": "87654321",
    "sucursalOrigenId": 1,
    "sucursalDestinoId": 2,
    "precio": 25.50,
    "contrasenaEntrega": "SEGURA123",
    "fechaEnvio": "2026-03-09",
    "encomienda": {
      "peso": 2.5,
      "dimensiones": "30x40x20 cm",
      "descripcion": "Documentos importantes"
    }
  }'

​
Example Response

{
  "id": 42,
  "codigoSeguimiento": "ENV-20260309-ABCD1234",
  "estado": "PENDIENTE",
  "remitente": {
    "id": 1,
    "dni": "12345678",
    "nombreCompleto": "María García",
    "correo": "[email protected]",
    "telefono": "987654321"
  },
  "encomienda": {
    "id": 42,
    "peso": 2.5,
    "dimensiones": "30x40x20 cm",
    "descripcion": "Documentos importantes"
  },
  "nombreDestinatario": "Juan Pérez",
  "dniDestinatario": "87654321",
  "precio": 25.50,
  "fechaEnvio": "2026-03-09T10:30:00",
  "fechaEntrega": null,
  "placa": null,
  "sucursalOrigen": {
    "id": 1,
    "codigoSucursal": "LIM-001",
    "nombreSucursal": "Lima Centro",
    "direccion": "Av. Abancay 123",
    "ciudad": "Lima"
  },
  "sucursalDestino": {
    "id": 2,
    "codigoSucursal": "CUS-001",
    "nombreSucursal": "Cusco Principal",
    "direccion": "Av. El Sol 456",
    "ciudad": "Cusco"
  },
  "contrasenaEntrega": "SEGURA123"
}
The tracking code (codigoSeguimiento) is automatically generated and should be provided to the client for tracking purposes.
Store the contrasenaEntrega securely. It will be required for package pickup at the destination.

Build docs developers (and LLMs) love

Get started for freeTalk to us