API de consulta de datos

• Descripción del módulo
• Módulo de Monedas
• Módulo de Clientes
• Módulo de Ubicaciones
• Módulo de pagos
• Módulo de Métodos de Pago (PaymentMethods)
• Módulo de Tipos de Proveedores (ProvidersType)
• Modulo de rembolsos
• Modulo de Reservas
• Módulo de Categorías de Transacciones (TransactionCategory)
• Módulo de Usuarios (Users & Providers)
• Módulo de Planes (Plans)

Descripción del módulo

La API Pública de Airvi permite consultar información registrada en el sistema (clientes, reservas, pagos y reembolsos) desde sistemas externos o integraciones de terceros.
Este módulo está diseñado para ofrecer acceso seguro, controlado y auditable a los datos del sistema sin necesidad de acceso directo a la base de datos.

Cada consulta genera un identificador único de rastreo (trace_id), útil para seguimiento de errores o solicitudes de soporte.
El acceso se gestiona mediante claves (tokens) que se generan desde el panel administrativo de Airvi.

Acceso al módulo

1. Ingrese a su cuenta de Airvi con un usuario con permisos administrativos.

2. Diríjase a la sección Parametrización → Claves (API Pública).

3. hacer clic en  “Añadir clave”.

4. Colocar un nombre a la clave

5. Haga clic en “Guardar”.

6. Copie el token generado. 

   

⚠️ Importante:
Guarde este token en un lugar seguro. Es necesario incluirlo en el encabezado de cada solicitud a la API. En caso de perdida o que ya no este funcionando, debes regenerar la clave API de nuevo.

Ejemplo de encabezado:

Authorization: Bearer {TOKEN}

Acceso a la documentación técnica

1. Abra el navegador e ingrese la siguiente dirección:

   {BASE_URL}/public/docs/ Siendo BASE_URL la URL de la plataforma
   

   Ejemplo: https://airvi-api.rpmarketing.com.co/public/docs#/

2. En esta interfaz podrá visualizar los diferentes endpoints disponibles, sus parámetros, ejemplos de uso y respuestas esperadas.

3. Puede ejecutar peticiones directamente desde el navegador, siempre que haya autenticado con su token.

📝 Nota:
La ruta incluye un guion medio entre “docs” y “api”. Es decir: docs-api, no “docsapi”.

Autenticación y seguridad

Todas las consultas se realizan mediante un token de autenticación generado desde Airvi. El token se envía en el encabezado HTTP de la petición.

Ejemplo de encabezado:

Estructura de las respuestas

Cada respuesta de la API tiene una estructura estándar:

• status: indica si la consulta fue exitosa (success) o falló (fail).

• errors: lista de errores o validaciones.

• data.items: contiene la información solicitada.

• trace_id: identificador único para auditoría y soporte técnico.

💡 Consejo:
Si una consulta falla o devuelve resultados vacíos, conserve el trace_id y compártalo con el área de soporte para una revisión más rápida.

---

Parámetros generales

La mayoría de endpoints utilizan los siguientes parámetros de consulta (query):

⚠️ Importante:
Incluso si realiza una consulta por un único registro, debe incluir el parámetro take.
Ejemplo: take=1

Módulo de Monedas

El módulo de Monedas (Currencies) permite acceder al listado de divisas configuradas dentro del sistema, junto con su información básica y su estado operativo.
Mantiene la misma estructura de autenticación, paginación y respuesta estándar que los demás módulos públicos de la API.

Obtener listado paginado de monedas

Función: Obtiene un listado paginado de monedas registradas en el sistema, permitiendo filtrarlas por estado (activo / inactivo).

Parámetros

Pasos para ejecutar la consulta

1. Ingrese a: {BASE_URL}/api/public/v1/currencies

2. Busque la sección currencies → Listado paginado de monedas.

3. Si lo necesita, aplique filtros como status=activo.

4. En el parámetro take, indique cuántos registros desea obtener.

