Copy page

Desenvolvedores

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:

Code
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.

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

Entrada de exemplo

Code
{
  "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 é 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).

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

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

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).
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 [email protected] 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

Code
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
• Guia de integração API
• Solicitação de pagamento