Kuenta Docs

Appearance

Listar cuentas por cobrar​

GET
/receivables

Obtiene todas las cuentas por cobrar para la entidad solicitante con opciones avanzadas de filtrado y paginación.

Funcionalidades:

  • Paginación: Resultados limitados con offset y limit
  • Filtrado por estado: Uno o múltiples estados de crédito
  • Filtrado por cuotas: Por cuotas vencidas o pendientes
  • Ordenamiento: Por fecha, monto, estado u otros campos
  • Búsqueda: Por nombre de deudor o número de identificación
  • Campos opcionales: Solicite información adicional solo cuando la necesite (include parameter)
  • Conteo de estados: Obtenga el total de créditos por estado

Casos de uso típicos:

  • Monitoreo de cartera de créditos
  • Generación de reportes financieros
  • Seguimiento de cuentas en mora
  • Integración con sistemas contables

Campos opcionales (parámetro include):

Use el parámetro include para solicitar información adicional solo cuando la necesite:

  • summary: Resumen financiero completo (balances, pagos, mora, etc.)
  • installments: Información detallada sobre estado de cuotas (vencidas, pendientes, próxima cuota, array de cuotas)
  • debtor-profile: Perfil completo del deudor con todas las subestructuras (ciudades, bancos, etc.)

Ejemplo: ?include=summary,installments

Nota: El objeto debtor (entidad del deudor) y parentID siempre se incluyen en la respuesta. Use debtor-profile solo cuando necesite el perfil completo con todas sus relaciones.

Filtros de estado de pago:

Puede filtrar créditos según el estado de sus cuotas:

  • hasOverdueInstallments=true: Solo créditos con cuotas vencidas
  • hasPendingInstallment=true: Solo créditos con cuotas pendientes (no vencidas)

Ejemplo: ?hasOverdueInstallments=true para ver solo créditos en mora.

Conteo de estados (statusCounts):

Use el parámetro statusCounts=true para obtener el conteo de créditos por estado en la respuesta.
Los conteos respetan los filtros de búsqueda y estado de pago aplicados.

Límites de rate limiting:

  • Producción: 100 requests/minuto
  • Testing: 1000 requests/minuto

Caché:

Los resultados se cachean por 5 minutos. Use el header Cache-Control: no-cache para forzar datos frescos.

Authorizations​

test

OAuth 2.0 Client Credentials Grant (RFC 6749 §4.4).
Utilice este flow para autenticación de aplicación-a-aplicación sin intervención del usuario.
Ideal para servicios backend y integración entre sistemas.

clientCredentials Flow
Token URLhttps://test-api.kuenta.co/v1/oauth/token
Scopes:
  • *Acceso completo (administrador)
  • users:readLectura de usuarios
  • users:writeEscritura de usuarios
  • users.info:writeEscritura de información de usuarios
  • clients:readLectura de clientes OAuth
  • clients:writeEscritura de clientes OAuth
  • verifications:writeEscritura de verificaciones
  • passwords:writeEscritura de contraseñas
  • keys:readLectura de claves
  • settings:readLectura de configuraciones
  • settings:writeEscritura de configuraciones
or
stage

OAuth 2.0 Client Credentials Grant (RFC 6749 §4.4).
Utilice este flow para autenticación de aplicación-a-aplicación sin intervención del usuario.
Ideal para servicios backend y integración entre sistemas.

clientCredentials Flow
Token URLhttps://stage-api.kuenta.co/v1/oauth/token
Scopes:
  • *Acceso completo (administrador)
  • users:readLectura de usuarios
  • users:writeEscritura de usuarios
  • users.info:writeEscritura de información de usuarios
  • clients:readLectura de clientes OAuth
  • clients:writeEscritura de clientes OAuth
  • verifications:writeEscritura de verificaciones
  • passwords:writeEscritura de contraseñas
  • keys:readLectura de claves
  • settings:readLectura de configuraciones
  • settings:writeEscritura de configuraciones
or
demo

