Crear tu primer envío

Esta guía recorre, en orden, todas las peticiones necesarias para crear una orden de envío: desde obtener el token hasta consultar la guía y el seguimiento.

Una orden necesita tres IDs que se obtienen en pasos anteriores:

ID	Qué es	Paso
branchAddressId	La dirección de recolecta, desde donde se recoge el paquete.	3
branchsClientId	El cliente destinatario. La orden se entrega en la dirección registrada del cliente.	4
courierServiceId	La mensajería y el servicio elegidos al cotizar.	5

Los ejemplos usan https://api.volao.app y valores de prueba. Reemplaza <access_token> y los IDs por los tuyos.

Obtén un token

Login

curl -X POST https://api.volao.app/api/auth/client/login \
  -H "Content-Type: application/json" \
  -d '{ "client_id": "client_demo", "client_secret": "secret_demo" }'

Guarda token.access_token y envíalo en todas las peticiones siguientes, en el header Authorization: Bearer <access_token>. Dura 15 minutos; consulta Autenticación.

Busca el municipio de destino

Los catálogos de ubicación son públicos y no requieren token.

1. Lista los departamentos y toma el departmentId del que necesitas:

   Departamentos

   curl https://api.volao.app/api/open/departments

2. Consulta sus municipios:

   Municipios del departamento

   curl -X POST https://api.volao.app/api/open/municipality \
     -H "Content-Type: application/json" \
     -d '{ "departmentId": "0199a1b2-3333-7e5f-8a6b-1c2d3e4f0004" }'

   Respuesta

   {
     "response_code": 200,
     "response_status": "Success",
     "response_message": "Municipios procesados correctamente",
     "data": [
       { "municipalityId": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0005", "municipalityCode": "0101", "municipalityName": "AHUACHAPÁN" }
     ]
   }

:::info Dos formas de identificar un municipio Cada municipio tiene un municipalityId (UUID) y un municipalityCode (código de 4 dígitos). La dirección de recolecta usa el código; el cliente y la cotización usan el UUID. Cada paso indica cuál enviar. :::

Elige la dirección de recolecta

Lista las direcciones de recolecta de tu comercio (-1 devuelve todas):

Direcciones de recolecta

curl "https://api.volao.app/api/branchs/branchsAddresses?branchAddressId=-1" \
  -H "Authorization: Bearer <access_token>"

Toma el branchAddressId de la dirección que quieras usar. La que tiene "defaultAddress": 1 es la predeterminada.

Si todavía no tienes una, créala. El typeBranchAddressId sale de GET /api/open/typeBranchAddress (casa, tienda, bodega…) y municipalityCodigo es el código del municipio:

Crear dirección de recolecta

curl -X POST https://api.volao.app/api/branchs/branchsAddresses \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchAddressName": "Bodega Prueba",
    "collectionAddress": "Calle Ficticia #123, Colonia Prueba, San Salvador",
    "contactName": "Cliente Prueba",
    "phoneNumber": "70000000",
    "emailContact": "cliente.prueba@example.com",
    "latitude": "13.692940",
    "longitude": "-89.218191",
    "municipalityCodigo": "0102",
    "typeBranchAddressId": "0199a1b2-1111-7e5f-8a6b-1c2d3e4f0002"
  }'

La respuesta (201) incluye el branchAddressId nuevo. Si ya existe una dirección activa con el mismo nombre, la API responde 409.

Elige o registra al cliente

Busca al cliente por nombre, teléfono u otro dato:

Buscar cliente

curl "https://api.volao.app/api/branchs/branchsClient/search?search=Cliente%20Prueba&favorite=-1" \
  -H "Authorization: Bearer <access_token>"

De la respuesta guarda dos valores: el branchsClientId (para la orden) y el municipalityId (para cotizar).

Si es un cliente nuevo, regístralo con su dirección de entrega. Aquí municipalityCode es el UUID del municipio (municipalityId del paso 2):

Registrar cliente

curl -X POST https://api.volao.app/api/branchs/branchsClient \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientName": "Cliente Prueba",
    "recipientEmail": "cliente.prueba@example.com",
    "recipientPhone": "70000000",
    "recipientAddress": "Calle Ficticia #456, Colonia Prueba, San Salvador",
    "municipalityCode": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0005"
  }'

