Skip to main content
registerUser aprovisiona una cuenta de Fluz para alguien usando datos de perfil que ya posees — sin redirección, sin formulario alojado, sin pedirle al usuario que vuelva a escribir su nombre y fecha de nacimiento.
Acceso restringido. Esta mutación requiere permiso explícito de Fluz. Contacta a tu gerente de cuenta para habilitar el registro de usuarios para tu aplicación. Las llamadas desde una aplicación sin ese permiso fallan con AUTH-0022.

Dónde encaja

El registro es un paso dentro de un flujo de incorporación y es opcional — puedes delegar todo a un widget en su lugar. Registra usuarios tú mismo cuando ya tienes datos de perfil limpios y no quieres que el usuario los escriba dos veces. Si estarías recopilando nombre, fecha de nacimiento y datos de contacto únicamente para pasarlos a Fluz, usa un widget incrustado en su lugar — mantiene esa recopilación dentro del alcance de cumplimiento de Fluz. La secuencia completa para la ruta por API:
1

Registrar

registerUser con nombre, teléfono, email y fecha de nacimiento.
2

Verificar

Ejecuta KYC con verifyUserInformation, o entrega al usuario un enlace de verificación de documentos. → Verificación KYC del usuario
3

Obtener autorización

El usuario otorga alcances (scopes) a tu aplicación. → Flujo de otorgamiento OAuth orientado al cliente
4

Operar

Genera un token de acceso de usuario y usa la API en su nombre. → Autenticación

La mutación

error es un objeto (RegisterUserError), no una cadena — siempre selecciona code y message como subcampos. Solicitar error a secas no compila.

Parámetros

Los nombres deben coincidir con los documentos de identidad con los que el usuario se verificará — una discrepancia aparecerá más tarde como una falla de KYC, mucho más difícil de diagnosticar que un error de registro.

Qué se crea

Una cuenta completa de Fluz: el registro del usuario, su billetera y saldos, y su elegibilidad de recompensas. No hay nada más que aprovisionar antes de que la cuenta pueda verificarse y usarse.

Manejo de la respuesta

Las fallas regresan en data, no en errors. Un registro fallido es un HTTP 200 con success: false. El código que solo revisa el arreglo errors de GraphQL interpretará cada falla como un éxito.
Success
Failure
Un manejador que cubre correctamente las tres capas:

“Ya en uso” es una señal de enrutamiento, no un error

AUTH-0026 (teléfono) y AUTH-0027 (email) significan que la persona ya tiene una cuenta de Fluz. Es un resultado normal y esperado — las cuentas de Fluz no están limitadas a tu aplicación, así que cualquiera que haya usado Fluz antes, mediante cualquier app o el producto para consumidores, ya existe. Tratar esto como una falla es el error de integración más común aquí. La respuesta correcta es dejar de intentar crear una cuenta y empezar a pedir acceso a la ya existente: envía al usuario por el flujo de otorgamiento OAuth, o abre un widget. Inician sesión en la cuenta que ya tienen y te autorizan. Diseña tu incorporación para que el camino registrar-y-luego-retroceder sea el caso normal en lugar de una rama de excepción, y se mantendrá limpio a escala.

Reintentos y duplicados

registerUser no acepta clave de idempotencia. Un reintento es un intento genuinamente nuevo, y un timeout tiene resultado desconocido.
Si una llamada expira o la conexión se cae, es muy posible que el registro haya tenido éxito. Reintentar la solicitud idéntica luego devuelve AUTH-0026 — lo cual es indistinguible de que el usuario ya tuviera una cuenta desde antes. Esa ambigüedad es inocua siempre que trates ambos casos igual: ante un timeout, reintenta una vez, y enruta AUTH-0026 / AUTH-0027 hacia autorización en lugar de a un estado de error. Ya sea la cuenta que acabas de crear o la que ya existía terminará autorizada, que es el resultado que buscabas. Lo que no debes hacer es mostrar “el número de teléfono ya está en uso” a un usuario que acaba de darte su número por primera vez.

Después del registro

Una cuenta registrada aún no está verificada. Antes de que el usuario pueda mover dinero necesitas:
  1. Verificación de identidad. Pasa el SSN y la dirección que tienes a verifyUserInformation, o emite un enlace de verificación de documentos para que el usuario lo complete. → Verificación KYC del usuario
  2. Un otorgamiento de autorización. Registrar a alguien no te da permiso para actuar en su nombre — es un paso separado y explícito. → Flujo de otorgamiento OAuth orientado al cliente
  3. Tu propio identificador adjunto. Pasa external_id en la autorización para poder dirigirte a esta persona con tu propio ID de usuario a partir de entonces. → Gestión de IDs de referencia externa

Manejo de los datos

Estás transmitiendo nombre completo, fecha de nacimiento, email y número de teléfono — un conjunto que identifica a una persona real. Envíalo sobre TLS desde tu servidor, mantenlo fuera de logs y de cargas de seguimiento de errores, y no lo repitas en respuestas visibles al cliente. Ten en cuenta que la fecha de nacimiento en particular es un dato de identidad regulado en la mayoría de las jurisdicciones, y sigue siendo sensible de tu lado después de que la llamada tenga éxito. Si prefieres no conservar ninguno de esos datos, ese es el argumento para el widget — Fluz los recopila dentro de su propio alcance de cumplimiento y tú nunca los tocas.

Códigos de error


Entornos

Apunta al host de GraphQL para tu entorno — https://transactional-graph.staging.fluzapp.com/api/v1/graphql para staging, https://transactional-graph.fluzapp.com/api/v1/graphql para producción. El permiso de registro se otorga por aplicación, por lo que una app de producción necesita que se habilite por separado. → Implementación en producción Nunca registres personas reales en staging. → Staging vs. Live

Próximos pasos

Verificación KYC del usuario

Verifica la cuenta que acabas de crear.

Flujo de otorgamiento

Obtén permiso para actuar en su nombre.

IDs de referencia externa

Dirígete a ellos con tu propio ID de usuario.

Widgets incrustados

Entrega toda la incorporación a Fluz en su lugar.