API Reference de Akua

Te damos la bienvenida a la referencia de las APIs de Akua, tu guía completa para integrarte con nuestra plataforma. Ya sea que estés desarrollando una integración personalizada o que formes parte de una empresa que busca aprovechar las capacidades de Akua, esta documentación proporciona toda la información necesaria para interactuar sin problemas con nuestras APIs.

Las APIs de Akua están diseñadas para:

• Simplificar la integración: endpoints intuitivos y documentación completa para una configuración rápida.
• Mejorar la flexibilidad: soporte para múltiples métodos de pago, incluyendo pagos con tarjeta, transferencias bancarias y reembolsos.
• Garantizar la fiabilidad: manejo robusto de errores y herramientas de monitoreo para asegurar un funcionamiento fluido.
• Habilitar la escalabilidad: diseño modular para adaptarse al crecimiento de tu negocio.

Servicios de Akua

---

Guía para comenzar a usar las APIs de Akua

• Obtén las credenciales de la API: inicia sesión en el dashboard de Akua y genera tus claves de API.
• Revisa la autenticación: Akua utiliza claves de API para una comunicación segura. Consulta la sección de Autenticación para más detalles.
• Prueba en el entorno de pruebas (Sandbox): utiliza nuestro entorno Sandbox para validar tu integración antes de llevarla a producción.

---

Comienza a explorar las APIs de Akua y transforma tus flujos de trabajo de pagos. Si tienes alguna pregunta, nuestro equipo de soporte está aquí para ayudarte.

Conectando con la API de Akua

La API de Akua es un servicio basado en principios REST sobre HTTP y está alojada en infraestructura en la nube. Para garantizar una integración estable y sin interrupciones, los clientes deben seguir ciertas recomendaciones de conectividad, seguridad y manejo de respuestas.

---

Conectividad

Optimización global con Cloudflare

Los endpoints públicos de la API de Akua están protegidos y optimizados a través de Cloudflare, lo que proporciona una red de distribución global con baja latencia y alta disponibilidad. Gracias a esto, los clientes pueden acceder a la API con tiempos de respuesta óptimos desde cualquier ubicación geográfica.

Sistema de Nombres de Dominio (DNS)

Dado que nuestros servidores están en la nube y pueden cambiar de dirección IP, Akua no garantiza direcciones IP estáticas. Para evitar problemas de conectividad, recomendamos:

✅ Utilizar siempre el dominio DNS para resolver la dirección IP del servidor de la API.
❌ No utilizar direcciones IP fijas en la configuración de la integración.
🔄 Respetar el tiempo de vida (TTL) de los registros DNS para evitar problemas de caché.

---

Seguridad y certificados

La API de Akua establece conexiones seguras mediante TLS (Transport Layer Security). Para garantizar la integridad y seguridad de la comunicación, los clientes deben:

• Validar los certificados SSL asegurándose de que la cadena de certificación sea válida.
• Verificar que el certificado sea emitido por una Autoridad Certificadora (CA) confiable.
• Soportar los siguientes protocolos y cifrados recomendados:

TLS 1.3 (recomendado)

• TLS_AES_128_GCM_SHA256
• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256

TLS 1.2 (mínimo requerido)

• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

🔹 No se admite el pinning de certificados, ya que estos pueden rotar en cualquier momento.

⚠️ Las versiones anteriores de TLS (1.0 y 1.1) no son soportadas por razones de seguridad.

⚠️ HTTP (sin cifrado) no es soportado; todas las conexiones deben realizarse mediante HTTPS.

Para más información sobre nuestras prácticas de seguridad y cumplimiento, visita: https://trust.akua.la/

---

Control de tasa (Rate Limiting)

Para garantizar la estabilidad y disponibilidad del servicio para todos los clientes, la API de Akua implementa límites de tasa:

• Límite estándar: 1000 solicitudes cada 10 segundos por cliente.
• En caso de exceder este límite, la API responderá con un código HTTP 429 (Too Many Requests).
• El encabezado de respuesta Retry-After indicará el tiempo en segundos que se debe esperar antes de realizar nuevas solicitudes.

Recomendaciones para manejar el rate limiting:

• Implementar lógica de reintentos con retroceso exponencial.
• Distribuir las solicitudes a lo largo del tiempo cuando sea posible.
• Monitorear el uso de la API para evitar alcanzar los límites.

---

Protocolo y estándares HTTP

