Administrar IDs de Referencia Externos

Un ID de referencia externo es tu propio identificador para un usuario de Fluz. Te permite operar la API de Fluz usando los IDs que ya tienes en tu sistema, sin almacenar ni pasar el userId y accountId internos de Fluz para cada usuario. Cuando un usuario autoriza tu aplicación, adjuntas tu identificador a ese grant. Fluz almacena el emparejamiento entre tu identificador y la cuenta de Fluz del usuario, con alcance a tu aplicación. A partir de ese momento puedes referenciar al usuario por tu propio ID al generar tokens, enviar transferencias y conciliar eventos de webhooks. La ganancia práctica: nunca tienes que construir una tabla de consulta de IDs de Fluz. Llega un webhook, lleva tu ID de usuario, lo enrutas. Sin joins, sin caché, sin trabajos de conciliación.

Un valor, tres nombres de campo

El mismo valor aparece con un nombre diferente según la superficie. Esta es la fuente más común de confusión en esta página, así que vale la pena memorizarlo antes de empezar.

Superficie	Nombre de campo	Dirección
URL de autorización OAuth	`external_id` (parámetro de query)	Tú → Fluz
Token de transacción preaprobada del Widget	`externalId` (claim de JWT)	Tú → Fluz
GraphQL API	`externalReferenceId`	Ambos
Cargas útiles de eventos de webhook	`externalReferenceId`	Fluz → Tú
Tokens de acceso OAuth	incrustado en el token emitido	Fluz → Tú

Debido a que está incrustado en el token de acceso, la asociación sobrevive a las renovaciones de tokens: lo asignas una vez, en el momento del grant, y persiste.

Elegir un identificador

Nunca uses PII. No direcciones de correo, números de teléfono ni nombres.Dos razones, ambas concretas. Primero, cambian: la gente cambia de email y de número, y tu mapeo se rompe permanentemente porque el valor es inmutable una vez definido. Segundo, este valor viaja en query strings y claims de JWT, lo que significa que termina en el historial del navegador, headers de referer, logs de proxies y en los logs de tu propia aplicación. No pongas datos personales ahí.

Usar	Evitar	Por qué
La clave primaria de tu base de datos	Dirección de email, número de teléfono	Mutable, y es PII en una URL
Un UUID que generes por usuario	Enteros secuenciales	Enumerables; también filtran tu conteo de usuarios
Un ID opaco con prefijo como `usr_8f3d2a91`	Un ID de orden, sesión o transacción	Mapea a un evento, no a una persona — ver abajo

El error más costoso es darle el alcance equivocado. Un ID de referencia externo identifica a una persona, de forma permanente — no a una transacción, una corrida de pagos, una sesión o una orden. Si pasas un identificador por transacción, la primera transferencia funciona y la segunda crea un segundo mapeo al mismo humano, y bifurcaste a un usuario en muchos sin forma de fusionarlos.Si te encuentras generando un valor nuevo por operación, lo que quieres es una clave de idempotencia, no un ID de referencia externo.

Las reglas

Propiedad	Regla
Tipo	Cualquier string. Fluz no impone un formato.
Unicidad	Debe ser único por usuario dentro de tu aplicación. Un ID de referencia externo mapea a exactamente un usuario de Fluz.
Alcance	Con alcance a tu cliente OAuth. El mismo usuario de Fluz puede llevar un ID de referencia externo diferente en la aplicación de otro desarrollador, y ninguna otra aplicación puede ver o usar el tuyo.
Estabilidad	Inmutable en la práctica. Una vez establecido en un grant, nunca se sobrescribe.
Entorno	Los mapeos viven con la aplicación, por lo que los mapeos de staging y producción están completamente separados. Nada de lo que crees en staging existe en producción.

Asignar uno

Aplicaciones OAuth estándar

Anexa external_id a la URL de autorización cuando envíes al usuario a consentir (ver Flujo de grant orientado al cliente):

https://fluz.app/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scopes=MAKE_DEPOSIT%20LIST_PAYMENT&state=<STATE>&external_id=usr_8f3d2a91

Cuando el usuario completa el grant, Fluz registra usr_8f3d2a91 contra esa autorización de tu aplicación. Opcional aquí, pero muy recomendado. Adoptarlo después implica rellenar grants una reautorización a la vez.

Obligatorio. Todos los tipos de aplicaciones de widget — depósito, retiro, pay-in, tarjeta virtual, catálogo de tarjetas de regalo, pago de facturas y payout externo — requieren un ID de referencia externo para establecer una sesión de usuario. Sin uno, la solicitud es rechazada:

External reference ID is required for <type> applications

