# Guia de integração API

Este guia descreve os passos recomendados para integrar com a API da Fluxis, do provisionamento de credenciais à conciliação de transações.

## Visão geral da integração

Uma integração típica com a Fluxis segue estes passos:

1. **Provisionamento de credenciais** — Criar uma chave de API no dashboard (papéis read + write)
2. **Autenticação** — Trocar credenciais por um token de acesso Bearer
3. **Descoberta de recursos** — Recuperar suas contas padrão e pontos de venda padrão (criados no cadastro)
4. **Criar seu POS online** — Configurar o POS para pagamentos online, para gerar várias solicitações de pagamento em paralelo
5. **Configuração de liquidação** — Configurar o endereço cripto onde os ativos cobrados serão entregues. Pode ser feito no dashboard ou via API.
6. **Criação de solicitações de pagamento** — Criar uma solicitação por tentativa de checkout
7. **Monitorar status de pagamento** — [Webhooks](/pt/docs/developers/webhook-events) (push) ou polling (pull) — escolha um ou ambos
8. **Conciliação** — Consultar transações periodicamente para capturar eventos perdidos

<div className="my-6">
  <img
    src="/images/fluxis-payment-flow-light.svg"
    alt="Fluxis API payment and collection flow"
    className="block w-full max-w-full dark:hidden"
  />
  <img
    src="/images/fluxis-payment-flow-dark.svg"
    alt="Fluxis API payment and collection flow"
    className="hidden w-full max-w-full dark:block"
  />
</div>

## Antes de começar

### Ambientes

| Ambiente | Host                       |
| ----------- | -------------------------- |
| Staging     | `https://api.stgfluxis.us` |
| Production  | `https://api.fluxis.us`    |

::::note
Credenciais de produção serão geradas após sua integração em staging estar completa e aprovada pela Fluxis.
::::

### Cabeçalhos obrigatórios

Todos os endpoints protegidos da Fluxis exigem **ambos** os cabeçalhos:

- `Authorization: Bearer <access_token>`
- `x-fluxis-api-key: <your_api_key>`

::::warning
Trate seu API Secret como credencial sensível. Nunca o exponha em código client-side, navegadores ou apps móveis.
::::

---

## Etapa 1 — Provisionamento de credenciais

Antes de qualquer chamada à API, crie credenciais de API no Dashboard da Fluxis.

::::info
Novo na Fluxis? Conclua o [Cadastro de comerciante](/pt/docs/merchant-integration/sign-up) (criação de conta + 2FA) antes desta etapa.
::::

### Criar uma chave de API no dashboard