5. Pulse “Enviar petición”.

6. Si la consulta es exitosa, recibirá un 200 OK con el listado de monedas.

7. Si ocurre un problema interno, la API responderá con 500 INTERNAL_ERROR.

Módulo de Clientes

El módulo de Clientes permite acceder a la información registrada de los clientes del sistema, ya sea de forma general (listado) o específica (por ID o por documento).

Consultar listado de clientes

Función: obtener una lista paginada de clientes con sus datos básicos.

Ruta: https://{Base_URL}/api/public/v1/clients

Parámetros disponibles:

Pasos para ejecutar la consulta:

1. Ingrese a {BASE_URL}/docs/api.

2. Busque la sección Clientes → Obtiene un listado paginado de clientes con sus datos básicos

3. En el campo take, escriba la cantidad de registros que desea obtener (por ejemplo, 10).

4. Si desea filtrar, puede agregar birthday_from y birthday_to en formato YYYY-MM-DD.

5. Pulse “Enviar petición”.

6. Verifique la respuesta.
   Si todo está correcto, obtendrá un código 200 OK con los datos solicitados.

Ejemplo de respuesta:

Consultar cliente por ID

Función: obtener los datos completos de un cliente específico usando su identificador.

Ruta: https://{Base_URL}/api/public/v1/clients/{id}

Pasos:

Ejemplo de solicitud:

Ejemplo de respuesta:

Consultar cliente por documento

Función: buscar un cliente utilizando su número de documento.

Ruta: GET {BASE_URL}/api/public_api/clients/by_identification/{document}

Pasos:

Módulo de Reservas

El módulo de Reservas devuelve las reservas asociadas a cada cliente, filtradas por su identificador o por su documento.

💡 Nota:
Actualmente, las consultas devuelven únicamente las reservas del cliente titular.
Si desea incluir pasajeros no titulares, consulte con el equipo técnico de Airvi si esta opción está habilitada en su instancia.

Consultar reservas por ID de cliente

Ruta: GET {BASE_URL}/api/public_api/clients/{id}/reservations

Parámetros disponibles:

Pasos:

1. Reemplace {id} por el ID del cliente.

2. Escriba las fechas en formato YYYY-MM-DD.

3. Envíe la petición.

4. Verifique que el resultado sea 200 OK.

5. Si no hay registros, el sistema devolverá un arreglo vacío en data.items 

Consultar reservas por número de documento del cliente.

Ruta: GET {BASE_URL}/api/public_api/clients/by_identification/{document}/reservations

Uso:
Permite consultar las reservas asociadas a un cliente a través de su número de documento.

Ejemplo:

Módulo de Ubicaciones

El módulo de Ubicaciones (Locations) permite acceder al listado de sedes o lugares registrados en el sistema. Este módulo también utiliza la misma estructura de autenticación, paginación y respuesta estándar de la API pública.

Consultar listado paginado de ubicaciones

Función: Obtiene un listado de ubicaciones con sus datos básicos, permitiendo aplicar filtros como ciudad, país o estado, además de paginar los resultados.

Parámetros

Pasos para ejecutar la consulta

1. Ingrese a: {BASE_URL}/api/public/v1/locations

2. Busque la sección locations → Listado de ubicaciones.

3. Si desea filtrar, complete los campos:

   • Ciudad

   • País

   • Estado

   • skip

   • take (obligatorio)

4. Pulse “Enviar petición”.

5. Si existen registros, recibirá un 200 OK con los datos de cada ubicación.

6. Si ocurre un error interno, la API responderá con 500 INTERNAL_ERROR.

Módulo de pagos

El módulos de Pagos (Payments)  permiten acceder a los movimientos financieros asociados a reservas. Comparten la misma estructura de autenticación y respuesta que los módulos anteriores.

Obtener listado paginado de pagos

Función: obtener una lista paginada de pagos, permitiendo filtrar por fechas, reserva, moneda, método de pago, pagador o IDs específicos.

