Administrar IDs de Referencia Externa

Un ID de referencia externa 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 el accountId internos de Fluz para cada usuario. Cuando un usuario autoriza tu aplicación, adjuntas tu identificador a esa concesión. 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 con tu propio ID al generar tokens, enviar transferencias y conciliar eventos de webhooks.

📘 Dónde lo verás El campo aparece como external_id en la URL de autorización OAuth y como externalReferenceId en la API GraphQL y en los payloads de webhooks. Son el mismo valor.

¿Qué puede ser?

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 externa se asigna a exactamente un usuario de Fluz.
Alcance	Con alcance a tu cliente OAuth. El mismo usuario de Fluz puede tener un ID de referencia externa diferente en la aplicación de otro desarrollador, y ninguna otra aplicación puede ver o usar el tuyo.
Estabilidad	Trátalo como inmutable. Usa un identificador estable de tu sistema — tu ID interno de usuario o un UUID.

⚠️ No uses PII como ID de referencia externa Evita direcciones de email, números de teléfono o nombres. Estos pueden cambiar con el tiempo y romperían tu mapeo, y además transmiten innecesariamente datos personales en URLs y tokens. Un UUID o la clave primaria de tu base de datos es la opción correcta.

¿Dónde lo usamos?

El ID de referencia externa circula por cuatro superficies:

Superficie	Campo	Dirección
URL de autorización OAuth	parámetro de query `external_id`	Tú → Fluz
Mutación `generateUserAccessToken`	argumento `externalReferenceId`	Tú → Fluz
Transferencias de billetera (`createTransfer`)	`destination.externalReferenceId`	Tú → Fluz
Payloads de eventos de webhook	`externalReferenceId`	Fluz → Tú

También está incrustado en el token de acceso OAuth emitido para el usuario, por lo que la asociación persiste a través de las actualizaciones de token.

¿Cómo lo usamos?

1. Asígnalo durante el flujo de autorización OAuth

Cuando dirijas a tu usuario final a la URL de autorización (ver Client facing OAuth grant flow), agrega tu identificador como el parámetro de query external_id:

https://uni.staging.fluzapp.com/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scopes=MAKE_DEPOSIT%20LIST_PAYMENT&external_id=usr_8f3d2a91

Cuando el usuario completa la concesión, Fluz registra usr_8f3d2a91 en esa autorización de tu aplicación por parte del usuario. El mismo parámetro aplica al iniciar un widget embebido — ver Widget Overview.

🚧 Requerido para aplicaciones de widget Todos los tipos de aplicaciones de widget (depósito, pagos de salida, pagos de entrada, tarjeta virtual, catálogo de tarjetas de regalo, pago de facturas y widgets de pago externo) requieren un ID de referencia externa al establecer una sesión de usuario. La solicitud será rechazada con External reference ID is required for <type> applications si se omite. Para aplicaciones OAuth estándar es opcional, pero altamente recomendado.

2. Genera tokens de acceso de usuario con él

Una vez que existe el emparejamiento, generateUserAccessToken acepta externalReferenceId en lugar de userId y accountId:

mutation {
  generateUserAccessToken(
    externalReferenceId: "usr_8f3d2a91"
    scopes: [MAKE_DEPOSIT, LIST_PAYMENT]
  ) {
    token
    refreshToken
    scopes
  }
}

Autentica esta llamada con las credenciales Basic de tu aplicación como de costumbre — ver Generate a User Access Token. Puedes pasar userId/accountId junto con externalReferenceId, pero deben coincidir con el usuario al que resuelve el ID de referencia externa. Si no coinciden, la solicitud se rechaza.

3. Indica destinos de transferencia con él

Al crear una transferencia de billetera a otra cuenta de Fluz (ver Transfer to Another Fluz Account), el destino puede identificarse por ID de referencia externa 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 de destino debe haber autorizado tu aplicación; de lo contrario, la transferencia se rechaza.

4. Haz coincidir eventos de webhooks con tus usuarios

Los payloads de webhooks incluyen externalReferenceId para que puedas correlacionar eventos de Fluz con tus propios registros de usuarios sin mantener una tabla de consulta de IDs de Fluz:

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

Consulta Configure App Widget para la configuración y detalles de entrega de webhooks.

📘 Nota de privacidad externalReferenceId se omite de los payloads de webhooks cuando la concesión del usuario no tiene un ID de referencia externa asociado, o cuando el evento está marcado como privado.

Reglas de validación y errores

Escenario	Resultado
Solicitud de token sin `externalReferenceId` ni `userId` + `accountId`	`Provide either externalReferenceId or both userId and accountId.`
`externalReferenceId` no encontrado para tu aplicación	`No user found with externalReferenceId <value>.`
`userId` provisto junto con `externalReferenceId` pero apuntando a un usuario distinto	`Provided userId does not match the user associated with the externalReferenceId.`
`accountId` provisto junto con `externalReferenceId` pero apuntando a una cuenta distinta	`Provided accountId does not match the account associated with the externalReferenceId.`
Destino de transferencia con ambos `accountId` y `externalReferenceId`	`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 externa	`External reference ID is required for <type> applications`

Agregar un ID de referencia externa a una concesión existente

Si un usuario autorizó tu aplicación antes de que adoptaras IDs de referencia externa, puedes proporcionar uno en una autorización o solicitud de token posterior y Fluz lo incorporará en la concesión existente, siempre que la concesión aún no tenga uno. Un ID de referencia externa existente nunca se sobrescribe.

Lo que no es un ID de referencia externa

No es un userId o accountId de Fluz. Esos son UUID emitidos por Fluz; el ID de referencia externa lo emites tú.
No es el external_id ni los identificadores de cuenta externa que aparecen en registros de retiros o fuentes de fondos vinculadas en otras partes de la API. Esos hacen referencia a registros bancarios y de procesadores, no a usuarios. [TBD: confirmar si alguno de estos se expone en el esquema público y debería cruzarse aquí]

​¿Qué puede ser?

​¿Dónde lo usamos?

​¿Cómo lo usamos?

​1. Asígnalo durante el flujo de autorización OAuth

​2. Genera tokens de acceso de usuario con él

​3. Indica destinos de transferencia con él

​4. Haz coincidir eventos de webhooks con tus usuarios

​Reglas de validación y errores

​Agregar un ID de referencia externa a una concesión existente

​Lo que no es un ID de referencia externa