1. Faça login no Dashboard da Fluxis ([staging](https://dashboard.stgfluxis.us) ou [production](https://dashboard.fluxis.us)).
2. Abra **Developers → API Keys** (ou navegue até `/app/api-keys`).
3. Clique em **Create** (ou equivalente) para adicionar uma nova chave.
4. Atribua os papéis **`read`** e **`write`** para listar recursos e criar solicitações de pagamento.
5. Conclua o **desafio 2FA** quando solicitado ([Autenticação de dois fatores](/pt/docs/developers/two-factor-auth) deve estar cadastrada antes).
6. Copie o **API Secret** imediatamente — é exibido **uma vez** e não pode ser recuperado depois.

Você receberá:

- **API Key ID** (ex.: `fxs.stg.<uuid>` para staging, `fxs.prd.<uuid>` para production)
- **API Secret** — armazene em gerenciador de segredos ou variáveis de ambiente

Consulte [Credenciais de API](/pt/docs/developers/api-credentials) para papéis, lista de IP e ciclo de vida.

::::tip
Se você opera várias marcas ou regiões, alinhe cedo com a Fluxis a estrutura de **Accounts** e **Points of Sale**. Isso simplifica relatórios e conciliação.
::::

---

## Etapa 2 — Autenticação

Troque suas credenciais por um token de acesso que deve ser incluído em todas as requisições API subsequentes.

**Endpoint:** `POST /v1/auth/token`

Consulte o formato completo de requisição/resposta em nossa [Referência API - Authentication](/api/authentication#authenticate-and-get-access-token).

### Uso do token

Inclua o token de acesso em todas as requisições protegidas:

```
Authorization: Bearer <access_token>
x-fluxis-api-key: <your_api_key>
```

### Ciclo de vida do token

- **Expiração**: Tokens de acesso expiram (consulte o campo `expired_at` na resposta)
- **Renovação**: Implemente um mecanismo para renovar o token antes da expiração
- **Rotação**: Rotacione sua API Key/Secret imediatamente se suspeitar de comprometimento

---

## Etapa 3 — Descoberta de recursos

Após autenticar, recupere informações sobre suas contas e pontos de venda padrão, ou crie novos.

### 3.1 Recuperar contas

Contas representam as contas financeiras do comerciante na Fluxis.

**Endpoint:** `GET /v1/account`

Consulte o formato completo da resposta em nossa [Referência API - Accounts](/api/accounts#list-accounts).

### 3.2 Recuperar pontos de venda

Pontos de Venda (POS) representam seus pontos de entrada de pagamento — locais físicos ou virtuais onde você aceita pagamentos. Você precisará do ID do POS ao criar solicitações de pagamento.

**Endpoint:** `GET /v1/pos?page=1&page_size=20`

Parâmetros obrigatórios: `page` (≥ 1) e `page_size` (1–100). Chaves de organização podem filtrar com `account_id`.

Consulte o formato completo da resposta em nossa [Referência API — Point of Sale](/api/point-of-sale#get-all-point-of-sales).

::::tip
Saiba mais sobre o conceito de POS: [Ponto de Venda](/pt/docs/key-concepts/point-of-sale).
::::

---

## Etapa 4 — Configuração de liquidação

Antes de aceitar pagamentos, configure para onde os ativos cripto cobrados serão entregues.

Todos os ativos cobrados de uma rede específica (ex.: USDT, USDC ou outros tokens na Polygon) serão entregues ao endereço de liquidação configurado para essa rede.

::::note
Por segurança, a configuração de endereços de liquidação é feita manualmente pela equipe Fluxis. Entre em contato com seu representante para configurar endereços em staging e production.
::::

---

## Etapa 5 — Criação de solicitações de pagamento

Crie uma solicitação de pagamento para cada tentativa de checkout do cliente. A resposta inclui um **token NASPIP** com todas as informações de pagamento.

**Endpoint:** `POST /v1/pos/:posID/payment-request`

Campos principais:

- `amount` — Valor do pagamento (ex.: `"49.99"`)
- `unique_asset_id` — Ativo/rede alvo ([saiba mais sobre UAIs](/pt/docs/key-concepts/uai))
- `reference_id` — Seu ID interno de pedido para conciliação
- `order` — Dados estruturados opcionais do pedido para recibos/UX

Consulte o formato completo em nossa [Referência API - Payment Request](/api/point-of-sale#create-point-of-sale-payment-request).

### 5.1 Exibir o token NASPIP

O `token` retornado na resposta é um token NASPIP que você apresenta ao cliente.

**Checkout desktop:**
Exiba o token NASPIP como QR code para o usuário escanear com o app de carteira.

**Checkout mobile:**
Exiba um botão "Pagar com [nome do app de carteira]" que abre o app via deep link:

```
[wallet app deeplink url]?<custom_query_params>&naspip_token=<NASPIP_TOKEN>
```

::::tip
Saiba mais sobre NASPIP: [Token NASPIP](/pt/docs/key-concepts/naspip/introduction).

Para lista mantida de apps de carteira, templates de deep link e logos, consulte [Registro de apps compatíveis](/pt/docs/developers/compatible-apps).
::::

### 5.2 Hosted checkout (opcional)

Para uma página de pagamento hospedada pela Fluxis em vez de incorporar o token NASPIP você mesmo:

**Endpoint:** `POST /v1/pos/:posID/payment-request-checkout`

A resposta inclui `token` e `checkout_url` para redirecionar clientes diretamente. A página hosted consulta `GET /public/checkout/:sessionId` e, ao terminar, usa `return_url`: em um ponto de venda genérico é `config.return_url` do POS; em uma sessão Tiendanube é o callback por tentativa (`success`, `failure` ou `cancel`) gravado no Process Payment, não a URL do POS.

Consulte [API Reference — Create payment request checkout](/api/point-of-sale#create-payment-request-checkout).

---

## Etapa 6 — Escolher como monitorar pagamentos

Após criar uma solicitação de pagamento, você precisa saber quando o cliente paga. Escolha **uma ou ambas** estratégias:

| Estratégia                | Entrega                           | Ideal para                                  | Requisitos                                                                                     |
| ----------------------- | ---------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Webhooks (Opção A)** | Push — Fluxis faz POST no seu servidor | Integrações em produção, UX em tempo real     | Endpoint HTTPS público, [verificação de assinatura](/pt/docs/developers/webhook-signature-verification) |
| **Polling (Opção B)**  | Pull — seu servidor consulta a Fluxis  | Backends simples, dev local, sem URL pública | Token Bearer + API key válidos; polling a cada ~3 segundos                                              |

::::tip
Muitas equipes usam **webhooks como principal** e **polling como fallback** quando um webhook é perdido ou o endpoint ficou temporariamente fora.
::::

### Opção A — Notificações webhook

Webhooks são a forma recomendada de receber atualizações de status em tempo real.

#### A.1 Configurar seu endpoint webhook

Primeiro, garanta um endpoint HTTPS publicamente acessível pronto para receber POST da Fluxis.

Depois registre um webhook na **conta** vinculada ao seu POS (use o `account_id` do POS ou da lista de contas):

**Endpoint:** `POST /v1/account/{accountID}/webhook`

```json
{
  "url": "https://your-server.com/webhooks/fluxis",
  "event_type": "payment_request"
}
```

A Fluxis retorna um `secret` **uma vez** na criação — armazene com segurança para [verificação de assinatura](/pt/docs/developers/webhook-signature-verification).

Consulte [API Reference — Create webhook](/api/webhooks#create-webhook).

#### A.2 Eventos webhook

A Fluxis envia webhooks `payment_request` quando o status se torna:

| Status       | Descrição                                         | Webhook entregue   |
| ------------ | --------------------------------------------------- | ------------------- |
| `processing` | Pagamento detectado, aguardando confirmações blockchain | Sim                 |
| `completed`  | Pagamento confirmado — atenda o pedido               | Sim                 |
| `underpaid`  | Cliente enviou menos que o valor solicitado        | Sim                 |
| `overpaid`   | Cliente enviou mais que o valor solicitado        | Sim                 |
| `expired`    | Sem pagamento no prazo                                  | Não — use polling   |
| `failed`     | Erro inesperado de processamento                         | Não — polling / suporte |

::::note
Os estados `underpaid` e `overpaid` são casos extremos que podem indicar configuração inadequada no app de carteira, já que tokens NASPIP contêm o valor esperado.
Para verificação de assinatura, consulte [Verificação de assinatura de webhook](/pt/docs/developers/webhook-signature-verification).
::::

#### A.3 Tratar webhooks

Ao receber uma notificação webhook:

1. **Verificar autenticidade** — Valide a assinatura HMAC sobre o corpo parseado completo `{ "data": … }` com o segredo da criação — consulte [Verificação de assinatura de webhook](/pt/docs/developers/webhook-signature-verification)
2. **Processar o status** — Atualize o status interno do pedido e notifique o cliente
3. **Confirmar recebimento** — Retorne HTTP `200 OK`

::::warning
Seu endpoint deve responder rápido (< 2 segundos). Enfileire processamento pesado em segundo plano. Falha em confirmar pode fazer a Fluxis reenviar a notificação.
::::

#### A.4 Idempotência

Você pode receber eventos webhook duplicados. Garanta que o handler seja **idempotente** — processar o mesmo evento várias vezes deve produzir o mesmo resultado.

#### A.5 Testar seu handler

Após o registro, dispare uma entrega de amostra assinada:

**Endpoint:** `POST /v1/account/{accountID}/webhook/{webhookID}/test`

A Fluxis faz POST de um payload `payment_request_status_update` com o mesmo caminho de assinatura da produção. Verifique a assinatura e retorne HTTP `200`. Consulte [Verificação de assinatura de webhook](/pt/docs/developers/webhook-signature-verification) para regras de JSON canônico e exemplo prático.

Você também pode registrar webhooks no dashboard em **Developers → Webhooks**. Consulte [Webhooks](/pt/docs/developers/webhooks) para opções API e dashboard.

---

### Opção B — Polling

Se não tiver endpoint HTTPS público — ou preferir uma primeira integração mais simples — **faça polling** do status da solicitação em intervalo fixo (por exemplo, a cada **3 segundos**) até status terminal.

**Endpoint:** `GET /v1/pos/:posID/payment-request/:paymentRequestID`

Cabeçalhos obrigatórios: `Authorization: Bearer <token>` e `x-fluxis-api-key: <your_api_key>`.

#### Padrão de polling recomendado

1. Após criar a solicitação, registre `paymentRequestID` e `posID`.
2. Faça polling a cada **~3 segundos** enquanto o status for `created`, `pending`, `confirmed` ou `processing`.
3. **Pare o polling** quando o status for terminal: `completed`, `expired`, `underpaid`, `overpaid` ou `failed`.
4. Em `completed`, atenda o pedido; em `expired`, ofereça criar nova solicitação.

::::warning
Solicitações de pagamento expiram após cerca de **8 minutos**. Evite polling mais rápido que uma vez por segundo — 3 segundos é um padrão razoável para UX de checkout.
::::

**Exemplo (curl):**

```bash
curl "https://api.stgfluxis.us/v1/pos/${POS_ID}/payment-request/${PAYMENT_REQUEST_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-fluxis-api-key: ${API_KEY}"
```

**Exemplo (loop Node.js):**

```javascript
const TERMINAL = new Set([
  "completed",
  "expired",
  "underpaid",
  "overpaid",
  "failed",
]);
const POLL_MS = 3000;

async function waitForPayment(posId, paymentRequestId) {
  while (true) {
    const res = await fetch(
      `${API_BASE}/v1/pos/${posId}/payment-request/${paymentRequestId}`,
      {
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "x-fluxis-api-key": apiKey,
        },
      },
    );
    const { data } = await res.json();
    if (TERMINAL.has(data.status)) return data;
    await new Promise((r) => setTimeout(r, POLL_MS));
  }
}
```

Consulte o formato completo em nossa [Referência API — Get payment request](/api/point-of-sale#get-payment-request).

::::note
Status `expired` e `failed` **não** disparam webhooks — polling (ou checagens manuais) é necessário para esses resultados.
::::

---

## Etapa 7 — Conciliação

Mesmo com webhooks ou polling no checkout, execute **conciliação periódica** para garantir que nenhum pagamento foi perdido (downtime, rede ou bugs no handler).

### Consultar uma solicitação específica

Se não recebeu webhook (ou o sistema ficou fora), busque o status diretamente:

**Endpoint:** `GET /v1/pos/:posID/payment-request/:paymentRequestID`

### Listar transações para conciliação

Para conciliação em lote, consulte o endpoint de transações:

**Endpoint:** `GET /v1/transactions?page=1&page_size=50`

Parâmetros obrigatórios: `page` (≥ 1) e `page_size` (5–100).

Filtros opcionais:

- `accountID` — Filtrar por conta (apenas chaves de API em nível de organização)

A resposta é paginada: `{ data, total, page, page_size, total_pages }`.

::::tip
Padrão comum: listar periodicamente transações `completed` e comparar com pedidos internos por ID de referência, valor e timestamp.
::::

---

## Ciclo de vida da solicitação de pagamento

As solicitações passam pelos seguintes estados:

| Estado                               | Descrição                              | Ação do comerciante                              |
| ----------------------------------- | ---------------------------------------- | -------------------------------------------- |
| `pending`                           | Checkout criado, moeda não selecionada  | Aguardar ou exibir hosted checkout              |
| `created`                           | Endereço atribuído, aguardando pagamento       | Exibir QR/link ao cliente                  |
| `confirmed`                         | Etapa interna de confirmação               | Geralmente sem ação do comerciante                   |
| `processing`                        | Pagamento detectado, aguardando confirmações | Continuar aguardando — não entregar ainda             |
| `completed`                         | Pagamento confirmado                        | Atender o pedido                            |
| `expired`                           | Sem pagamento no prazo              | Oferecer nova solicitação ao cliente |
| `underpaid` / `overpaid` / `failed` | Casos extremos                               | Contatar suporte Fluxis                       |

Saiba mais: [Fluxos de pagamento - Caminho feliz](/pt/docs/payment-flows/std-flow) e [Fluxos de pagamento - Casos extremos](/pt/docs/payment-flows/edge-cases).

---

## Checklist para produção

Antes de ir para produção, verifique:

- [ ] Você obtém e renova tokens Bearer via `POST /v1/auth/token`
- [ ] Você lista seu POS e seleciona o `posID` correto
- [ ] Seu checkout cria uma solicitação por tentativa
- [ ] Você exibe o token NASPIP corretamente (QR code ou deep link)
- [ ] Você tem estratégia de monitoramento: webhooks **e/ou** polling (~3 s até status terminal)
- [ ] Se usa webhooks: registrado via `POST /v1/account/{accountID}/webhook` com `event_type: payment_request`
- [ ] Segredo de webhook armazenado da resposta de criação e usado para [verificação de assinatura](/pt/docs/developers/webhook-signature-verification)
- [ ] Entrega de teste via `POST /v1/account/{accountID}/webhook/{webhookID}/test` verifica e retorna HTTP 200
- [ ] Seu endpoint webhook é publicamente acessível e responde HTTP 200
- [ ] Seu handler de webhook é idempotente
- [ ] Se usa polling: `GET /v1/pos/:posID/payment-request/:paymentRequestID` para em status terminal
- [ ] Você tem processo de conciliação periódica (`GET /v1/transactions`)

---

## Precisa de ajuda?

Se tiver dúvidas sobre onboarding, credenciais ou prontidão para produção, entre em contato em [support@fluxis.us](mailto:support@fluxis.us).