Para garantizar la compatibilidad y estabilidad, la API de Akua sigue los estándares de HTTP. Los clientes deben asegurarse de:

✅ Usar correctamente los métodos HTTP, como GET, POST, PUT, PATCH y DELETE.
✅ Manejar adecuadamente los códigos de respuesta, como 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized.
✅ Formatear correctamente los encabezados en cada solicitud (Content-Type, Accept, Authorization).

---

Timeouts

Para evitar tiempos de espera indefinidos y mejorar la experiencia del usuario, recomendamos:

• Establecer un timeout de conexión de 5 a 10 segundos para evitar bloqueos en caso de fallos de red.
• Definir un timeout para la lectura de respuestas de hasta 20 segundos.
• Implementar reintentos con backoff exponencial y jitter para prevenir la sobrecarga en la API.

Si una solicitud excede el tiempo máximo de espera, el servidor responderá con un HTTP 504 Gateway Timeout.

---

Manejo de JSON / Payloads

Para una integración robusta y segura, los clientes deben seguir las mejores prácticas en el manejo de respuestas JSON:

✅ Utilizar un parser JSON estándar que cumpla con RFC 8259.
✅ No asumir un orden específico en los campos JSON, ya que este puede cambiar sin previo aviso.
✅ Ignorar los espacios en blanco insignificantes y manejar correctamente caracteres especiales como comillas y barras invertidas.
✅ Utilizar UTF-8 para la codificación de datos.
✅ Aceptar propiedades adicionales en los payloads JSON, ya que pueden agregarse nuevas propiedades en el futuro.

⚠️ Evita depender de propiedades marcadas como EXPERIMENTAL en la documentación, ya que estas pueden cambiar o eliminarse sin previo aviso.

Ciclo de vida y versionado de la API de Akua

En Akua, nuestra API evoluciona de manera continua, incorporando nuevas funcionalidades y mejoras sin comprometer la estabilidad de las integraciones existentes. Utilizamos un sistema de versionado basado en versiones mayores (/v1, /v2, etc.), lo que significa que cualquier cambio disruptivo dará lugar a una nueva versión, mientras que las actualizaciones menores se implementarán dentro de la versión actual.

Este documento describe cómo gestionamos los cambios en la API, asegurando compatibilidad hacia atrás y proporcionando información clara sobre actualizaciones, deprecaciones y mejoras.

---

Principios de versionado

• Evolución incremental: mejoramos la API dentro de la versión actual (/v1), agregando nuevas funciones sin afectar la compatibilidad con las integraciones existentes.
• Transparencia: comunicamos los cambios con antelación a través de nuestro changelog y notificaciones dirigidas.

---

Cambios compatibles y no compatibles

Al actualizar la API es importante distinguir entre cambios no disruptivos (compatibles con versiones anteriores) y cambios disruptivos (que requieren una nueva versión de la API).

Cambios compatibles con versiones anteriores

Los siguientes cambios no afectan la funcionalidad de las integraciones actuales y no requieren migraciones:

• Agregar nuevos endpoints sin modificar los existentes.
• Añadir nuevos parámetros opcionales a las solicitudes.
• Agregar nuevas propiedades en las respuestas sin afectar los valores existentes.
• Cambiar el orden de los campos JSON en las respuestas.
• Introducir nuevos códigos de error sin eliminar los actuales.
• Optimizar la API para mejorar tiempos de respuesta y estabilidad sin modificar su comportamiento.

Cambios no compatibles con versiones anteriores (Breaking Changes)

Estos cambios pueden afectar las integraciones existentes y requieren una nueva versión (/v2, /v3, etc.):

• Eliminar o renombrar endpoints existentes.
• Modificar la estructura de las URLs (por ejemplo, cambiar /merchants/{id} a /accounts/{id}).
• Modificar el formato de las solicitudes o respuestas, como eliminar campos requeridos o cambiar tipos de datos.
• Cambiar los requisitos de autenticación o permisos de acceso.
• Eliminar códigos de error utilizados en la gestión de respuestas de los clientes.

Si se introduce un cambio disruptivo, se creará una nueva versión mayor de la API y se notificará a los clientes con suficiente antelación.

---

Política de deprecación

Para garantizar una transición fluida, seguimos un proceso estructurado de deprecación cuando una funcionalidad o endpoint queda obsoleto:

