# Registro de apps compatíveis

A Fluxis mantém um registro JSON público de carteiras e aplicativos de pagamento que suportam o protocolo NASPIP. Frontends usam esse arquivo para renderizar um seletor **"Pagar com…"**: logos, links de loja e deep links que abrem o app escolhido pelo usuário com um token de pagamento já anexado.

## URL do registro

O registro é servido como JSON estático no CDN da Fluxis:

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

Busque-o em tempo de execução (por exemplo, em uma página de checkout ou webview móvel). Não é necessária autenticação. O arquivo é atualizado conforme novos aplicativos se integram à Fluxis.

## Para que serve

Quando um comerciante apresenta um token NASPIP (QR code, checkout hospedado ou folha de pagamento no app), o pagador precisa saber **quais apps podem concluir o pagamento**. O registro de apps compatíveis responde isso em uma única requisição amigável a cache.

Uso típico no frontend:

1. Carregar `compatible-apps.json`.
2. Renderizar cada entrada como botão ou linha de lista (logo + nome de exibição).
3. Quando o usuário seleciona um app, substituir o placeholder `[NASPIP_TOKEN]` em `deep_link` pelo token NASPIP real da sua solicitação de pagamento.
4. Abrir a URL resultante (deep link móvel ou universal link) para que a carteira receba o token.

Se um app ainda não tem deep link, você ainda pode exibir o logo e linkar para `website_url`, `app_store_url` ou `google_play_url` para que usuários instalem o app e paguem via QR.

## Esquema

O arquivo é um **array JSON**. Cada elemento descreve um aplicativo compatível:

| Campo | Tipo | Descrição |
| ----- | ---- | ----------- |
| `name` | `string` | Identificador estável (slug em minúsculas). Use como chave React ou dimensão de analytics. |
| `display_name` | `string` | Nome legível exibido na UI. |
| `image_url` | `string` | URL absoluta do logo do app (SVG ou PNG). |
| `website_url` | `string` | Site oficial. |
| `app_store_url` | `string \| null` | Link da Apple App Store, se disponível. |
| `google_play_url` | `string \| null` | Link do Google Play, se disponível. |
| `deep_link` | `string \| null` | Template de URL para abrir o app com um token NASPIP. Consulte [Placeholder de deep link](#placeholder-de-deep-link). |

Todas as URLs são absolutas. Campos anuláveis usam JSON `null` quando não se aplicam.

### Entrada de exemplo

```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 atual (ilustrativo)

O arquivo ao vivo em [compatible-apps.json](https://assets.fluxis.us/sdk-assets/compatible-apps.json) é a fonte da verdade. No momento da redação inclui integrações como Belo, MetaMask e Trust Wallet, cada uma com formatos de deep link específicos.

## Placeholder de deep link

Todo valor `deep_link` inclui o placeholder literal **`[NASPIP_TOKEN]`**. Antes de abrir o link, substitua-o pelo token NASPIP codificado em URL da sua solicitação de pagamento (o campo `token` retornado 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 apresentar tokens NASPIP no checkout, consulte [Etapa 5.1 — Exibir o token NASPIP](/pt/docs/developers/tutorials/api-integration-guide#51-exibir-o-token-naspip) no Guia de integração API.
::::

## Quando `deep_link` é `null`

Nem todo app integrado expõe deep link ainda. Nesses casos:

- `deep_link` é `null`.
- O app continua listado para que usuários saibam que suporta Fluxis / NASPIP.
- Sua UI deve recorrer a links de loja ou orientar o usuário a escanear o QR NASPIP dentro do app.

Exiba a ação **"Pagar com [app]"** que abre deep link somente quando `deep_link` não for null.

## Crescimento do registro

O registro é **curado pela Fluxis**. Conforme carteiras e apps de pagamento integram nosso protocolo e fornecem um template de deep link, adicionamos entradas a este arquivo.

Se você está construindo uma carteira ou app de pagamento e quer ser listado:

1. Implemente o tratamento de tokens NASPIP ([Guia de implementação](/pt/docs/key-concepts/naspip/implementation-guide)).
2. Forneça um template de URL de deep link com o placeholder `[NASPIP_TOKEN]` (ou documente que deep links ainda não estão disponíveis).
3. Forneça assets de marca (`image_url`) e links de loja.
4. Entre em contato em [support@fluxis.us](mailto:support@fluxis.us) com os detalhes da integração.

Atualizamos `compatible-apps.json` no CDN; frontends não precisam redeploy para obter novos apps se buscarem o arquivo em tempo de execução. Considere cache HTTP curto (por exemplo, 5–15 minutos) para que usuários vejam novas carteiras sem dados obsoletos por muito tempo.

## Exemplo de integração no 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),
  );
}
```

## Documentação relacionada

- [Token NASPIP — Introdução](/pt/docs/key-concepts/naspip/introduction)
- [Guia de integração API](/pt/docs/developers/tutorials/api-integration-guide)
- [Solicitação de pagamento](/pt/docs/key-concepts/payment-request)