# Transações

A API de Transações retorna registros contábeis criados após a confirmação de pagamentos bem-sucedidos. Use-a para conciliar pagamentos, auditar saldos e respaldar integrações baseadas em webhooks.

## Visão geral

Cada solicitação de pagamento confirmada produz um registro de transação. Transações incluem valores brutos e líquidos, metadados de ativo e rede, endereços de origem e destino e hashes de transação on-chain opcionais.

Transações estão no escopo da entidade autenticada:

- **Chaves de API em nível de conta** — transações apenas dessa conta
- **Chaves de API em nível de organização** — todas as transações da organização, ou uma conta específica quando `accountID` é informado

## Autenticação

Todas as requisições exigem ambos os cabeçalhos:

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

## Listar transações

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

### Parâmetros de consulta

| Parâmetro | Obrigatório | Descrição |
| --------- | -------- | ----------- |
| `page` | Sim | Número da página (mínimo `1`) |
| `page_size` | Sim | Itens por página (`5`–`100`) |
| `accountID` | Não | Filtrar por conta específica (apenas chaves de organização). Deve pertencer à sua organização |

::::warning
**Divergência do Swagger:** A referência OpenAPI pode documentar parâmetros `limit` e `offset` e uma resposta em array simples. O handler em produção usa **`page` e `page_size`** e retorna um envelope paginado com `data`, `total`, `page`, `page_size` e `total_pages`. Siga esta página e o comportamento do handler — não tipos swagger desatualizados.
::::

### Exemplo

```bash
curl "https://api.fluxis.us/v1/transactions?page=1&page_size=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"
```

Para chaves de organização limitadas a uma conta:

```bash
curl "https://api.fluxis.us/v1/transactions?page=1&page_size=50&accountID=c87464d1-c54a-48c3-80c9-bee4fddf593d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"
```

### Formato da resposta

```json
{
  "data": {
    "data": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "payment_in",
        "status": "completed",
        "gross_amount": "100.00",
        "net_amount": "97.50",
        "expected_amount": "100.00",
        "currency": "USDC",
        "network": "polygon",
        "unique_asset_id": "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "from_type": "wallet",
        "to": "0x1234567890abcdef1234567890abcdef12345678",
        "to_type": "vault",
        "financial_provider": "fluxis",
        "transaction_hash": "0xabcdef...",
        "created_at": "2026-05-21T12:00:00Z",
        "updated_at": "2026-05-21T12:05:00Z"
      }
    ],
    "total": 150,
    "page": 1,
    "page_size": 50,
    "total_pages": 3
  }
}
```

::::note
Campos opcionais como `account_external_id`, `unique_asset_id`, `network` e `transaction_hash` usam `omitempty` e podem estar ausentes conforme o tipo de transação e a etapa de processamento.
::::

## Tipos de transação

| Tipo | Descrição |
| ---- | ----------- |
| `payment_in` | Pagamento recebido do cliente |
| `payment_out` | Pagamento de saída |
| `deposit` | Depósito |
| `withdraw` | Saque |
| `refund` | Reembolso |
| `adjustment` | Ajuste manual |
| `swap` | Troca de ativos |
| `dry_run` | Registro de teste / pré-visualização |

A maioria das integrações de comerciantes interage principalmente com registros `payment_in` criados quando solicitações de pagamento atingem `confirmed`.

## Status de transação

| Status | Descrição |
| ------ | ----------- |
| `preview` | Estado de pré-visualização |
| `pending` | Aguardando processamento |
| `created` | Registro criado |
| `processing` | Em andamento |
| `completed` | Concluído com sucesso |
| `failed` | Falhou |
| `error` | Estado de erro |
| `expired` | Expirado |

## Relação com solicitações de pagamento

```mermaid
sequenceDiagram
    participant PR as Payment Request
    participant WH as Webhook
    participant TX as Transaction

    PR->>PR: processing → completed / underpaid / overpaid
    PR->>WH: payment_request_status_update
    PR->>PR: confirmed (ledger step)
    PR->>TX: payment_in transaction created
```

1. Webhooks disparam em `processing`, `completed`, `underpaid` e `overpaid` — consulte [Eventos de webhook](/pt/docs/developers/webhook-events).
2. Após a confirmação, uma transação contábil aparece em `GET /v1/transactions`.
3. Faça polling de transações como fallback se um webhook for perdido.

## Padrão de conciliação

::::note
Combine webhooks (tempo real) com polling periódico de transações (rede de segurança). Faça o match por `payment_request_id` via seu `external_reference_id` ou correlacionando valores, timestamps e hashes de transação.
::::

Fluxo recomendado:

1. Armazene IDs de solicitação de pagamento ao criar sessões de checkout
2. Atualize o status do pedido a partir de webhooks `payment_request`
3. Diariamente (ou sob demanda), percorra `GET /v1/transactions` e concilie lacunas

## Documentação relacionada

- [Solicitações de pagamento](/pt/docs/key-concepts/payment-request) — ciclo de vida de status
- [Eventos de webhook](/pt/docs/developers/webhook-events) — atualizações de status em tempo real
- [Verificação de assinatura de webhook](/pt/docs/developers/webhook-signature-verification) — verificação HMAC para entregas de webhook
- [Liquidações e consolidação](/pt/docs/key-concepts/settlements-and-consolidation) — como os fundos se movem após a confirmação
- [Guia de integração API](/pt/docs/developers/tutorials/api-integration-guide) — Etapa 7 conciliação