Quantian Compliance

Apariencia

Hosted flow ​

Relación con la entrega de la firma

El hosted flow es la vía para que el consumidor cierre el legajo en el portal — la usás cuando el flujo requiere biometría o faltan datos que solo el cliente puede completar. Al firmar, se aplica la entrega configurada en el flujo (email, URLs vía API o sin firma). Ver Entrega de la firma.

El hosted flow es el mecanismo para entregar el cierre del legajo al consumidor final. La API emite un magic-link seguro que su sistema entrega al cliente, y el cliente termina el onboarding desde el navegador en el portal de onboarding.

Para qué sirve ​

Hay pasos del onboarding que no se pueden ejecutar por API porque requieren al cliente físicamente presente con un dispositivo:

  • Captura de selfie con detección de vida (liveness).
  • Match contra el documento de identidad subido.
  • Lectura y aceptación electrónica del contrato.

Y hay datos que su sistema puede no tener al momento de crear el legajo (cuestionario de perfil de inversor, declaración FATCA, datos del cónyuge, cotitulares, etc.).

El hosted flow resuelve los dos casos en una sola pieza:

  1. Su sistema carga todo lo que puede por API (datos vía bulk POST, documentos vía /documents).
  2. Llama a POST /v1/accounts/{id}/hosted-flow/link y obtiene el magic-link.
  3. Lo entrega al cliente por el canal de su preferencia (email, SMS, in-app, WhatsApp).
  4. El cliente abre el link y el onboarding le muestra todos los pasos pendientes — los datos que falten, los biométricos y la firma. El onboarding usa el mismo recorrido que un legajo iniciado por el consumidor.
  5. Al terminar la firma, el legajo avanza al circuito de validación normal (due-diligence, screening, apertura en ERP). El integrador no necesita hacer ninguna llamada adicional — el cierre, la firma y la apertura en ERP corren automáticamente cuando el cliente termina en el portal.

Cuanto más cargue por API, menos tiene que hacer el cliente

El portal solo le presenta al cliente los pasos donde faltan datos o falta acción suya. Si su sistema ya completó FATCA, perfil de inversor, dirección, CBU, cotitulares y demás, el cliente solo ve liveness + firma. Cargar todo lo posible en el bulk POST acorta drásticamente el tiempo y la fricción del cierre, y permite la apertura en ERP sin viajes adicionales.

Hosted flow vs. submit por API

Son dos formas de avanzar el legajo. Usá /hosted-flow/link cuando el flujo requiere biometría (requires_liveness=true) o faltan datos que solo el cliente puede completar en el portal. Si ya cargaste todo por API y el flujo no requiere biometría, podés usar POST /v1/accounts/{id}/submit directamente. En ambos casos la firma se entrega según la entrega del flujo. Ver Entrega de la firma.

bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria.perez@example.com",
    "expires_in_hours": 24
  }' \
  https://compliance.quantian.ar/api/v1/accounts/{account-id}/hosted-flow/link

Respuesta (201 Created):

jsonc
{
  "data": {
    "url": "https://tu-broker.quantian.ar/auth/verify#token=mLk_a7c3...d4e9",
    "expires_at": "2026-05-27T15:30:00+00:00"
  }
}
  • url: el enlace que se entrega al cliente. Apunta a su subdominio; el token viaja en el fragmento de la URL (#token=...) para que nunca aparezca en logs de servidor ni en headers Referer.
  • expires_at: fecha y hora de expiración (ISO 8601 UTC).

Parámetros del request:

  • email (requerido) — email del consumidor que cerrará el legajo. Máx. 255 caracteres, debe ser un email válido.
  • expires_in_hours (opcional, default 24, mín 1, máx 168) — vida útil del link en horas.

Requiere ability accounts:write.

El id del magic-link se registra en auditoría

La respuesta no incluye el id interno del magic-link, pero queda registrado en el módulo de Auditoría del backoffice junto a la operación, con event=api.hosted-flow.link.created. Para revocación masiva o trazabilidad detallada, ese es el lugar de consulta.

Reglas de seguridad ​

El endpoint aplica tres guardas explícitas para evitar abusos:

  1. El legajo debe haber sido creado por API. Las cuentas iniciadas por el propio consumidor desde el portal de onboarding o desde el backoffice no pueden recibir un hosted-flow link vía API. Código de error devuelto: 422 Unprocessable Entity con el mensaje Hosted-flow handoff is only available for accounts created via the public API..

  2. El legajo debe estar en estado draft o in_progress. Una vez en pending_signature o más allá, el hosted flow no agrega valor: el flujo de firma siguió su curso normal. Código de error devuelto: 422 Unprocessable Entity con el mensaje Account is not in an onboarding state..

  3. Coincidencia de email si ya hay un consumidor asociado. Si el legajo ya tiene un consumer_id vinculado, el email pedido en el request debe coincidir (case-insensitive) con el del consumidor existente. Dos emails distintos no pueden compartir un mismo legajo en curso. Código de error devuelto: 422 Unprocessable Entity con el mensaje Account is already bound to a different consumer..

Re-emisión y revocación ​

Cada vez que se llama a /hosted-flow/link para un legajo, el link anterior emitido para ese par (account, consumer) queda borrado de inmediato — no espera a la expiración natural. Esto permite, por ejemplo, reenviar un link si el cliente perdió el email previo sin dejar dos links válidos en paralelo.

Si necesita revocar todos los magic-links de un consumidor (por ejemplo, ante sospecha de phishing), comunicáte con el área de cumplimiento: la revocación masiva se opera desde el backoffice.

Qué ve el cliente ​

El consumidor abre la URL en su navegador. El sitio web de Onboarding:

  1. Muestra su marca (logo, colores configurados).
  2. Identifica al cliente vía el token en el fragmento de la URL — sin pedirle registrarse ni recordar contraseña.
  3. Lo lleva paso a paso por todo lo que esté pendiente del legajo: datos personales o societarios faltantes, dirección, cotitulares, declaraciones (FATCA, origen de fondos), cuestionario de perfil de inversor, carga de documentos, selfie con liveness, firma electrónica del contrato.
  4. Al terminar la firma, dispara el cierre y muestra una pantalla de confirmación. El legajo entra al circuito de validación interno (due-diligence, screening, apertura en ERP) automáticamente.

Si su sistema ya completó una sección por API, el onboarding no se la vuelve a pedir al cliente — solo aparecen los pasos cuyo dato falta o requieren acción del cliente (biometría, firma).

Auditoría ​

Cada emisión de magic-link queda registrada en el módulo de Auditoría del backoffice con:

  • El nombre del token de API que la emitió.
  • El email destinatario y el magic_link_id.
  • La fecha de expiración configurada.
  • Evento: api.hosted-flow.link.created.

El valor del token magic-link nunca queda registrado en los logs, ni siquiera en debug — solo el id interno.

Buenas prácticas de entrega ​

  • Email transaccional: el caso más común. Aseguráte de que el dominio remitente tenga SPF/DKIM/DMARC configurados para evitar que el link caiga en spam.
  • No envíes el link en un canal donde otros podrían verlo (chats grupales, foros internos). Es una credencial.
  • Comunicá el plazo de expiración al cliente en el mismo mensaje (ej. "este enlace expira en 24 horas").
  • Habilitá un canal para que el cliente pida un link nuevo si pierde el original. Su soporte puede pedirle a su sistema que vuelva a llamar al endpoint — el link anterior queda invalidado automáticamente.