La respuesta (201) incluye el branchsClientId nuevo.

Cotiza el envío

1. Consulta las modalidades de servicio y toma el serviceModeCode (por ejemplo, NORMAL):

   Modalidades de servicio

   curl https://api.volao.app/api/courier/serviceMode \
     -H "Authorization: Bearer <access_token>"

2. Cotiza con la dirección de recolecta, el municipio del cliente (UUID), el peso y el monto a cobrar. Envía courierName vacío para ver todas las mensajerías:

   Cotizar

   curl -X POST https://api.volao.app/api/courier \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
       "branchAddressId": "0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b",
       "municipalityCode": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0005",
       "shippingAmount": 10,
       "weight": 4,
       "cantPackages": 1,
       "courierName": "",
       "typeService": "NORMAL"
     }'

La respuesta trae una opción por cada servicio disponible, con su costo (deliveryCost), comisión, fechas estimadas de recolección y entrega, y agencias. Elige una y guarda su courierServiceId.

:::warning El monto debe cubrir el envío Si cobras contra entrega, shippingAmount debe cubrir el costo del envío más las comisiones. Si no, al crear la orden la API responde 409 con el monto mínimo requerido. :::

Crea la orden

Con los tres IDs, crea la orden:

Crear orden

curl -X POST https://api.volao.app/api/orders \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchInfo": {
      "branchAddressId": "0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b",
      "branchsClientId": "0199a1b2-2222-7e5f-8a6b-1c2d3e4f0003"
    },
    "courier": {
      "courierServiceId": "019f88a7-40d5-75b5-add9-87e652d9ba69",
      "agencias": {}
    },
    "location": { "latitude": "13.692940", "longitude": "-89.218191" },
    "product": { "productDescription": "Ropa", "totalWeight": 4, "cantPackages": 1 },
    "order": { "shippingAmount": 10, "onDelivery": 1, "paymentOrderCollection": 0, "comments": "" }
  }'

• agencias es obligatorio, pero puede ir vacío ({}). Solo se llena si el servicio elegido trabaja con agencias (GET /api/courier/agencies).
• onDelivery: 1 indica que el monto se cobra contra entrega.

La respuesta (201) incluye el ID de la orden y la guía:

Respuesta

{
  "response_code": 201,
  "response_status": "Success",
  "response_message": "Orden creada correctamente",
  "data": {
    "ordersId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008",
    "comprobante": "29137811",
    "courierName": "Mensajería Ejemplo",
    "availableBalance": 42.22
  },
  "guide": { "URLguide": "https://..." }
}

Guarda data.ordersId: lo necesitas para consultar la guía, el seguimiento o cancelar la orden. El costo del envío se descuenta de tu saldo prepago (availableBalance es el saldo que queda).

Consulta la guía y el seguimiento

• Guía de envío (para imprimir):

  Guía de envío

  curl "https://api.volao.app/api/orders?OrderId=0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" \
    -H "Authorization: Bearer <access_token>"

• Seguimiento (estado actual y movimientos):

  Seguimiento

  curl "https://api.volao.app/api/orders/tracking?OrderId=0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" \
    -H "Authorization: Bearer <access_token>"

• Seguimiento público, sin token, para compartir con tu cliente: GET /api/open/trackingComp?OrderId=....

Para cancelar una o varias órdenes, usa PATCH /api/orders con la lista de IDs y el motivo.

Errores frecuentes

Respuesta	Causa	Qué hacer
401 Token inválido o expirado	Pasaron más de 15 minutos desde el login.	Repite el paso 1.
409 sobre el monto a cobrar	shippingAmount no cubre el envío más las comisiones.	Sube el monto al mínimo que indica response_message.
409 sobre la dirección	El branchAddressId no existe o no pertenece a tu comercio.	Vuelve a listar tus direcciones (paso 3).
409 sobre el saldo	Tu saldo prepago no alcanza para el costo del envío.	Recarga saldo antes de crear la orden.
400	Falta un campo obligatorio o tiene un formato inválido. La API informa el primer error.	Revisa el campo que indica response_message.

Consulta cada endpoint en la Referencia API para ver todos los campos y probarlo desde la documentación.