Tokens de API

Para qué sirve

Los tokens de API permiten a los sistemas internos de su empresa (CRM, backoffice propio, automatizaciones) crear y consultar legajos de apertura de cuenta sin pasar por la pantalla del operador. Un token es una credencial larga y aleatoria que su sistema envía en cada llamada, identificándose ante el servicio.

A diferencia de las credenciales de un usuario humano, los tokens están pensados para integraciones servidor a servidor: no requieren contraseña, no expiran al cabo de una sesión, y se pueden generar y revocar tantas veces como sea necesario.

Cuándo conviene usarlos

• Para alimentar legajos desde un sistema interno que ya tiene los datos del cliente cargados.
• Para consultar el estado de un legajo y reflejarlo en su propio panel.
• Para automatizar reportes o flujos que dependen del estado de las cuentas.
• Para mantener separadas las integraciones (por ejemplo, un token para producción y otro para pruebas).

Para flujos donde el cliente final completa los datos en pantalla (selfie, firma electrónica del contrato), la integración por API termina en un paso intermedio: el sistema entrega un enlace seguro que su empresa hace llegar al cliente, y el cliente termina los pasos navegables. Esos pasos no se pueden ejecutar por API porque requieren la presencia del cliente.

Permisos del token

Cada token tiene un conjunto de permisos asignados al momento de crearlo. Los permisos son granulares y se pueden combinar:

• Lectura de cuentas: el token puede consultar legajos existentes, su estado de completitud y los catálogos globales. No puede crear ni modificar.
• Escritura de cuentas: el token puede crear legajos nuevos, cargar datos del titular o de la empresa, subir documentos y gestionar enlaces para que el cliente complete los pasos navegables.

Un token con permisos limitados es preferible siempre que sea posible. Por ejemplo, un sistema que solo necesita consultar el estado de legajos debe tener únicamente lectura.

Vigencia y revocación

Los tokens pueden generarse sin fecha de vencimiento o con una fecha de expiración explícita. Cualquier token activo puede revocarse en cualquier momento desde la pantalla de gestión: la revocación es inmediata y cualquier sistema que estuviera usándolo dejará de poder operar.

Si sospecha que un token fue filtrado (por ejemplo, quedó en un repositorio público, en logs accesibles, en un correo reenviado), revóquelo inmediatamente y genere uno nuevo. No hay forma de recuperar el valor de un token existente: por seguridad, el sistema solo lo muestra una vez al crearlo y guarda únicamente un hash interno. Si lo olvidó, hay que generar uno nuevo y descartar el anterior.

Buenas prácticas

• Use un token distinto por cada integración. Si un sistema queda comprometido, revocar afecta solo a ese sistema y no obliga a reconfigurar todo lo demás.
• Asigne nombres descriptivos al token (por ejemplo, "CRM principal — producción") para reconocerlo rápidamente al revisar el listado.
• Revise periódicamente la columna Último uso para detectar tokens que ya no se usan y revocarlos.
• No incluya el token en URLs ni en parámetros de consulta: el lugar correcto es el encabezado Authorization de cada llamada.

Documentación técnica

La documentación detallada de la API (autenticación, rutas, payloads, ejemplos) está disponible en la sección Desarrolladores del manual. Está pensada para que los equipos técnicos de su empresa la consulten directamente al integrar.

Cada organización tiene su propio contrato de campos obligatorios y opcionales, configurable desde Configuración → Campos configurables. Antes de empezar a integrar, conviene revisar esos campos con el área de cumplimiento de su empresa: el cuerpo de cada llamada de creación de legajo se valida contra esa configuración, y los errores 422 indican exactamente qué campos faltan o están mal completados.