Version: 1.0.0

• Especificación OpenAPI

API de Volao

La API REST de Volao conecta tu tienda o sistema con la plataforma de envíos de Volao. Con ella puedes cotizar envíos entre varias mensajerías, crear y cancelar órdenes, obtener la guía de cada envío y seguir su recorrido, además de administrar las direcciones de recolecta y los clientes de tu comercio.

Qué puedes hacer

Área	Para qué sirve
Autenticación	Obtener el token de acceso con tus credenciales.
Órdenes	Crear órdenes de envío, cancelarlas, obtener la guía, consultar el seguimiento y sus incidencias.
Mensajerías	Cotizar un envío, y consultar las mensajerías disponibles, sus modalidades de servicio, promesas de entrega, cobertura, agencias y tarifas.
Sucursales	Administrar las direcciones de recolecta y los clientes (destinatarios) de tu comercio.
Historial	Consultar el historial de órdenes, de transacciones y movimientos de saldo, de liquidaciones y de beneficios del comercio.
Operaciones masivas	Crear órdenes y generar guías por lote a partir de un archivo Excel.
Catálogos y datos públicos	Departamentos, municipios, tipos de dirección, bancos, tipos de documento, motivos de movimiento y seguimiento público de órdenes.

URL base

Todas las rutas empiezan con /api y se concatenan a la URL del servidor. Por ejemplo: {servidor}/api/orders. En el panel Petición de cada endpoint puedes ver y elegir el servidor.

Autenticación

1. Solicita tus credenciales (client_id y client_secret) al equipo de Volao.
2. Obtén un token con POST /api/auth/client/login.
3. Envía el token en el header de cada petición: Authorization: Bearer <access_token>.

El token dura 15 minutos y no se puede renovar: cuando vence, repite el login. Los endpoints bajo /api/open/ son públicos y no requieren token.

Formato de las peticiones

• Los parámetros de los endpoints GET se envían en la URL (query string).
• El cuerpo de las peticiones POST, PUT, PATCH y DELETE se envía en JSON, con el header Content-Type: application/json.
• La excepción es la carga masiva de órdenes, que recibe el archivo Excel como multipart/form-data.

Formato de las respuestas

Todas las respuestas comparten la misma estructura:

{
  "response_code": 200,
  "response_status": "Success",
  "response_message": "Operación exitosa",
  "data": {}
}

response_code repite el código HTTP y data contiene el resultado. response_status puede llegar como Success/Error o success/error, así que compáralo sin distinguir mayúsculas o usa response_code.

Códigos de estado

Código	Significado
200	La operación se realizó correctamente.
201	El recurso se creó correctamente (por ejemplo, una orden, una dirección o un cliente).
400	La petición tiene datos inválidos o le faltan parámetros.
401	Las credenciales son inválidas, o el token falta, venció o no es válido.
403	El cliente API está desactivado.
404	El recurso solicitado no existe.
409	La operación no se puede realizar por una regla de negocio (por ejemplo, saldo insuficiente o un nombre repetido). El motivo viene en response_message.
500	Error interno del servidor.

Flujo para crear un envío

1. Autentícate con POST /api/auth/client/login.
2. Consulta los catálogos de departamentos y municipios (/api/open/...) para obtener los códigos de ubicación.
3. Elige o registra la dirección de recolecta en /api/branchs/branchsAddresses.
4. Elige o registra al cliente (destinatario) en /api/branchs/branchsClient.
5. Cotiza el envío con POST /api/courier para ver las mensajerías disponibles y su precio.
6. Crea la orden con POST /api/orders.
7. Obtén la guía con GET /api/orders y sigue el envío con GET /api/orders/tracking.

Probar desde esta documentación

Cada endpoint incluye un panel para enviar peticiones reales:

1. Abre Login de cliente API, escribe tus credenciales y presiona Enviar petición.
2. Copia el access_token de la respuesta.
3. En cualquier otro endpoint, pégalo en el campo Autenticación del panel. Se mantiene mientras no cierres la pestaña.

Más información

• Primeros pasos: credenciales y primera petición.
• Autenticación: vigencia del token y errores.
• Formato de respuesta: estructura común de las respuestas.

Esquema de seguridad

HTTP: Bearer Auth

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer
Bearer format:	JWT

Contacto

Equipo Volao:

URL: https://volao.app