1. Anuncio: informamos sobre la deprecación a través de nuestro changelog y notificaciones por correo electrónico.
2. Marcado de deprecación: los endpoints obsoletos reciben una etiqueta DEPRECATED, junto con la fecha prevista de eliminación.
3. Período de transición: se otorga un tiempo de gracia (generalmente 6 meses) para permitir la migración a alternativas.
4. Eliminación: finalizado el período de transición, los endpoints obsoletos se retiran de la API. Se proveerán guías de migración cuando sea necesario.

---

Entornos de prueba y feedback

Para minimizar el impacto en las integraciones y recibir retroalimentación anticipada, ofrecemos:

• Entorno Sandbox: un entorno de prueba idéntico al de producción donde se pueden validar cambios antes de su implementación.
• Canales de feedback: recolectamos opiniones sobre los cambios a través de nuestro equipo de soporte y documentación colaborativa.
• Funciones experimentales (EXP): algunas funcionalidades pueden estar etiquetadas como EXPERIMENTAL, lo que indica que se encuentran en fase de validación y pueden sufrir cambios antes de su lanzamiento oficial.

⚠️ Nota: las funciones EXPERIMENTAL pueden modificarse sin seguir el proceso estándar de deprecación.

---

Compromiso con la estabilidad

En Akua, nuestro objetivo es mantener una API confiable y robusta que permita a nuestros clientes operar sin interrupciones. Al seguir esta política, aseguramos un equilibrio entre innovación y estabilidad, brindando la confianza necesaria para desarrollar integraciones escalables y seguras.

📩 Para cualquier consulta sobre nuestra política de versionado y la evolución de la API, contacta con nuestro equipo de soporte o visita nuestro portal de desarrolladores.

---

Ejemplo de solicitud con versión específica

Puedes especificar la versión de la API de Akua que deseas consumir indicándola en la URL de la solicitud:

curl 'https://api.akua.la/v1/payments' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer token-documentacion" \
    -X GET

Introducción

Algunos de nuestros endpoints implementan un sistema de idempotencia que garantiza que las solicitudes con la misma clave produzcan resultados idénticos, incluso cuando se envían múltiples veces. Esto previene el procesamiento duplicado de operaciones críticas, como transacciones de pago o creación de recursos.

Requisitos

Para utilizar correctamente nuestra API con idempotencia, debes incluir los siguientes headers en tus solicitudes:

Idempotency-Key: identificador único para la operación específica.

Recomendamos utilizar UUIDs v4 u otro mecanismo que genere identificadores únicos. La longitud de la clave debe estar entre 8 y 64 caracteres.

Ejemplo: Idempotency-Key: ba7b2f7d-b24d-45b6-a4ae-d89b5f235088

En caso de que este header no se incluya, la solicitud se ejecutará normalmente sin utilizar el mecanismo de idempotencia.

Ejemplo de solicitud

POST /api/payments HTTP/1.1
Host: example.akua.la
Content-Type: application/json
Idempotency-Key: ba7b2f7d-b24d-45b6-a4ae-d89b5f235088
{
    "amount": 100.00,
    "currency": "USD",
    "description": "Idempotent request"
}

Manejo de errores

Gestión de reintentos

Utiliza la misma clave de idempotencia al reintentar solicitudes fallidas.
Implementa un mecanismo de reintento con retroceso exponencial.

Organización de claves

Asocia las claves con operaciones específicas y no con sesiones de usuario.
Mantén un registro de las claves utilizadas para facilitar la depuración.

Consistencia

Nunca reutilices la misma clave para operaciones diferentes.
Asegúrate de que el body de la solicitud sea idéntico en los reintentos.

Tiempo de vida

Las claves de idempotencia se almacenan durante 24 horas. Después de este período, las solicitudes con la misma clave se tratarán como nuevas.

Entornos

Para interactuar con la API de Akua puedes utilizar dos entornos:

• Sandbox
• Producción

Ambos entornos también están disponibles en el Panel, lo que permite conectarse y probar distintas configuraciones sin necesidad de ingresar datos reales de la cuenta.

Sandbox

Es un entorno pre-productivo controlado donde puedes realizar pruebas durante la implementación.

Las pruebas realizadas en Sandbox no afectan los datos reales ni la contabilidad, ya que la información utilizada durante el modo de prueba es ficticia.

La URL base utilizada para la API de Akua en el entorno Sandbox tiene el siguiente formato:

https://sandbox.akua.la

⚠️ Importante:

