Guía de la API

Esta sección contiene lo necesario para comenzar a integrar con la API de LIRA: conceptos clave, flujos de trabajo y buenas prácticas de uso.

---

Guía general de uso de la API de LIRA

La API de LIRA permite a tus sistemas integrar clientes de terceros, consultar información y ejecutar operaciones sobre la plataforma de forma segura y estandarizada.

Toda la referencia técnica (endpoints, parámetros y ejemplos) se encuentra documentada en esta sección, donde se explica cómo usarla de forma general y segura.

---

1. Conceptos básicos

• La API es REST sobre HTTP/HTTPS.

• Los recursos se organizan por módulos (por ejemplo: App, Loans, Users, etc.).

• Se intercambian datos en formato JSON (excepto cuando se indica multipart/form-data para carga de archivos).

• Cada endpoint define:

  • Método HTTP: GET, POST, PUT, DELETE, etc.

  • URL relativa: por ejemplo /api/app/ o /api/app/version.

  • Parámetros de query, path y body.

  • Permiso requerido (ej. application.list).

---

2. URL base por ambiente

Cada cliente tendrá su propio ambiente (sandbox, staging, producción, etc.).

En la especificación verás un servidor genérico:

servers:
  - url: http://{{base_url}}

Al momento de integrar, deberás sustituir {{base_url}} por la URL que LIRA te asigne, por ejemplo:

• https://api.sandbox.tucliente.lira.com.do

• https://api.prod.tucliente.lira.com.do

En tu herramienta de pruebas (Postman, Insomnia, etc.) es recomendable crear una variable de entorno llamada base_url y construir las peticiones así:

{{base_url}}/api/app/
{{base_url}}/api/app/version
{{base_url}}/api/app/{{id}}

---

3. Autenticación y seguridad

La API está protegida mediante OAuth2 con tokens de acceso.

En components.securitySchemes verás el esquema oauth2Auth:

components:
  securitySchemes:
    oauth2Auth:
      type: http
      scheme: oauth2
security:
  - oauth2Auth: []

3.1. Obtención del token

• Durante el proceso de onboarding, LIRA te entregará:

  • Credenciales (por ejemplo, client_id y client_secret) y

  • La URL del endpoint de autenticación para obtener el token.

• Con esas credenciales, tu sistema obtiene un token de acceso (access token) que deberás enviar en cada llamada a la API.

Esta guía asume que ya dispones del token. El detalle del flujo OAuth y el endpoint de autenticación se comparte de forma privada durante la integración.

3.2. Enviar el token en cada petición

En todas las llamadas deberás incluir el header:

Authorization: Bearer <ACCESS_TOKEN>

Además:

Content-Type: application/json
Accept: application/json

En Postman:

1. Ve a la pestaña Authorization.

2. Tipo: Bearer Token.

3. Pega el token en el campo Token.

---

4. Permisos y control de acceso

Cada endpoint indica el permiso mínimo requerido. Ejemplos:

• application.list

• application.retrieve

• application_version.create

Estos permisos se configuran en LIRA y se asocian a tu integración (cliente, rol o usuario de servicio). Si el token no tiene el permiso necesario:

• 401 Unauthorized → token inválido o ausente.

• 403 Forbidden → el token es válido pero no tiene el permiso requerido.

Si recibes errores de este tipo, valida con el equipo de LIRA que tu integración tenga los permisos correctos.

---

5. Estructura general de las respuestas

La mayoría de respuestas siguen esta estructura:

{
  "message": "Descripción de la operación",
  "data": {
    // contenido específico: objeto o listado paginado
  },
  "status": "success"
}

Para listados paginados, dentro de data verás algo como:

{
  "has_page": {
    "next": false,
    "previous": false
  },
  "total": 7,
  "num_pages": 1,
  "page": 1,
  "page_size": 10,
  "results": [
    { /* objeto 1 */ },
    { /* objeto 2 */ }
  ]
}

• page y page_size indican la página actual y el tamaño configurado.

• has_page.next y has_page.previous te dicen si hay páginas siguientes o anteriores.

• results contiene la lista de elementos (apps, versiones, etc.).

---

6. Paginación, filtros y búsquedas

Los endpoints de tipo “list” soportan parámetros de consulta (query parameters) para:

1. Paginar:

   • page: número de página.

   • page_size: elementos por página.

2. Filtrar por campos específicos.

   Ejemplo en el módulo App:

   • name

   • activated

   • url

   • only_with_versions

3. Filtrar por estado o propiedades booleanas:

   • activated=true o activated=false

   • only_with_versions=true

Ejemplo de URL:

GET {{base_url}}/api/app/?activated=true&only_with_versions=true&page=1&page_size=20

---

7. Tipos de parámetros

En la documentación OpenAPI verás 3 tipos de parámetros:

1. Path parameters ({id}):

   • Forman parte de la URL.

   • Ejemplo: /api/app/{id}

     → /api/app/fb599838-32af-4878-b76b-5db599a91605

2. Query parameters:

   • Van después del signo ? en la URL.

   • Ejemplo: /api/app/?page=1&page_size=10