Para widgets, el valor viaja como el claim externalId dentro del token firmado de transacción preaprobada, junto con el monto y el tipo de transacción. Lo generas del lado del servidor; no es una opción de inicialización del cliente. Ver Configura tu servidor.

import jwt from 'jsonwebtoken';
import { v4 as uuidv4 } from 'uuid';

const generatedToken = jwt.sign(
  {
    amount,
    apiKey: process.env.FLUZ_API_KEY,
    transactionType,           // DEPOSIT (Pay-In) or WITHDRAW (Payout)
    externalId: 'usr_8f3d2a91', // your user, stable across every session
    jti: uuidv4(),              // unique per transaction — not the same thing
  },
  process.env.FLUZ_API_SECRET,
  { expiresIn: '1 day' }
);

externalId y jti están uno junto al otro en el mismo token y responden a preguntas diferentes. externalId es quién — estable durante la vida del usuario. jti es qué transacción — nuevo cada vez. Reutilizar jti rompe la idempotencia; cambiar externalId bifurca a tu usuario.

Usar uno

Direccionar destinos de transferencia

Al crear una transferencia de billetera a otra cuenta de Fluz (ver Transferir a otra billetera de Fluz), identifica el destino por tu propio ID en lugar de un ID de cuenta de Fluz:

mutation {
  createTransfer(input: {
    idempotencyKey: "1f7c5a2e-9b14-4c6d-8e3f-2a90d4b7c1aa"
    amount: 25.00
    destination: { externalReferenceId: "usr_8f3d2a91" }
  }) {
    transferId
  }
}

Proporciona destination.accountId o destination.externalReferenceId — nunca ambos. El usuario destino debe haber autorizado tu aplicación, o la transferencia se rechaza.

Hacer match de eventos de webhook con tus usuarios

Las cargas de los webhooks llevan externalReferenceId, para que puedas enrutar eventos sin una tabla de consulta:

{
  "userId": "5070d5a1-d71a-4190-91b0-f116eec51771",
  "accountId": "9c2e1b44-7a3d-4f08-b6e5-d18a3c7f0e22",
  "externalReferenceId": "usr_8f3d2a91",
  "eventType": "DEPOSIT_COMPLETE",
  "amount": 100.00
}

Maneja el caso de que el campo esté ausente. externalReferenceId se omite cuando el grant del usuario no tiene un ID de referencia externo asociado, o cuando el evento está marcado como privado. Un handler que asume que el campo siempre está presente lanzará errores en esas entregas — y un webhook handler que lanza errores es un webhook que no procesaste.

Consulta Configurar App Widget para la configuración de webhooks.

Obtener tokens con alcance de usuario

generateUserAccessToken no acepta un externalReferenceId: identifica al usuario por userId y accountId (ver Generar un token de acceso de usuario). Para usuarios que referencias por tu propio ID, usa el flujo de OAuth en su lugar. El grant ya lleva tu identificador, y los tokens que obtienes al intercambiar el código de autorización en /token/exchange se emiten para ese usuario con la asociación incrustada. Ver Intercambiar un código de autorización de OAuth.

De extremo a extremo

Un usuario, un identificador, cuatro superficies.

Tu sistema ya conoce a esta persona

El usuario usr_8f3d2a91 en tu base de datos hace clic en Conectar Fluz.

Asignar en el consentimiento

Rediriges a /authorize con external_id=usr_8f3d2a91. Inicia sesión, verifica si es necesario y aprueba tus scopes. Fluz vincula usr_8f3d2a91 a su cuenta, solo para tu aplicación.

Intercambiar

Tu callback intercambia el code por un accessToken y refreshToken. La asociación está incrustada, por lo que sobrevive a cada futura renovación. Almacenas los tokens contra usr_8f3d2a91 — sin UUIDs de Fluz en tu esquema.

Operar

Le pagas usando destination: { externalReferenceId: "usr_8f3d2a91" }, utilizando tu propio ID como dirección.

Conciliar

Llega el webhook de finalización con externalReferenceId: "usr_8f3d2a91". Lo enrutas directamente al registro de ese usuario y marcas el pago como liquidado. Sin joins, sin consultas de lookup, sin caché.

Ciclo de vida

Rellenar un grant existente

Si un usuario autorizó tu aplicación antes de que adoptaras IDs de referencia externos, proporciona uno en una autorización posterior y Fluz lo rellenará en el grant existente, siempre que el grant no tenga ya uno. Un valor existente nunca se sobrescribe.

Reautorizar con un valor diferente

Dado que un valor existente nunca se sobrescribe, pasar un external_id diferente para un usuario que ya tiene uno no cambia el mapeo. Considera que el primer valor es permanente. Si tus IDs de usuario son inestables, genera un ID inmutable dedicado para Fluz en lugar de reutilizar algo que puedas migrar.

