Kuenta Docs

Appearance

Integración con API ​

Kuenta ofrece una API RESTful completa para integrar todas las funcionalidades de la plataforma en tus sistemas.

Endpoints ​

Lista de endpoints

Autenticación ​

Headers requeridos ​

http
Config-Organization-ID: tu-id-de-organizacion
Organization-ID: tu-id-de-organizacion
Authorization: Bearer tu-token-de-acceso

Restablecimiento de contraseña ​

Kuenta proporciona un flujo seguro para el restablecimiento de contraseñas:

  1. Solicitar código de verificación (TOTP) al número de teléfono del usuario
  2. Recibir el código mediante SMS o llamada
  3. Utilizar el código junto con el nuevo password para completar el restablecimiento:
http
POST /v1/auth/password/reset
Content-Type: application/json

{
  "phone": "+573001234567",
  "TOTP": "123456",
  "password": "NuevaContraseña123"
}

Obtención de token ​

http
POST /v1/oauth/token
Content-Type: application/json

{
  "client_id": "tu-client-id",
  "client_secret": "tu-client-secret",
  "grant_type": "client_credentials"
}

Ambientes disponibles ​

  • Producción: https://api.kuenta.co/v1
  • Pruebas: https://test-api.kuenta.co/v1
  • Stage: https://stage-api.kuenta.co/v1
  • Demo: https://demo-api.kuenta.co/v1

Endpoints principales ​

Gestión de créditos ​

http
# Crear solicitud de crédito
POST /v1/credit-applications

# Obtener estado de solicitud
GET /v1/credit-applications/{id}

# Aprobar crédito
POST /v1/credit-applications/{id}/approve

# Rechazar crédito
POST /v1/credit-applications/{id}/reject

Gestión de pagos ​

http
# Crear pago
POST /v1/payments

# Obtener estado de pago
GET /v1/payments/{id}

# Obtener historial de pagos
GET /v1/loans/{id}/payments

Validación de identidad ​

http
# Iniciar validación
POST /v1/identity-validation

# Obtener resultado
GET /v1/identity-validation/{id}

# Verificar documento
POST /v1/documents/verify

Webhooks ​

Kuenta puede notificar a tu sistema con una solicitud HTTP saliente cuando se aprueba un pago o se desembolsa un crédito de una línea de crédito específica. El webhook se crea y configura por separado (URL, cuerpo, autenticación saliente) y luego se asocia a la línea de crédito correspondiente.

http
POST /v1/webhook
Content-Type: application/json
Organization-ID: tu-id-de-organizacion

{
  "tag": "notificacion-desembolso",
  "url": "https://tu-dominio.com/webhook",
  "requestBody": "{\"creditId\":\"{{ .Credit.ID }}\",\"status\":\"{{ .Credit.Status }}\"}"
}

El cuerpo de la solicitud (requestBody) es una plantilla evaluada contra el crédito que disparó el evento, no un payload de forma fija. Para el detalle completo (puntos de disparo disponibles, sintaxis de la plantilla, autenticación saliente y cómo asociar el webhook a una línea de crédito), consulta la guía de Webhooks.

SDKs disponibles ​

Python ​

python
from kuenta import KuentaClient

client = KuentaClient(
    organization_id="tu-id-de-organizacion",
    client_id="tu-client-id",
    client_secret="tu-client-secret"
)

# Crear solicitud de crédito
application = client.credit_applications.create({
    "amount": 5000000,
    "term": 12,
    "term_unit": "months"
})

Node.js ​

javascript
const { KuentaClient } = require("@kuenta/sdk");

const client = new KuentaClient({
  organizationId: "tu-id-de-organizacion",
  clientId: "tu-client-id",
  clientSecret: "tu-client-secret",
});

// Crear solicitud de crédito
const application = await client.creditApplications.create({
  amount: 5000000,
  term: 12,
  termUnit: "months",
});

Mejores prácticas ​

  1. Manejo de errores

    • Implementa reintentos con backoff exponencial
    • Valida respuestas y maneja errores específicos
    • Registra errores para debugging

  2. Seguridad

    • Almacena credenciales de forma segura
    • Usa HTTPS para todas las comunicaciones
    • Implementa rate limiting en tu lado

  3. Webhooks

    • Kuenta no reintenta automáticamente el envío si tu endpoint falla o no responde; si necesitas reenviar una notificación, puede ejecutarse manualmente (POST /v1/webhook/{webhookid}/request, ver Webhooks). Diseña tu integración para tolerar esto (por ejemplo, consultando el estado del crédito por API como respaldo).
    • Procesa webhooks de forma asíncrona y responde rápido a la solicitud entrante
    • Si necesitas verificar el origen de la solicitud, acuerda con Kuenta un encabezado estático propio (no hay firma HMAC automática)

Próximos pasos ​

Soporte ​

Si necesitas ayuda con la integración:

  • Consulta la documentación técnica
  • Contacta al equipo de soporte
  • Revisa las preguntas frecuentes