---

Parámetros disponibles

---

Pasos para ejecutar la consulta

1. Ingrese a {BASE_URL}/api/public/v1/payments

2. Busque la sección payments→ Listado paginado de pagos.

3. En el campo take, indique cuántos registros desea obtener (por ejemplo, 10).

4. Si lo necesita, agregue filtros como:

   • date_from y date_to para un rango de fechas.

   • reservation_id si quiere pagos de una reserva específica.

   • currency_code, method o payer_identification.

5. Pulse “Enviar petición”.

6. Verifique la respuesta: si la solicitud es correcta, recibirá un código 200 OK con los datos paginados.

Consultar Información de un pago en especifico por ID

Función: obtener la información básica y detallada de un pago identificado por su {id}.

Parámetros disponibles

Ejemplo: 87

---

Pasos para ejecutar la consulta

1. Ingrese a {BASE_URL}/api/public/v1/payments

2. Busque la sección payments → Consultar información de un pago por ID.

3. En el campo id, escriba el identificador del pago que desea consultar.

4. Pulse “Enviar petición”.

5. Si el registro existe, recibirá un código 200 OK con toda la información del pago.

6. Si el pago no se encuentra, el sistema responderá con 404 NOT_FOUND.

7. Ante errores inesperados, retornará 500 INTERNAL_ERROR.

Módulo de Métodos de Pago (PaymentMethods)

El módulo de Métodos de Pago (PaymentMethods) permite consultar todos los medios de pago disponibles dentro del sistema. Mantiene la misma estructura de autenticación, paginación y formato de respuesta utilizada en los demás módulos públicos.

Obtener el listado completo de métodos de pago

Función: Retorna un listado paginado de los métodos de pago registrados en la plataforma

Parámetros

Pasos para ejecutar la consulta

1. Ingrese a: {BASE_URL}/api/public/v1/paymentMethods

2. Diríjase a la sección: paymentMethods → Obtener listado completo de métodos de pago

3. Complete los parámetros según lo necesite:

   • filters[status]: Filtrar por estado (opcional)

   • skip: Registros a omitir (opcional)

   • take: Registros a retornar (obligatorio)

4. Pulse “Enviar petición”.

5. Si todo está correcto, el sistema responderá con 200 SUCCESS y el listado solicitado.

6. Si ocurre un error inesperado, se mostrará un 500 INTERNAL_ERROR.

Módulo de Tipos de Proveedores (ProvidersType)

El módulo de Tipos de Proveedores (ProvidersType) permite acceder al listado completo de categorías de proveedores disponibles en el sistema.
Sigue la misma estructura estándar de autenticación y respuesta que el resto de los módulos públicos.

Obtener el listado completo de tipos de proveedores

Función: Retorna un conjunto paginado de tipos de proveedores registrados en la base de datos.

Parámetros

Pasos para ejecutar la consulta

1. Ingrese a: {BASE_URL}/api/public/v1/providersType

2. Busque la sección: providersType → Obtener todos los tipos de proveedores

3. Complete los parámetros:

   • skip: cantidad de registros a omitir (opcional)

   • take: cantidad de registros a retornar (obligatorio)

4. Pulse “Enviar petición”.

5. Si la consulta es exitosa, recibirá un 200 OK con el listado de tipos de proveedores.

6. Si ocurre un problema inesperado, el sistema responderá con 500 INTERNAL_ERROR.

Modulo de rembolsos

El módulo de reembolsos (Refunds) permiten acceder a los movimientos financieros asociados a reservas. Comparten la misma estructura de autenticación y respuesta que los módulos anteriores.

Obtener Listado paginado y filtrado de reembolsos

Función: Devuelve un listado de reembolsos aplicando filtros opcionales como fechas, moneda, método, identificación del receptor, IDs específicos, entre otros.

