> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/client-facing-o-auth-grant-flow)), agrega tu identificador como el parámetro de query `external_id`:

```text theme={null}
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](/developers/widgets).

> 🚧 **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`:

```graphql theme={null}
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](/recipes/generate-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](/features/transfer-to-another-fluz-wallet)), el destino puede identificarse por ID de referencia externa en lugar de un ID de cuenta de Fluz:

```graphql theme={null}
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:

```json theme={null}
{
  "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](/developers/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í]

<StickyContactSalesBanner />

<br />