# Casos de uso

Este documento explora aplicações e casos de uso do mundo real para implementar pagamentos seguros com Fluxis API e o protocolo NASPIP, demonstrando como integrar pagamentos blockchain em suas aplicações usando o fluxo de API de comerciante compatível.

::::tip Authentication pattern
Todos os exemplos abaixo assumem que você já trocou sua chave API e segredo por um token Bearer via `POST /v1/auth/token`. Rotas protegidas exigem **ambos** `Authorization: Bearer <token>` e `x-fluxis-api-key: <api_key>`. Nunca exponha segredos API em código client-side.
::::

## E-commerce e varejo

### Pagamentos em loja online

**Cenário**: Uma plataforma de e-commerce quer aceitar pagamentos com criptomoedas junto com métodos de pagamento tradicionais.

**Solução Fluxis API**:

```javascript
const API_BASE = "https://api.fluxis.us/v1";
const POS_ID = "YOUR_POINT_OF_SALE_ID";

// 1) Troque chave API + segredo por um token de acesso (somente server-side)
const authRes = await fetch(`${API_BASE}/auth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: process.env.FLUXIS_API_KEY,
    api_secret: process.env.FLUXIS_API_SECRET,
  }),
});
const { data: auth } = await authRes.json();

// 2) Crie uma solicitação de pagamento para um checkout
const prRes = await fetch(`${API_BASE}/pos/${POS_ID}/payment-request`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${auth.token}`,
    "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "299.99",
    unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    reference_id: "order-12345",
  }),
});
const { data: paymentRequest } = await prRes.json();

// 3) Apresente paymentRequest.token ao pagador (QR / deep link / checkout hospedado)
// Opcional: POST /pos/:posID/payment-request-checkout para uma URL de checkout hospedado
```

**Benefícios**:

- **🚀 Integração rápida**: Comece em minutos com Fluxis API
- **🔐 Segurança empresarial**: Instruções de pagamento NASPIP assinadas (PASETO v4) e verificação de assinatura de webhooks
- **🌐 Multirrede**: Suporte a ativos EVM configurados (UAIs) em redes habilitadas como Polygon, Base, Avalanche e Arbitrum
- **📱 Checkout flexível**: Token NASPIP QR, deep links ou checkout hospedado
- **⚡ Alto desempenho**: Infraestrutura escalável para aplicações de produção

### Sistemas de ponto de venda (POS)

**Cenário**: Uma loja de varejo quer aceitar pagamentos com criptomoedas em locais físicos usando um fluxo estilo caixa.

**Implementação Fluxis API**:

```javascript
const API_BASE = "https://api.fluxis.us/v1";

class POSSystem {
  constructor(apiKey, apiSecret, posId) {
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
    this.posId = posId;
    this.accessToken = null;
  }

  async authenticate() {
    const res = await fetch(`${API_BASE}/auth/token`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        api_key: this.apiKey,
        api_secret: this.apiSecret,
      }),
    });
    const { data } = await res.json();
    this.accessToken = data.token;
  }

  authHeaders() {
    return {
      Authorization: `Bearer ${this.accessToken}`,
      "x-fluxis-api-key": this.apiKey,
      "Content-Type": "application/json",
    };
  }

  async createPaymentIntention(amount, coinCode = "USD") {
    const res = await fetch(
      `${API_BASE}/pos/${this.posId}/payment-intention`,
      {
        method: "POST",
        headers: this.authHeaders(),
        body: JSON.stringify({
          amount,
          coin_code: coinCode,
          external_id: `pos-${Date.now()}`,
        }),
      },
    );
    return (await res.json()).data;
  }

  async getPaymentRequest(paymentRequestId) {
    const res = await fetch(
      `${API_BASE}/pos/${this.posId}/payment-request/${paymentRequestId}`,
      { headers: this.authHeaders() },
    );
    return (await res.json()).data;
  }
}

// Uso
const pos = new POSSystem(
  process.env.FLUXIS_API_KEY,
  process.env.FLUXIS_API_SECRET,
  "YOUR_POS_ID",
);
await pos.authenticate();
const intention = await pos.createPaymentIntention(50.0, "USD");
// Exiba o token de intenção como QR; faça polling ou use webhooks para atualizações de status
```

## Serviços financeiros

### Remessas transfronteiriças

**Cenário**: Um serviço de remessas quer oferecer transferências internacionais rápidas e de baixo custo usando stablecoins.

**Implementação Fluxis API**:

```javascript
async function createRemittancePayment({ amount, referenceId, posId }) {
  const auth = await getAccessToken(); // POST /v1/auth/token

  const res = await fetch(
    `https://api.fluxis.us/v1/pos/${posId}/payment-request`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.token}`,
        "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: amount.toString(),
        unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        reference_id: referenceId,
        order: {
          description: "Cross-border remittance",
        },
      }),
    },
  );

  const { data } = await res.json();
  return {
    paymentRequestId: data.id,
    naspipToken: data.token,
    expiration: data.expiration,
  };
}
```

Registre um webhook de conta para receber atualizações de status `completed`, `underpaid` ou `overpaid` e execute a transferência após confirmação do pagamento.

### Integração de pagamentos DeFi

**Cenário**: Um protocolo DeFi quer integrar instruções de pagamento seguras para yield farming e provisão de liquidez.

```javascript
async function createPoolDepositPayment({ poolAddress, amount, posId }) {
  const auth = await getAccessToken();

  const res = await fetch(
    `https://api.fluxis.us/v1/pos/${posId}/payment-request`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.token}`,
        "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: amount.toString(),
        unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        reference_id: `pool-${poolAddress.slice(0, 8)}`,
        order: {
          description: `Yield farming deposit — ${poolAddress}`,
        },
      }),
    },
  );

  const { data } = await res.json();
  return { paymentRequest: data, naspipToken: data.token };
}
```

## Gaming e entretenimento

### Compras dentro do jogo

**Cenário**: Um jogo mobile quer aceitar pagamentos com criptomoedas para itens do jogo e recursos premium.

```javascript
async function createInGamePurchase({ itemId, price, playerId, posId }) {
  const auth = await getAccessToken();

  const res = await fetch(
    `https://api.fluxis.us/v1/pos/${posId}/payment-request`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.token}`,
        "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: price.toString(),
        unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        reference_id: `player-${playerId}-item-${itemId}`,
        order: {
          description: `In-game purchase: ${itemId}`,
        },
      }),
    },
  );

  const { data } = await res.json();

  // Opcional: checkout hospedado em vez do token NASPIP bruto
  // POST /v1/pos/:posID/payment-request-checkout

  return {
    paymentRequestId: data.id,
    naspipToken: data.token,
    referenceId: data.reference_id,
  };
}

