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 ​

Configuración ​

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

{
  "url": "https://tu-dominio.com/webhook",
  "events": [
    "credit.application.created",
    "credit.application.approved",
    "credit.application.rejected",
    "payment.created",
    "payment.completed",
    "payment.failed"
  ],
  "secret": "tu-secreto-webhook"
}

Eventos disponibles ​

json
{
  "credit": [
    "credit.application.created",
    "credit.application.approved",
    "credit.application.rejected",
    "credit.disbursed",
    "credit.completed"
  ],
  "payment": [
    "payment.created",
    "payment.completed",
    "payment.failed",
    "payment.refunded"
  ],
  "document": ["document.created", "document.signed", "document.expired"],
  "validation": [
    "validation.started",
    "validation.completed",
    "validation.failed"
  ]
}

Verificación de webhooks ​

python
import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

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

    • Verifica firmas de webhooks
    • Implementa reintentos en caso de fallos
    • Procesa webhooks de forma asíncrona

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