Este endpoint permite consultar un listado paginado de reembolsos registrados en el sistema.
La API permite aplicar filtros para refinar la búsqueda y obtener únicamente los reembolsos deseados.

Cada reembolso incluido en la respuesta contiene:

Los resultados pueden ser paginados usando los parámetros skip y take, y se ordenan por ID en orden descendente.

Consultar información de un reembolso por ID

Función: Obtiene los datos completos de un reembolso específico usando su identificador

Este endpoint permite consultar la información detallada de un reembolso registrado en el sistema.
Al enviar un id válido, la API retorna los datos principales del reembolso, incluyendo:

• ID del reembolso

• ID de la reserva asociada

• Valor y moneda

• Fecha del reembolso

• Concepto

• Método de reembolso

• Cuenta bancaria utilizada

• Datos del receptor (nombre completo, identificación, email)

• Fecha de creación del registro

Si el reembolso no existe, la API responde con un NOT_FOUND.
Si ocurre un error inesperado, retorna INTERNAL_ERROR.

Pasos generales:

1. Ingrese a {BASE_URL}/docs/api.

2. Busque la sección de  Reembolsos.

3. Ingrese los parámetros solicitados (take, skip, fechas, etc.).

4. Envíe la petición y verifique la respuesta 200 OK.

Modulo de Reservas

El módulo de Reservas devuelve las reservas asociadas a cada cliente, filtradas por su identificador o por estados de reservas y fechas 

💡 Nota:
Actualmente, las consultas devuelven únicamente las reservas del cliente titular.
Si desea incluir pasajeros no titulares, consulte con el equipo técnico de Airvi si esta opción está habilitada en su instancia.

Consultar reservas por ID 

Ruta:

Parámetros disponibles:

Pasos:

1. Reemplace {id} por el ID del cliente.

2. Escriba las fechas en formato YYYY-MM-DD.

3. Envíe la petición.

4. Verifique que el resultado sea 200 OK.

5. Si no hay registros, el sistema devolverá un arreglo vacío en data.items.

---

Consultar reservas

Función:
Devuelve un listado paginado de reservaciones que puede ser filtrado según diferentes criterios operativos.

Ruta:

Descripción general:
Esta función retorna una lista de reservaciones aplicando los siguientes filtros opcionales:

• Rango de fechas del viaje: trip_date_from, trip_date_to

• Rango de fechas de asignación: assignation_date_from, assignation_date_to

• Estado de la reserva: confirmado, borrador, cancelado

• Estado del pago: pagado, impagado, abonado

Datos incluidos por cada reserva:

• Identificadores de la reserva (ID y UUID)

• Moneda y valores financieros (total a pagar, monto pendiente, abonado)

• Fecha de asignación

• Información del viaje (nombre, fecha, estado)

• Estado actual de la reserva y del pago

Comportamiento de la respuesta:

• Los resultados se devuelven paginados mediante los parámetros skip y take.

• El listado se ordena automáticamente por la fecha del viaje en orden descendente.

• Si ocurre un error durante la consulta, la API retorna un mensaje con estado INTERNAL_ERROR e incluye el campo trace_id para seguimiento técnico.

Módulo de Categorías de Transacciones (TransactionCategory)

El módulo de Categorías de Transacciones (Transaction Categories) permite consultar y gestionar los tipos de categorías asociadas a movimientos financieros del sistema. Este módulo mantiene la misma estructura de autenticación, paginación y formato de respuesta estándar que el resto de la API pública.

Consultar listado paginado de categorías de transacciones

Función: Obtiene un listado paginado de categorías de transacciones con sus datos básicos, permitiendo filtrar por estado (activo o inactivo).

Parámetros

Pasos para ejecutar la consulta

1. Ingrese a: {BASE_URL}/api/public/v1/transactionCategory

2. Busque la sección transactionCategory → Listado de categorías de transacciones.

3. Si desea filtrar, seleccione o escriba:

   • Estado (activo / inactivo)

   • skip

   • take (obligatorio)

