Kuenta Docs

Appearance

Crear solicitud de asistencia para entidad​

POST
/entities/{entityid}/assistance

Crea una solicitud de asistencia temporal para la entidad objetivo y envía automáticamente el código OTP.

Funcionalidad mejorada:

  • Operación atómica: La creación de la asistencia y el envío del OTP se realizan en una sola operación
  • Información detallada del OTP: La respuesta incluye logs detallados del intento de envío de OTP
  • Manejo de fallos: Si el OTP falla, la asistencia se crea exitosamente pero se informa el error del envío
  • Frontend reactivo: El frontend puede reaccionar apropiadamente según el estado del envío de OTP

Flujo de asistencia:

  1. Se validan los campos obligatorios (permissions y channel)
  2. Se crea la solicitud con los permisos solicitados
  3. Se envía automáticamente un código TOTP al cliente por el canal especificado
  4. Se retorna información detallada tanto de la asistencia como del log de OTP
  5. El cliente debe verificar el código para aprobar la asistencia
  6. Una vez aprobada, se crea un rol temporal con los permisos otorgados

Respuesta estructurada:

  • request: Información de la solicitud de asistencia creada
  • otpLog: Log detallado del intento de envío de OTP (éxito o fallo)

Validaciones obligatorias:

  • permissions: Debe contener al menos un permiso válido
  • channel: Debe ser uno de los canales soportados (sms, email, voice)

Canales de comunicación:

  • sms: Envío por mensaje de texto
  • email: Envío por correo electrónico
  • voice: Envío por llamada de voz

Sistema de permisos granular:
El sistema utiliza permisos específicos con formato acción:recurso:

  • read: Permisos de solo lectura (ej: read:profile, read:document)
  • write: Permisos de escritura (ej: write:document, write:receivable)
  • Ver el schema de permisos para la lista completa y descripciones detalladas

Generación automática de roles:
Los nombres de los roles temporales se generan automáticamente según los permisos solicitados:

  • Asistencia de Lectura: Para permisos de solo lectura
  • Asistencia de Documentos: Para gestión de documentos
  • Asistencia Financiera: Para gestión de pagos y cuentas por cobrar
  • Asistencia Técnica: Para configuraciones y plantillas
  • Asistencia Completa: Para múltiples categorías de permisos

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​

Path Parameters

entityid*

ID de la entidad objetivo (a quién se solicita la asistencia)

Typestring
Required
Example123e4567-e89b-12d3-a456-426614174000
formatuuid

Request Body​

application/json
JSON
{
"permissions": [
"read:profile",
"read:document",
"write:document"
],
"channel": "string"
}

Responses​

Solicitud de asistencia creada exitosamente con información detallada del envío de OTP
application/json
JSON
{
"status": "success",
"data": {
"request": {
"id": "b8a00e72-17cf-436f-9cb8-8d99b08d386c",
"requestID": "ASST1234567890",
"status": "sent",
"expiresAt": "2025-09-22T15:30:00Z",
"channel": "sms",
"requestedPermissions": [
"read:profile",
"read:document"
],
"estimatedDuration": "30 minutos",
"recipientPhone": "+57***1234"
},
"otpLog": {
"id": "763b7ece-b4ae-4f1e-ba2e-b6ed450e99fa",
"channel": "sms",
"sentAt": "2025-09-22T14:00:00Z",
"deliveryStatus": "sent",
"attemptNumber": 1,
"isCooldownViolation": false,
"cooldownRemaining": 0,
"processingTimeMs": 1250,
"maskedPhone": "+57***1234"
}
}
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​

Powered by VitePress OpenAPI