# Registro de apps compatibles

Fluxis mantiene un registro JSON público de billeteras y aplicaciones de pago que soportan el protocolo NASPIP. Los frontends usan este archivo para renderizar un selector **"Pagar con…"**: logos, enlaces a tiendas y deep links que abren la app elegida por el usuario con un token de pago ya adjunto.

## URL del registro

El registro se sirve como JSON estático desde el CDN de Fluxis:

```
https://assets.fluxis.us/sdk-assets/compatible-apps.json
```

Obténlo en tiempo de ejecución (por ejemplo, desde una página de checkout o vista web móvil). No se requiere autenticación. El archivo se actualiza a medida que nuevas aplicaciones se integran con Fluxis.

## Para qué sirve

Cuando un comercio presenta un token NASPIP (código QR, checkout alojado o hoja de pago en la app), el pagador necesita saber **qué apps pueden completar el pago**. El registro de apps compatibles responde esa pregunta en una sola solicitud apta para caché.

Uso típico en frontend:

1. Cargar `compatible-apps.json`.
2. Renderizar cada entrada como botón o fila de lista (logo + nombre para mostrar).
3. Cuando el usuario selecciona una app, reemplazar el marcador `[NASPIP_TOKEN]` en `deep_link` con el token NASPIP real de tu solicitud de pago.
4. Abrir la URL resultante (deep link móvil o universal link) para que la billetera reciba el token.

Si una app aún no tiene deep link, puedes mostrar su logo y enlazar a `website_url`, `app_store_url` o `google_play_url` para que los usuarios instalen la app y paguen vía QR.

## Esquema

El archivo es un **array JSON**. Cada elemento describe una aplicación compatible:

| Campo | Tipo | Descripción |
| ----- | ---- | ----------- |
| `name` | `string` | Identificador estable (slug en minúsculas). Úsalo como clave React o dimensión de analítica. |
| `display_name` | `string` | Nombre legible mostrado en la UI. |
| `image_url` | `string` | URL absoluta al logo de la app (SVG o PNG). |
| `website_url` | `string` | Sitio web oficial. |
| `app_store_url` | `string \| null` | Enlace a Apple App Store, si está disponible. |
| `google_play_url` | `string \| null` | Enlace a Google Play, si está disponible. |
| `deep_link` | `string \| null` | Plantilla de URL para abrir la app con un token NASPIP. Consulta [Marcador de deep link](#marcador-de-deep-link). |

Todas las URLs son absolutas. Los campos anulables usan JSON `null` cuando no aplican.

### Entrada de ejemplo

```json
{
  "name": "belo",
  "display_name": "Belo App",
  "image_url": "https://assets.fluxis.us/apps/belo.svg",
  "website_url": "https://belo.app",
  "app_store_url": "https://apps.apple.com/bo/app/belo-tu-pasaporte-financiero/id1575614708",
  "google_play_url": "https://play.google.com/store/apps/details?id=com.belo.android",
  "deep_link": "https://api.belo.app/dynamic-link?route=qri-scanner&naspip_token=[NASPIP_TOKEN]"
}
```

### Registro actual (ilustrativo)

El archivo en vivo en [compatible-apps.json](https://assets.fluxis.us/sdk-assets/compatible-apps.json) es la fuente de verdad. Al momento de escribir incluye integraciones como Belo, MetaMask y Trust Wallet, cada una con formatos de deep link específicos.

## Marcador de deep link

Cada valor `deep_link` incluye el marcador literal **`[NASPIP_TOKEN]`**. Antes de abrir el enlace, reemplázalo con el token NASPIP codificado en URL de tu solicitud de pago (el campo `token` devuelto por `POST /v1/pos/:posID/payment-request`).

```javascript
function buildDeepLink(template, naspipToken) {
  return template.replace(
    "[NASPIP_TOKEN]",
    encodeURIComponent(naspipToken),
  );
}

// Example
const deepLink = buildDeepLink(
  app.deep_link,
  paymentRequest.token,
);
window.location.href = deepLink;
```

::::tip
Para contexto sobre cómo presentar tokens NASPIP en checkout, consulta [Paso 5.1 — Mostrar el token NASPIP](/es/docs/developers/tutorials/api-integration-guide#51-mostrar-el-token-naspip) en la Guía de integración API.
::::

## Cuando `deep_link` es `null`

No todas las apps integradas exponen un deep link aún. En esos casos:

- `deep_link` es `null`.
- La app sigue listada para que los usuarios sepan que soporta Fluxis / NASPIP.
- Tu UI debe recurrir a enlaces de tienda o indicar al usuario que escanee el código QR NASPIP dentro de la app.

Solo muestra una acción **"Pagar con [app]"** que abra un deep link cuando `deep_link` no sea null.

## Crecimiento del registro

El registro es **curado por Fluxis**. A medida que billeteras y apps de pago integran nuestro protocolo y proporcionan una plantilla de deep link, las agregamos a este archivo.

Si estás construyendo una billetera o app de pago y quieres aparecer en la lista:

1. Implementa el manejo de tokens NASPIP ([Guía de implementación](/es/docs/key-concepts/naspip/implementation-guide)).
2. Proporciona una plantilla de URL de deep link con el marcador `[NASPIP_TOKEN]` (o documenta que los deep links aún no están disponibles).
3. Suministra activos de marca (`image_url`) y enlaces a tiendas.
4. Contacta [support@fluxis.us](mailto:support@fluxis.us) con los detalles de tu integración.

Actualizamos `compatible-apps.json` en el CDN; los frontends no necesitan redesplegar para obtener nuevas apps si obtienen el archivo en tiempo de ejecución. Considera un caché HTTP corto (por ejemplo, 5–15 minutos) para que los usuarios vean nuevas billeteras sin datos obsoletos indefinidamente.

## Ejemplo de integración en frontend

```javascript
const REGISTRY_URL =
  "https://assets.fluxis.us/sdk-assets/compatible-apps.json";

async function loadCompatibleApps() {
  const res = await fetch(REGISTRY_URL);
  if (!res.ok) throw new Error("Failed to load compatible apps");
  return res.json();
}

function renderPayWithApp(app, naspipToken) {
  if (!app.deep_link) {
    // No deep link — link to store or show QR-only flow
    return app.website_url;
  }
  return app.deep_link.replace(
    "[NASPIP_TOKEN]",
    encodeURIComponent(naspipToken),
  );
}
```

## Documentación relacionada

- [Token NASPIP — Introducción](/es/docs/key-concepts/naspip/introduction)
- [Guía de integración API](/es/docs/developers/tutorials/api-integration-guide)
- [Solicitud de pago](/es/docs/key-concepts/payment-request)