// No webhook `completed` (ou polling GET /pos/:posID/payment-request/:id):
// conceda o item ao jogador identificado por reference_id
```

## Por que escolher Fluxis API para estes casos de uso?

### 🚀 Desenvolvimento rápido

- **5 minutos até o primeiro pagamento**: Comece imediatamente
- **API REST simples**: Integração fácil com qualquer stack tecnológico
- **Documentação abrangente**: Exemplos e guias claros

### 🔒 Segurança empresarial

- **Instruções de pagamento assinadas**: Tokens NASPIP com payloads verificáveis
- **Autenticidade de webhooks**: Assinaturas HMAC-SHA256 em eventos de saída
- **Credenciais server-side**: Segredos API nunca pertencem a apps client-side

### 📈 Pronto para produção

- **Infraestrutura de produção**: Projetada para alta disponibilidade (confirme os termos de SLA com a equipe comercial do Fluxis)
- **CDN global**: Tempos de resposta rápidos em todo o mundo
- **Autoescaling**: Lida com picos de tráfego automaticamente

### 🛠️ Experiência do desenvolvedor

- **Playground interativo da API**: Teste endpoints diretamente no navegador
- **Guias de integração**: Onboarding de comerciantes passo a passo
- **Suporte especializado**: Entre em contato com [support@fluxis.us](mailto:support@fluxis.us) quando precisar de ajuda

## Primeiros passos

Pronto para implementar qualquer um destes casos de uso? Comece com o [Guia de integração da API](/pt/docs/developers/tutorials/api-integration-guide) ou explore nossa [Referência da API](/api).

### Próximos passos

1. **[Cadastre-se no Fluxis](https://fluxis.us/signup)** - Crie sua conta
2. **[Obtenha sua chave API](https://fluxis.us/dashboard)** - Gere sua primeira chave
3. **[Siga o Guia de integração da API](/pt/docs/developers/tutorials/api-integration-guide)** - Faça sua primeira chamada à API
4. **[Primeiros passos](/pt/docs/introduction/getting-started)** - Início rápido em 6 etapas

---

**Pronto para transformar sua experiência de pagamento?** [Comece a integrar com Fluxis API](https://fluxis.us/signup) hoje!