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

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:

POST /v1/auth/password/reset
Content-Type: application/json

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

Obtención de token

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

# 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

# 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

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

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

# Verificar documento
POST /v1/documents/verify

Precargar un cliente y darle acceso

El caso típico de una integración: tú creas al cliente desde tu sistema, cargas sus datos, y le pasas un enlace para que pida su crédito. Para que ese cliente pueda entrar a la plataforma necesita una cuenta, y la cuenta se pide explícitamente enviando su celular al crear la ficha.

El flujo completo

# 1. Crear la ficha Y pedir la cuenta, en una sola llamada.
#    `phone` es opcional: sin él, el cliente queda registrado pero no puede entrar.
POST /v1/debtor
Content-Type: application/json

{
  "type": "natural",
  "idType": "CC",
  "idNumber": "1234567890",
  "phone": "+50761234567"
}

{
  "status": "success",
  "data": {
    "debtor": { "id": "770e8400-...", "type": "natural", "idNumber": "1234567890" },
    "access": { "debtorID": "770e8400-...", "userID": "88f...", "phone": "+50761234567" }
  }
}

# 2. Cargar el resto de la información del cliente.
PUT /v1/debtor/{debtorid}/profile

# 3. Pasarle el enlace. Al entrar con su celular, el cliente:
#    - crea su propia contraseña,
#    - recibe un código de verificación en ese número,
#    - y continúa viendo los datos que ya cargaste.

Qué NO hace esta llamada

No entrega credenciales. La cuenta se crea sin contraseña. La prueba de que el cliente posee ese número la pone el propio ingreso, con el código de un solo uso. Ni esta API ni ningún mensaje envían una contraseña.

Por eso esta llamada puede estrenar el acceso de una ficha que aún no tiene dueño, pero nunca apoderarse de una cuenta que ya lo tiene.

Reglas

Situación	Respuesta
Ficha nueva, celular libre	201 con data.access
Ya tiene cuenta con ese mismo celular	201 con access.alreadyGranted: true, sin escribir nada
Ya tiene cuenta con otro celular	409 DebtorAccessAlreadyGranted
El celular pertenece a otra cuenta o a otra ficha	409 PhoneAlreadyRegistered
El deudor es persona jurídica	412 — ver abajo

Repetir la llamada es seguro. Si un corte de red te deja sin saber si la primera llamada llegó, repítela: con el mismo celular responde éxito sin duplicar nada.

Si la ficha se crea pero la cuenta falla, la respuesta es el error y la ficha queda creada. Repetir el alta con el celular corregido la completa: la ficha se reutiliza, no se duplica. Ese mismo camino sirve para dar acceso a clientes que ya tenías cargados sin él.

Personas jurídicas

Una persona jurídica no ingresa a la plataforma. Quien ingresa es una persona natural —su representante legal, administrador o socio—, y su acceso se pide sobre su propia ficha de persona natural, con este mismo mecanismo.

El celular

Envíalo con indicativo de país (+507...). Un número sin indicativo se interpreta como colombiano, y si el cliente después intenta entrar escribiéndolo de otra forma, el sistema no encontrará su cuenta.

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.

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

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

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

• Configura tus webhooks
• Configura tus plantillas de documentos
• Configura tus flujos de validación

Soporte

Si necesitas ayuda con la integración:

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