Kuenta Docs

Appearance

Primeros pasos con Kuenta API ​

Esta guía te ayudará a comenzar rápidamente con la API de Kuenta. Sigue estos pasos para hacer tu primera integración.

Requisitos previos ​

Antes de comenzar, asegúrate de tener:

  • Una cuenta activa en Kuenta
  • Acceso a la sección de integraciones
  • Permisos de administrador en tu organización

1. Obtener credenciales de API ​

Acceso al portal de integraciones ​

  1. Inicia sesión en el Portal de Kuenta
  2. Navega a la sección de "Integraciones"
  3. Selecciona "Clientes OAuth"

Crear una nueva aplicación ​

  1. Haz clic en "Agregar nueva aplicación"
  2. Proporciona un nombre descriptivo
  3. Selecciona los permisos necesarios
  4. Guarda la configuración

Guardar las credenciales ​

Al crear la aplicación, recibirás:

  • Client ID: Identificador único de tu aplicación
  • Client Secret: Clave secreta para autenticación
  • Entity ID: Identificador de tu organización

⚠️ Importante: Guarda estas credenciales en un lugar seguro. El Client Secret solo se muestra una vez.

2. Autenticación ​

Obtener token de acceso ​

Realiza una petición POST al endpoint de autenticación:

http
POST https://api.kuenta.co/v1/oauth/token
Content-Type: application/json

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

Respuesta de autenticación ​

json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

3. Realizar tu primera llamada ​

Headers requeridos ​

http
Authorization: Bearer tu-access-token
Config-Organization-ID: tu-entity-id
Organization-ID: tu-entity-id

Ejemplo de llamada ​

bash
curl -X GET "https://api.kuenta.co/v1/credit-lines" \
  -H "Authorization: Bearer tu-access-token" \
  -H "Config-Organization-ID: tu-entity-id" \
  -H "Organization-ID: tu-entity-id"

4. Manejo de errores ​

Códigos de estado comunes ​

  • 200 OK: La petición fue exitosa
  • 400 Bad Request: Error en los parámetros de la petición
  • 401 Unauthorized: Token inválido o expirado
  • 403 Forbidden: No tienes permisos para la operación
  • 404 Not Found: Recurso no encontrado
  • 429 Too Many Requests: Límite de peticiones excedido

Ejemplo de error ​

json
{
  "error": {
    "code": "invalid_request",
    "message": "El token de acceso ha expirado",
    "details": {
      "expired_at": "2024-03-20T10:00:00Z"
    }
  }
}

5. 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

💡 Consejo: Comienza en el ambiente de pruebas para familiarizarte con la API antes de pasar a producción.

6. Mejores prácticas ​

  1. Seguridad

    • Almacena las credenciales de forma segura
    • Nunca compartas tu Client Secret
    • Usa HTTPS para todas las comunicaciones

  2. Manejo de tokens

    • Implementa renovación automática de tokens
    • Maneja la expiración de tokens
    • No reutilices tokens expirados

  3. Rate limiting

    • Respeta los límites de peticiones
    • Implementa reintentos con backoff exponencial
    • Maneja los errores 429 apropiadamente

Soporte ​

Si necesitas ayuda durante la integración:

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