API de consulta de datos 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 Ingrese a su cuenta de Airvi con un usuario con permisos administrativos. Diríjase a la sección Parametrización → Claves (API Pública) . hacer clic en  “Añadir clave” . Colocar un nombre a la clave Haga clic en “Guardar” . 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 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#/ En esta interfaz podrá visualizar los diferentes endpoints disponibles , sus parámetros , ejemplos de uso y respuestas esperadas . 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: Authorization: Bearer 1234abcd5678efgh 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): Parámetro Descripción Obligatorio Formato take Cantidad de registros a mostrar ✅ Sí Número entero skip Cantidad de registros a omitir antes de iniciar la búsqueda ❌ No Número entero date_from , date_to Rango de fechas según el endpoint ❌ No YYYY-MM-DD ⚠️ 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 Parámetro Tipo Obligatorio Descripción filters[status] string No Estado de la moneda. Ej: activo skip integer No Cantidad de registros a omitir. Ej: 0 take integer Sí Cantidad de registros a retornar. Ej: 10 Pasos para ejecutar la consulta Ingrese a: {BASE_URL}/api/public/v1/currencies Busque la sección currencies → Listado paginado de monedas . Si lo necesita, aplique filtros como status=activo . En el parámetro take , indique cuántos registros desea obtener. Pulse “Enviar petición” . Si la consulta es exitosa, recibirá un 200 OK con el listado de monedas. 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: Parámetro Descripción take Cantidad de registros a retornar (obligatorio). skip Cantidad de registros a omitir. birthday_from y birthday_to Rango de fechas de nacimiento (opcional). ids[] Lista de identificadores específicos (opcional). Pasos para ejecutar la consulta: Ingrese a {BASE_URL}/docs/api . Busque la sección Clientes → Obtiene un listado paginado de clientes con sus datos básicos En el campo take , escriba la cantidad de registros que desea obtener (por ejemplo, 10 ). Si desea filtrar, puede agregar birthday_from y birthday_to en formato YYYY-MM-DD . Pulse “Enviar petición” . 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: En el campo de la ruta, reemplace {id} por el número de identificación del cliente (por ejemplo, 2200 ). Agregue el parámetro take=1 . Envíe la petición. Si el cliente existe, recibirá un código 200 OK . Si el cliente no existe, obtendrá un 404 Not Found . Ejemplo de solicitud: GET /api/ public_api /clients/ 2200 ? take = 1 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: Sustituya {document} por el número del documento (por ejemplo, 103968949 ). Presione “Enviar petición” . Verifique el código de estado: 200 OK: el cliente fue encontrado. 404 Not Found: no existe ningún cliente con ese documento. 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: Parámetro Descripción assignment_date_from , assignment_date_to Fecha de asignación del viaje. trip_date_from , trip_date_to Fecha del viaje. skip , take Control de paginación. Pasos: Reemplace {id} por el ID del cliente. Escriba las fechas en formato YYYY-MM-DD . Envíe la petición. Verifique que el resultado sea 200 OK . 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: GET /api/ public_api /clients/ by_identification /2034/ reservations ? take = 5 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 Parámetro Tipo Obligatorio Descripción filters[city] string No Ciudad de la ubicación. Ej: San José filters[country] string No País de la ubicación. Ej: Costa Rica filters[status] string No Estado de la ubicación. Ej: activo skip integer No Registros a omitir. Ej: 0 take integer Sí Registros a retornar. Ej: 10 Pasos para ejecutar la consulta Ingrese a: {BASE_URL}/api/public/v1/locations Busque la sección locations → Listado de ubicaciones . Si desea filtrar, complete los campos: Ciudad País Estado skip take (obligatorio) Pulse “Enviar petición” . Si existen registros, recibirá un 200 OK con los datos de cada ubicación. 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 Parámetro Descripción take Cantidad de registros a retornar (obligatorio). skip Cantidad de registros a omitir. filters[payment_ids] IDs de pagos separados por comas (opcional). filters[reservation_id] ID de la reserva asociada (opcional). filters[date_from] Fecha inicial del rango de pago (Y-m-d) (opcional). filters[date_to] Fecha final del rango de pago (Y-m-d) (opcional). filters[currency_code] Código de moneda del pago, ej: USD (opcional). filters[method] Slug del método de pago, ej: efectivo (opcional). filters[payer_identification] Identificación del pagador (opcional). Pasos para ejecutar la consulta Ingrese a {BASE_URL}/api/public/v1/payments Busque la sección payments → Listado paginado de pagos . En el campo take , indique cuántos registros desea obtener (por ejemplo, 10). 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 . Pulse “Enviar petición” . 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 Parámetro Tipo Descripción id integer Identificador del pago que se desea consultar (obligatorio). Ejemplo: 87 Pasos para ejecutar la consulta Ingrese a {BASE_URL}/api/public/v1/payments Busque la sección payments  → Consultar información de un pago por ID . En el campo id , escriba el identificador del pago que desea consultar. Pulse “Enviar petición” . Si el registro existe, recibirá un código 200 OK con toda la información del pago. Si el pago no se encuentra, el sistema responderá con 404 NOT_FOUND . 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 Parámetro Tipo Obligatorio Descripción filters[status] string No Filtra por estado (activo/inactivo) skip integer No Registros a omitir take integer Sí Registros a retornar (máximo permitido) Pasos para ejecutar la consulta Ingrese a: {BASE_URL}/api/public/v1/paymentMethods Diríjase a la sección: paymentMethods → Obtener listado completo de métodos de pago Complete los parámetros según lo necesite: filters[status]: Filtrar por estado (opcional) skip: Registros a omitir (opcional) take: Registros a retornar (obligatorio) Pulse “Enviar petición” . Si todo está correcto, el sistema responderá con 200 SUCCESS y el listado solicitado. 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 Parámetro Tipo Obligatorio Descripción skip integer No Cantidad de registros a omitir. Ej: 0 take integer Sí Cantidad de registros a retornar. Ej: 10 Pasos para ejecutar la consulta Ingrese a: {BASE_URL}/api/public/v1/providersType Busque la sección: providersType → Obtener todos los tipos de proveedores Complete los parámetros: skip: cantidad de registros a omitir (opcional) take: cantidad de registros a retornar (obligatorio) Pulse “Enviar petición” . Si la consulta es exitosa, recibirá un 200 OK con el listado de tipos de proveedores. 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: 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 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: Ingrese a {BASE_URL}/docs/api . Busque la sección de   Reembolsos . Ingrese los parámetros solicitados ( take , skip , fechas, etc.). 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: GET {BASE_URL}/api/public_api/clients/{ id }/reservations Parámetros disponibles: Parámetro Descripción assignment_date_from , assignment_date_to Fecha de asignación del viaje. trip_date_from , trip_date_to Fecha del viaje. skip , take Control de paginación. Pasos: Reemplace {id} por el ID del cliente. Escriba las fechas en formato YYYY-MM-DD . Envíe la petición. Verifique que el resultado sea 200 OK . 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: GET { BASE_URL } /api/ public / reservations 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 Parámetro Tipo Obligatorio Descripción filters[status] string No Estado de la categoría. Ej: activo skip integer No Registros a omitir. Ej: 0 take integer Sí Registros a retornar. Ej: 10 Pasos para ejecutar la consulta Ingrese a: {BASE_URL}/api/public/v1/transactionCategory Busque la sección transactionCategory → Listado de categorías de transacciones . Si desea filtrar, seleccione o escriba: Estado (activo / inactivo) skip take (obligatorio) Pulse “Enviar petición” . Si la consulta es exitosa, recibirá un 200 OK con la lista de categorías. 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 Parámetro Tipo Obligatorio Descripción filters[document] string No Número de documento del proveedor filters[status] string No Estado del proveedor (activo / inactivo) filters[user_ids] string No IDs separados por comas skip integer No Cantidad de registros a omitir take integer Sí Cantidad de registros a retornar Pasos para ejecutar la consulta Ingrese a {BASE_URL}/api/public/v1/providers. Busque la sección Providers → Obtener listado paginado de proveedores . En el campo take , escriba cuántos registros desea obtener. Si desea aplicar filtros, agregue document, status o user_ids. Pulse “Enviar petición” . Si la consulta es exitosa, recibirá un 200 OK con los proveedores encontrados. 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 Parámetro Tipo Obligatorio Descripción filters[document] string No Número de documento del usuario filters[status] string No Estado del usuario (activo / inactivo) filters[user_ids] string No IDs separados por comas skip integer No Cantidad de registros a omitir take integer Sí Cantidad de registros a retornar Pasos para ejecutar la consulta Ingrese a {BASE_URL}/api/public/v1/users. Busque la sección Users → Obtener listado paginado de usuarios . En el campo take , escriba cuántos registros desea obtener. Si necesita filtrar, agregue document, status o user_ids. Pulse “Enviar petición” . Si la información existe, recibirá un 200 OK con los datos paginados. 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 Parámetro Tipo Obligatorio Descripción filters[plan_id] integer No ID del plan filters[plan_type] string No Tipo de plan (ej. alojamiento) search string No Término de búsqueda skip integer No Cantidad de registros a omitir take integer Sí Cantidad de registros a retornar Pasos para ejecutar la consulta Ingrese a {BASE_URL}/api/public/v1/plans . Busque la sección Plans → Obtener listado paginado de planes . En el campo take , escriba cuántos registros desea obtener. Si desea aplicar filtros, agregue plan_id , plan_type o search . Pulse “Enviar petición” . Si la consulta es exitosa, recibirá un 200 OK con los planes encontrados. 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 .