3. Body parameters (payload):

   • Van en el cuerpo de la petición (POST / PUT).

   • Generalmente en multipart/form-data o application/json.

La tabla “Query Parameters / Body Parameters / Path Parameters” que ves en GitBook indica:

• Name

• Type (string, boolean, int, UUID, etc.)

• Description

• Required (Sí / No)

---

8. Ejemplo práctico con el módulo

App

El módulo App sirve de buen ejemplo para entender el patrón general de diseño de la API.

8.1. Listar aplicaciones

Objetivo: obtener una lista paginada de apps.

• Método: GET

• Endpoint: /api/app/

• Permiso requerido: application.list

Ejemplo en Postman:

1. Método: GET

2. URL: {{base_url}}/api/app/

3. Auth: Bearer Token (ver sección 3).

4. (Opcional) Query params:

   • activated = 1

   • only_with_versions = 1

Resultado (simplificado):

{
  "message": "",
  "data": {
    "page": 1,
    "page_size": 10,
    "results": [
      { "id": 6, "name": "portals", ... },
      { "id": 5, "name": "e-commerce", ... }
    ]
  },
  "status": "success"
}

---

8.2. Crear una aplicación

Objetivo: registrar una nueva app.

• Método: POST

• Endpoint: /api/app/

• Permiso requerido: application.create

• Body (multipart/form-data):

  • name (string, requerido)

  • url (string, requerido)

  • activated (boolean/integer, opcional)

En Postman:

1. Método: POST

2. URL: {{base_url}}/api/app/

3. Body → form-data:

Key	Value
name	Lira 1
url	https://admin.develop.lira.com.do
activated	1

Respuesta (simplificada):

{
  "message": "App created successfully",
  "data": {
    "id": 7,
    "name": "Lira 1",
    "created_at": "...",
    "updated_at": "..."
  },
  "status": "success"
}

---

8.3. Gestionar versiones de una app

Endpoints de App > Version siguen siempre el mismo patrón:

• Listar versiones

  GET /api/app/version

  Con filtros opcionales: app_id, activated, version_code, is_current, page, page_size.

• Crear versión

  POST /api/app/version

  Body form-data con:

  • app_id (UUID)

  • version_code (string único por app)

  • activated (boolean)

  • is_current (boolean)

• Obtener una versión específica

  GET /api/app/version/{id}

• Actualizar versión

  PUT /api/app/version/{id}

  Body parcial, puedes enviar solo los campos que quieras actualizar.

Este mismo patrón (listar, crear, obtener detalle, actualizar) se repite en el resto de módulos de la API.

---

9. Errores comunes y manejo de respuestas

Además de las respuestas 200 (OK), puedes encontrar:

• 400 Bad Request

  • Parámetros inválidos, tipos incorrectos, campos requeridos faltantes.

• 401 Unauthorized

  • Token ausente, expirado o inválido.

• 403 Forbidden

  • El token no tiene el permiso requerido.

• 404 Not Found

  • Recurso no encontrado (id inexistente).

• 409 Conflict

  • Inconsistencias de negocio (por ejemplo, version_code duplicado).

• 500/5xx

  • Error interno del servidor.

La respuesta de error, en general, incluirá un campo message con una descripción legible. Puedes usarlo para mostrar mensajes claros en tus sistemas.

---

10. Buenas prácticas de integración

1. Usar entornos separados

   • Comenzar siempre en sandbox / staging antes de pasar a producción.

2. Centralizar la configuración

   • Manejar base_url, client_id, client_secret y otros valores en variables de entorno o configuraciones seguras.

3. Respetar límites y paginación

   • No intentes traer todo en una sola llamada si el API ofrece paginación.

4. Logs y trazabilidad

   • Loguear:

     • URL llamada,

     • método,

     • código de respuesta,

     • request_id si LIRA lo incluye en headers,

     • payloads (sin datos sensibles).

5. Control de errores

   • Implementar manejo claro según código HTTP para evitar fallos silenciosos.

6. Seguridad

   • No exponer el access_token en aplicaciones públicas del lado del cliente.

   • Usar HTTPS siempre en producción.

---

11. Dónde encontrar la referencia completa

• Toda la lista de endpoints, parámetros y ejemplos de respuesta se encuentra en el portal de documentación OpenAPI (GitBook).

• Cada sección del menú corresponde a un módulo (por ejemplo: App, Loans, Users, Accounting, etc.).

• Dentro de cada módulo verás:

  • Descripción funcional.

  • Tabla de parámetros.

  • Ejemplo de petición (GET/POST/PUT/DELETE).

  • Ejemplo de respuesta.

Te recomendamos:

1. Revisar primero esta guía para entender el flujo general.

2. Navegar luego al módulo específico que necesites (por ejemplo, “Clientes”, “Préstamos”, “Transacciones”) en la referencia OpenAPI.

3. Probar las llamadas en Postman/Insomnia usando la variable {{base_url}} y tu token OAuth2.

Con esto deberías tener el marco general para integrar clientes terceros a la plataforma de LIRA utilizando nuestra API.