Eliminar usuarios de tu lado

Nunca recicles un identificador. Si eliminas por completo a un usuario y luego vuelves a emitir la misma clave primaria a otra persona, esa persona nueva hereda el mapeo anterior — y la cuenta de Fluz de la persona anterior. Usa UUIDs, o una secuencia monótona que nunca reinicies.

Reglas de validación y errores

Escenario	Resultado
`externalReferenceId` no encontrado para tu aplicación	`No user found with externalReferenceId <value>.`
Destino de transferencia con `accountId` y `externalReferenceId` a la vez	`Provide either destination.accountId or destination.externalReferenceId, not both.`
El usuario destino de la transferencia no ha autorizado tu aplicación	`Destination account has not authorized this application.`
Sesión de widget creada sin un ID de referencia externo	`External reference ID is required for <type> applications`

Solución de problemas

Síntoma	Casi siempre
`No user found with externalReferenceId` para un usuario que sabes que existe	Entorno equivocado: el mapeo se creó en staging y estás llamando a producción, o al revés
La misma persona aparece como múltiples usuarios de Fluz	Se pasó un valor por transacción o por sesión en lugar de uno por usuario
El valor que pasaste en la reautorización no surtió efecto	El grant ya tenía uno; los valores existentes nunca se sobrescriben
El handler de webhook falla intermitentemente	Campo ausente en algunas entregas: grants sin asociación o eventos marcados como privados
Sesión de widget rechazada	Los tipos de widget requieren el claim `externalId` en el `patToken`; confirma que esté en el payload firmado, no solo en tus opciones de init
Transferencia rechazada como no autorizada	El usuario destino no ha autorizado tu aplicación, independientemente de que exista el mapeo

Lo que un ID de referencia externo no es

No es un userId o accountId de Fluz. Esos son UUIDs emitidos por Fluz; este lo emites tú.
No es una clave de idempotencia. Esa es idempotencyKey en llamadas de API y jti en tokens de widget, y es única por operación. Este es único por persona.
No es el parámetro state en el flujo de OAuth. state es protección CSRF por intento de autorización y no se almacena.
No son los identificadores de cuenta externa que aparecen en los registros de retiros o en fuentes de fondos vinculadas. Esos hacen referencia a registros bancarios y de procesadores, no a usuarios.

Próximos pasos

Flujo de grant

Dónde asignas el identificador para apps OAuth.

Configura tu servidor

Dónde lo asignas para apps de widget.

Transferir a otra billetera de Fluz

Direccionar transferencias con tu propio ID.

Configurar webhooks de la app

Recibir eventos que lo traen de vuelta.

Crea una plataforma

Administrar IDs de Referencia Externos

Un valor, tres nombres de campo

Elegir un identificador

Las reglas

Asignar uno

Aplicaciones OAuth estándar

Aplicaciones de Widget

Usar uno

Direccionar destinos de transferencia

Hacer match de eventos de webhook con tus usuarios

Obtener tokens con alcance de usuario

De extremo a extremo

Ciclo de vida

Rellenar un grant existente

Reautorizar con un valor diferente

Eliminar usuarios de tu lado

Reglas de validación y errores

Solución de problemas

Lo que un ID de referencia externo no es

Próximos pasos

Flujo de grant

Configura tu servidor

Transferir a otra billetera de Fluz

Configurar webhooks de la app

​Un valor, tres nombres de campo

​Elegir un identificador

​Las reglas

​Asignar uno

​Aplicaciones OAuth estándar

​Aplicaciones de Widget

​Usar uno

​Direccionar destinos de transferencia

​Hacer match de eventos de webhook con tus usuarios

​Obtener tokens con alcance de usuario

​De extremo a extremo

​Ciclo de vida

​Rellenar un grant existente

​Reautorizar con un valor diferente

​Eliminar usuarios de tu lado

​Reglas de validación y errores

​Solución de problemas

​Lo que un ID de referencia externo no es

​Próximos pasos

Flujo de grant

Configura tu servidor

Transferir a otra billetera de Fluz

Configurar webhooks de la app

Un valor, tres nombres de campo

Elegir un identificador

Las reglas

Asignar uno

Aplicaciones OAuth estándar

Aplicaciones de Widget

Usar uno

Direccionar destinos de transferencia

Hacer match de eventos de webhook con tus usuarios

Obtener tokens con alcance de usuario

De extremo a extremo

Ciclo de vida

Rellenar un grant existente

Reautorizar con un valor diferente

Eliminar usuarios de tu lado

Reglas de validación y errores

Solución de problemas

Lo que un ID de referencia externo no es

Próximos pasos