OAuth 2.0 Client Credentials Grant (RFC 6749 §4.4).
Utilice este flow para autenticación de aplicación-a-aplicación sin intervención del usuario.
Ideal para servicios backend y integración entre sistemas.

clientCredentials Flow
Token URLhttps://demo-api.kuenta.co/v1/oauth/token
Scopes:
  • *Acceso completo (administrador)
  • users:readLectura de usuarios
  • users:writeEscritura de usuarios
  • users.info:writeEscritura de información de usuarios
  • clients:readLectura de clientes OAuth
  • clients:writeEscritura de clientes OAuth
  • verifications:writeEscritura de verificaciones
  • passwords:writeEscritura de contraseñas
  • keys:readLectura de claves
  • settings:readLectura de configuraciones
  • settings:writeEscritura de configuraciones
or
prod

OAuth 2.0 Client Credentials Grant (RFC 6749 §4.4).
Utilice este flow para autenticación de aplicación-a-aplicación sin intervención del usuario.
Ideal para servicios backend y integración entre sistemas.

clientCredentials Flow
Token URLhttps://api.kuenta.co/v1/oauth/token
Scopes:
  • *Acceso completo (administrador)
  • users:readLectura de usuarios
  • users:writeEscritura de usuarios
  • users.info:writeEscritura de información de usuarios
  • clients:readLectura de clientes OAuth
  • clients:writeEscritura de clientes OAuth
  • verifications:writeEscritura de verificaciones
  • passwords:writeEscritura de contraseñas
  • keys:readLectura de claves
  • settings:readLectura de configuraciones
  • settings:writeEscritura de configuraciones

Parameters​

Header Parameters

Configuration-ID

UUID de la configuración de marca blanca. Recomendado para resolución determinística.
Se resuelve automáticamente por hostname o entidad única si no se envía.

Typestring
Examplea1b2c3d4-e5f6-7890-abcd-ef1234567890
formatuuid
Organization-ID

UUID de la entidad activa. Opcional si el usuario tiene un solo rol.

Typestring
Example123e4567-e89b-12d3-a456-426614174000
formatuuid
Cache-Control

Control de caché para forzar datos frescos.

Valores comunes:

  • no-cache: Omitir caché y obtener datos frescos
  • max-age=300: Aceptar datos con hasta 5 minutos de antigüedad
Typestring
Exampleno-cache

Query Parameters

offset

Desplazamiento para paginación (número de registros a omitir).

Valor por defecto: 0
Uso: Combinar con limit para paginar resultados

Typeinteger
Example0
minimum0
default0
limit

Número de elementos a retornar.

Valor por defecto: 10
Rango: 1-100 elementos

Typeinteger
Example10
minimum1
maximum100
default10
status

Filtrar por uno o múltiples estados de crédito.

Múltiples valores: Separar con comas
Estados principales (ver CreditStatus para lista completa de 22 estados):

  • 0: InProcess - En proceso de análisis
  • 1: Pending - Pendiente de aprobación
  • 2: Approved - Aprobado
  • 3: Rejected - Rechazado
  • 5: Formalized - Formalizado
  • 7: Disbursed - Desembolsado
  • 8: Paid - Pagado completamente
  • 10: Delinquent - En mora
  • 13: AwaitingForm - Esperando formularios
  • 14: AwaitingCheck - En verificación

Filtros comunes:

  • En proceso: 0,1,2,13,14
  • Activos (desembolsados): 7,10
  • En mora: 10
  • Completados: 8
Typearray
q

Búsqueda de texto libre en nombre del deudor o número de identificación.

Funcionalidad:

  • Búsqueda parcial insensible a mayúsculas
  • Mínimo 3 caracteres
  • Busca en: nombre, apellido, razón social, número de documento
Typestring
ExampleJuan Pérez
minLength3
maxLength100
order

Campo y dirección para ordenar los resultados.

Formato: campo o campo:direccion

  • Si no se especifica dirección, se usa DESC por defecto

