# API REST da Fluxis

A API REST da Fluxis permite autenticar, gerenciar contas e pontos de venda, criar solicitações de pagamento e receber notificações webhook. Esta página orienta você; a referência interativa está em [/api](/api).

## URLs base

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

Todos os endpoints têm o prefixo `/v1`.

## Autenticação

Cada requisição protegida exige **ambos** os cabeçalhos:

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

Obtenha um token trocando sua chave e segredo de API:

**`POST /v1/auth/token`**

Consulte [Authentication](/api/authentication#authenticate-and-get-access-token) na referência da API.

::::warning
Nunca exponha seu segredo de API em código client-side, navegadores ou apps móveis.
::::

## Recursos principais

| Recurso         | Finalidade                                   | Referência                            |
| ---------------- | ----------------------------------------- | ------------------------------------ |
| **Accounts**     | Contas de comerciante, endereços de liquidação   | [/api — Accounts](/api/account)      |
| **Point of Sale**| Pontos de entrada de pagamento, solicitações de pagamento    | [/api — Point of Sale](/api/point-of-sale) |
| **Webhooks**     | Notificações de eventos em nível de conta         | [/api — Webhooks](/api/webhooks)     |
| **Transactions** | Conciliação e relatórios              | [/api — Transactions](/api/transactions) |
| **NASPIP**       | Ler ou criar tokens NASPIP              | [/api — NASPIP Token](/api/naspip-token) |

## Fluxo de integração típico

1. **Autenticação** — `POST /v1/auth/token`
2. **Descoberta de recursos** — `GET /v1/account`, `GET /v1/pos?page=1&page_size=20`
3. **Criar pagamentos** — `POST /v1/pos/{posID}/payment-request` (ou `payment-request-checkout` para checkout hospedado)
4. **Receber atualizações** — Registre `POST /v1/account/{accountID}/webhook` com `event_type: payment_request`
5. **Conciliar** — `GET /v1/transactions?page=1&page_size=50` ou faça polling de `GET /v1/pos/{posID}/payment-request/{paymentRequestID}`

Passo a passo: [Guia de integração API](/pt/docs/developers/tutorials/api-integration-guide).

## Paginação

Endpoints de listagem usam os parâmetros de consulta **`page`** e **`page_size`** (não offset/limit):

- **POS:** `page` ≥ 1, `page_size` 1–100
- **Transactions:** `page` ≥ 1, `page_size` 5–100
- **Webhook logs:** `page` ≥ 1, `page_size` 5–20

As respostas incluem `{ data, total, page, page_size, total_pages }`.

## Webhooks

Webhooks são registrados por **conta**, não por POS. A Fluxis assina as entregas com HMAC-SHA256.

- [Visão geral de webhooks](/pt/docs/developers/webhooks) — Registro e comportamento de entrega
- [Verificação de assinatura de webhook](/pt/docs/developers/webhook-signature-verification) — JSON canônico e fluxo de teste

Valores `event_type` suportados: `payment_request`, `incoming_transfer`, `refund`.

## Explorar a API

<div
  style={{
    padding: "1.5rem",
    border: "1px solid #00e4a4",
    borderRadius: "8px",
    backgroundColor: "rgba(0, 228, 164, 0.05)",
    marginTop: "1.5rem",
  }}
>
  <h4 style={{ marginTop: 0, color: "#00e4a4" }}>Referência API interativa</h4>
  <p style={{ marginBottom: "1rem" }}>
    Navegue por endpoints, esquemas e teste requisições no playground.
  </p>
  <a href="/api" style={{ color: "#00d086", fontWeight: 600 }}>
    Abrir referência API →
  </a>
</div>

## Guias relacionados

- [Guia de integração API](/pt/docs/developers/tutorials/api-integration-guide)
- [Criar e monitorar solicitações de pagamento](/pt/docs/developers/tutorials/payment-request)
- [Webhooks](/pt/docs/developers/webhooks)
- [Verificação de assinatura de webhook](/pt/docs/developers/webhook-signature-verification)
- [SDKs (em breve)](/pt/docs/developers/sdk)