El ambiente de sandbox está diseñado exclusivamente para pruebas de integración. Las autorizaciones son procesadas por un simulador de Mastercard y Visa — en ningún momento se realizan cobros reales al usuario final. Las transacciones procesadas en sandbox no pasan por el flujo de clearing ni liquidación, por lo que no generan cobros ni pagos a comercios. Para que una transacción sea efectiva y liquidada, debe procesarse en el ambiente de producción.

---

Producción

Es el entorno donde ocurren las operaciones reales que afectan la contabilidad y las métricas. Este entorno se utiliza una vez finalizadas las pruebas de integración y llegado el momento de abrir el servicio al público.

La URL base utilizada para la API de Akua en el entorno de Producción tiene el siguiente formato:

💻 Credenciales

Las credenciales para usar la API de Akua en Sandbox son diferentes de las de producción. Según el entorno que selecciones al acceder al Panel, encontrarás distintas claves de API e información de la cuenta.

https://api.akua.la

---

Tenants (Multi y Single)

En Akua soportamos ambos modelos de implementación para adaptarnos a las necesidades específicas de cada cliente.

Multi-tenant

• Múltiples clientes comparten la misma infraestructura de Akua.
• Se mantiene un aislamiento lógico entre los datos de cada cliente.

Single-tenant

• Cada cliente cuenta con su propia instancia dedicada y aislada de Akua.
• La infraestructura es exclusiva para ese cliente.
• Se mantiene un aislamiento físico de los datos.
• Ideal para clientes con requerimientos especiales de seguridad o cumplimiento normativo.

Comparación de modelos: Multi-Tenant y Single-Tenant

Beneficios

La flexibilidad de ofrecer ambos modelos nos permite adaptarnos a diferentes necesidades y presupuestos, cumplir con diversos requisitos de seguridad y cumplimiento, y brindar la mejor solución según cada caso de uso específico.

Esta sección proporciona números de tarjeta de prueba para simular distintos escenarios de autorización, aprobación y rechazo dentro del sistema de procesamiento de pagos de Akua.

Tarjetas para pagos aprobados

Los siguientes números de tarjeta de prueba simulan transacciones exitosas.

Tarjetas para pagos rechazados

Los siguientes números de tarjeta de prueba simulan distintos escenarios de rechazo.

Tarjetas para reembolsos

Los siguientes números de tarjeta de prueba simulan el comportamiento de reembolsos.

Pasos para obtener credenciales

Sigue estos pasos para obtener tus credenciales de API e integrarte con nuestra plataforma. Este artículo te guiará a través de las acciones clave para generar claves de API y comenzar a operar con Akua.

Paso 1

• Inicia sesión en el dashboard con el usuario y la contraseña creados.
• En el menú lateral, ubica y haz clic en Developers > API Keys.

Paso 2: Ver claves API existentes (Opcional)

En la sección de claves API existentes, puedes ver detalles sobre las claves ya generadas, tales como:

• Nombre: Identificador de la clave (ej. "Clave de Pagos").
• Client ID: Identificador público único de tu API.
• Permisos: Operaciones que esta clave puede realizar (ej. PAYMENTS:READ, CARDS:READ).
• Usar la acción Eliminar para remover claves existentes.

Paso 3: Crear un nuevo par de credenciales

1. Desplázate hasta la sección Generate New API Key.
2. Completa los siguientes campos:
   • Nombre de la credencial: Ingresa un nombre descriptivo para tu clave API (ej. "Clave de Integración").
3. Selecciona los permisos para esta clave API:
   • Ejemplos: PAYMENTS:READ o PAYMENTS:WRITE, CARDS:READ o CARDS:WRITE, CUSTOMERS:READ o CUSTOMERS:WRITE.
4. Haz clic en el botón Generate New API Key.

Paso 4: Guarda tus credenciales

Después de generar el nuevo par de claves, recibirás:

• Client ID: Identificador de tu aplicación.
• Client Secret: Valor sensible requerido para generar JWTs.

⚠️ Importante: El Client Secret solo se muestra una única vez, en el momento de su creación. No podrás consultarlo nuevamente. Asegúrate de copiarlo y almacenarlo de inmediato en un lugar seguro.

¿Para qué sirven los permisos?

Los permisos en Akua permiten definir el nivel de acceso que cada cliente tiene a los distintos recursos de la plataforma. Se categorizan según el tipo de recurso (ej. pagos, tarjetas, clientes) y la acción permitida (ej. lectura, escritura). Cada permiso se etiqueta con el formato RECURSO:ACCIÓN.

Permisos

Listado de permisos