Campos disponibles:

  • created_at: Fecha de creación
  • updated_at: Fecha de última actualización (por defecto)
  • principal: Monto principal
  • status: Estado del crédito
  • rate: Tasa de interés
  • consecutive: Número consecutivo
  • reference: Referencia del crédito
  • disbursed_at: Fecha de desembolso
  • released_date: Fecha de liberación de fondos
  • credit_line_id_foreign_key: Línea de crédito

Ejemplos:

  • updated_at:desc: Créditos más recientemente actualizados primero
  • principal:desc: Mayor monto primero
  • status:asc: Estados en orden ascendente
  • disbursed_at:desc: Últimos desembolsados primero
Typestring
pattern^[a-z_]+(:asc|:desc)?$
defaultupdated_at:desc
summary

Incluir resumen financiero en la respuesta.

Typeboolean
defaultfalse
include

Campos opcionales adicionales a incluir en la respuesta. Permite solicitar información específica solo cuando se necesita, optimizando el rendimiento.

Formato: Lista separada por comas de campos a incluir
Valores disponibles:

  • summary: Incluye el resumen financiero completo del crédito
  • installments: Incluye información detallada sobre estado de cuotas
  • debtor-profile: Incluye el perfil completo del deudor con todas las subestructuras (ciudades, estados, países, bancos, etc.)

Campos incluidos por defecto (no necesitan ser solicitados):

  • debtor: Entidad del deudor con id, phone, idType, idNumber
  • parentID: ID del crédito padre para refinanciamientos

Ejemplos:

  • ?include=summary - Incluye resumen financiero
  • ?include=installments - Incluye información de cuotas pendientes/vencidas
  • ?include=debtor-profile - Incluye el perfil completo del deudor
  • ?include=summary,installments,debtor-profile - Incluye todos los campos opcionales

Notas:

  • Si no se especifica, estos campos opcionales no se incluyen en la respuesta
  • El campo summary en include es independiente del parámetro summary (boolean)
  • Incluir debtor-profile puede aumentar significativamente el tiempo de respuesta
Typestring
pattern^[a-zA-Z0-9,_-]+$
hasOverdueInstallments

Filtrar por créditos con cuotas vencidas.

Uso:

  • true: Solo créditos que tienen cuotas vencidas (deuda > 0 y días de mora > 0)
  • false: Solo créditos sin cuotas vencidas

Nota: Este filtro solo aplica a créditos con estado que permite cuotas (desembolsado, en mora, etc.)

Typeboolean
Exampletrue
hasPendingInstallment

Filtrar por créditos con cuotas pendientes (no vencidas).

Uso:

  • true: Solo créditos que tienen cuotas pendientes (saldo > 0 y deuda = 0)
  • false: Solo créditos sin cuotas pendientes

Nota: Este filtro solo aplica a créditos con estado que permite cuotas (desembolsado, en mora, etc.)

Typeboolean
Exampletrue
statusCounts

Incluir conteo de créditos por estado en la respuesta.

Uso:

  • true: Incluye un objeto statusCounts en la respuesta con el conteo de créditos por estado
  • false (default): No incluye el conteo

Nota: Los conteos respetan los filtros de búsqueda (q) y estado de pago (hasOverdueInstallments, hasPendingInstallment) aplicados.

Ejemplo de respuesta con statusCounts:

{
  "credits": [...],
  "statusCounts": {
    "0": 5,   // InProcess
    "4": 23,  // Disbursed
    "10": 12  // Delinquent
  }
}
Typeboolean
Exampletrue
defaultfalse

Responses​

Cuentas por cobrar obtenidas exitosamente. La respuesta incluye un array de créditos que cumplen los criterios especificados y opcionalmente un conteo de créditos por estado. **Nota sobre paginación:** Use `offset` y `limit` para paginar. El endpoint no devuelve metadatos de paginación (total, páginas, etc.). Para obtener el total de créditos por estado, use `statusCounts=true`.
application/json

Respuesta cuando no hay créditos que cumplan los criterios de filtrado especificados

JSON
{
"status": "success",
"data": {
"credits": [
]
}
}

Playground​

Server
Authorization
Headers
Variables
Key
Value

Samples​

Powered by VitePress OpenAPI