Kuenta Docs

Appearance

Crear deudor​

POST
/debtor

Crea un nuevo deudor (tercero) asociado a la organización del usuario actual.

Funcionalidad:

  • Registra una entidad (persona natural o jurídica) como deudor
  • Establece relación creditor-debtor
  • Si se envía phone, además le entrega el acceso a la plataforma

Acceso a la plataforma. Sin phone, el deudor queda como ficha: no puede
autenticarse por sí mismo. Con phone, se le crea la cuenta y el flujo del cliente
queda así:

  1. POST /debtor con phone — crea la ficha y habilita el ingreso.
  2. PUT /debtor/{debtorid}/profile — carga el resto de los datos.
  3. El cliente entra con su celular: el sistema le pide crear su contraseña, le envía
    un código a ese número (TOTP) y, validado, entra viendo los datos ya cargados.

Esta llamada no entrega credenciales: crea la cuenta sin contraseña, y la prueba
de que el cliente posee el número la pone el propio ingreso con el código de un solo
uso. Por eso puede estrenar un acceso pero nunca apropiarse de uno existente.

Reglas del acceso:

  • Sólo personas naturales.
  • Si el deudor ya tiene acceso con ese mismo número, la respuesta es exitosa con
    access.alreadyGranted: true y no se escribe nada: repetir la llamada es seguro.
  • Si ya tiene acceso con OTRO número, responde 409 DebtorAccessAlreadyGranted.
  • Si el celular ya pertenece a otra cuenta o a otra ficha, responde
    409 PhoneAlreadyRegistered.
  • Si la ficha se crea pero la entrega del acceso falla, la respuesta es el error: la
    ficha queda creada y repetir la llamada con el número corregido la completa.

Tipos de entidad:

  • natural: Persona natural
  • legal: Persona jurídica

Casos de uso:

  • Registro de nuevos clientes
  • Onboarding de deudores
  • Gestión de cartera de terceros

Permisos requeridos: WriteChildEntity

Authorizations​

bearerAuth

JWT token de autenticación. Utilice este esquema para autenticar solicitudes con un token JWT.

TypeHTTP (bearer)

Parameters​

Header Parameters

Config-Organization-ID*

ID de la organización configuradora

Typestring
Required
Example550e8400-e29b-41d4-a716-446655440000
formatuuid
Organization-ID*

ID de la organización creditor

Typestring
Required
Example660e8400-e29b-41d4-a716-446655440001
formatuuid

Request Body​

application/json
JSON
{
"type": "string",
"idType": "string",
"idNumber": "string",
"phone": "+50761234567"
}

Responses​

Deudor creado exitosamente
application/json
JSON
{
"data": {
"debtor": {
"id": "string",
"type": "string",
"idType": "string",
"idNumber": "string",
"status": "string",
"parentID": "string",
"profile": {
"id": "string",
"name": "string",
"email": "string",
"phone": "string"
},
"createdAt": "string",
"updatedAt": "string"
}
},
"success": true
}

Playground​

Server
Authorization
Headers
Body

Samples​

Powered by VitePress OpenAPI