4. Pulse “Enviar petición”.

5. Si la consulta es exitosa, recibirá un 200 OK con la lista de categorías.

6. Si ocurre un problema inesperado, el sistema responderá con 500 INTERNAL_ERROR.

Módulo de Usuarios (Users & Providers)

Este módulo permite acceder a la información de usuarios registrados en el sistema, tanto proveedores como usuarios internos.
Los endpoints comparten la misma estructura de autenticación, paginación y formato de respuesta que los demás módulos públicos de la API.

Obtener listado paginado de proveedores

Función: Obtiene un listado paginado de proveedores, aplicando filtros opcionales por ID, documento y estado.

Parámetros

Pasos para ejecutar la consulta

1. Ingrese a {BASE_URL}/api/public/v1/providers.

2. Busque la sección Providers → Obtener listado paginado de proveedores.

3. En el campo take, escriba cuántos registros desea obtener.

4. Si desea aplicar filtros, agregue document, status o user_ids.

5. Pulse “Enviar petición”.

6. Si la consulta es exitosa, recibirá un 200 OK con los proveedores encontrados.

7. Si ocurre un problema durante la consulta, el endpoint retornará 500 INTERNAL_ERROR.

Consultar Listado paginado de usuarios

Función: Obtiene un listado paginado de usuarios cuyo rol corresponde a user, excluyendo los roles system y super_administrador, con filtros opcionales por documento, estado e IDs.

Parámetros

Pasos para ejecutar la consulta

1. Ingrese a {BASE_URL}/api/public/v1/users.

2. Busque la sección Users → Obtener listado paginado de usuarios.

3. En el campo take, escriba cuántos registros desea obtener.

4. Si necesita filtrar, agregue document, status o user_ids.

5. Pulse “Enviar petición”.

6. Si la información existe, recibirá un 200 OK con los datos paginados.

7. Si ocurre un error inesperado, la API responderá con 500 INTERNAL_ERROR.

Módulo de Planes (Plans)

Obtener listado paginado de planes

Este módulo permite consultar los planes disponibles en el sistema mediante un listado paginado. El endpoint admite filtros opcionales para facilitar la búsqueda por ID, tipo de plan o término de búsqueda. La estructura de autenticación, paginación y formato de respuesta es consistente con los demás módulos públicos de la API.

Función: Devuelve un listado paginado de planes que puede ser filtrado por ID, tipo de plan o término de búsqueda.

Parámetros

Pasos para ejecutar la consulta

1. Ingrese a {BASE_URL}/api/public/v1/plans.
2. Busque la sección Plans → Obtener listado paginado de planes.
3. En el campo take, escriba cuántos registros desea obtener.
4. Si desea aplicar filtros, agregue plan_id, plan_type o search.
5. Pulse “Enviar petición”.
6. Si la consulta es exitosa, recibirá un 200 OK con los planes encontrados.
7. Si ocurre un problema durante la consulta, el endpoint retornará 500 INTERNAL_ERROR.

Obtener listado de tipos de productos

Este módulo permite consultar los tipos de productos disponibles en el sistema. El endpoint devuelve una lista de tipos de planes que pueden ser utilizados para clasificar los productos y mantiene la misma estructura de autenticación y formato de respuesta de los demás módulos públicos de la API.

Función: Devuelve una lista de los tipos de productos disponibles.

Parámetros
Este endpoint no requiere parámetros para la consulta.

Pasos para ejecutar la consulta
Ingrese a {BASE_URL}/api/public/v1/plan_types.
Busque la sección Plan Types → Obtener listado de tipos de productos.
Pulse “Enviar petición”.
Si la consulta es exitosa, recibirá un 200 OK con los tipos de productos disponibles.
Si no se envía un token válido, el endpoint retornará 401 UNAUTHORIZED.
Si ocurre un problema durante la consulta, el endpoint retornará 500 INTERNAL_ERROR.