# Liquidações e consolidação

Depois que os clientes pagam, a Fluxis processa os fundos por meio de dois pipelines automatizados no backend: **consolidação** (mover ativos dos vaults de pagamento) e **liquidação** (agrupar transações de ledger confirmadas e enviar o líquido para seus endereços configurados).

## Fluxo de alto nível

```mermaid
flowchart LR
    PR[Payment Request] --> V[Vault Address]
    V --> C[Consolidation]
    C --> LT[Ledger Transaction]
    LT --> S[Settlement Batch]
    S --> ADDR[Your Settlement Address]
```

1. **Pagamento** — o cliente envia cripto para um endereço vault por solicitação
2. **Consolidação** — jobs cron agregam pagamentos concluídos dos vaults
3. **Confirmação** — solicitações de pagamento atingem `confirmed`; transações de ledger são criadas
4. **Liquidação** — jobs cron agrupam transações e transferem valores líquidos para seu endereço de liquidação

O monitoramento on-chain roda hoje em **Polygon**, **Base**, **Avalanche** e **Arbitrum**.

## Consolidação

A consolidação agrupa solicitações de pagamento concluídas por endereço vault e ativo, depois move fundos de wallets vault efêmeras para wallets de consolidação controladas pela Fluxis.

### Agendamento cron

| Job | Schedule | Purpose |
| --- | -------- | ------- |
| `CONSOLIDATION_AGGREGATION_JOB` | Every 10 minutes | Agrupar solicitações de pagamento elegíveis por vault + token |
| `CONSOLIDATION_EXECUTION_JOB` | Every 30 minutes | Executar transferências de consolidação pendentes |

Solicitações de pagamento vinculadas a uma consolidação recebem um `consolidation_id` no banco de dados. Este é um passo operacional interno — comerciantes normalmente observam o resultado pelo status da solicitação de pagamento e registros de transações, não diretamente pelos IDs de consolidação.

::::note
Limites mínimos de consolidação se aplicam (a agregação usa um valor mínimo configurável). Saldos pequenos podem permanecer nos vaults até atingir o limite.
:::::

## Liquidação

A liquidação agrupa **transações de ledger confirmadas** por conta, organização e token, depois envia o líquido para endereços de liquidação configurados.

### Agendamento cron

| Job | Schedule | Purpose |
| --- | -------- | ------- |
| `SETTLEMENT_AGGREGATION_JOB` | Hourly at `:00` | Agrupar transações não liquidadas em registros de liquidação |
| `SETTLEMENT_EXECUTION_JOB` | Hourly at `:05` | Processar liquidações pendentes (transferências on-chain) |
| `SETTLEMENT_CONFIRMATION_JOB` | Hourly at `:15` | Confirmar transações de liquidação on-chain |

### Status de liquidação

| Status | Meaning |
| ------ | ------- |
| `created` | Registro de liquidação criado |
| `pending` | Pronto para execução |
| `processing` | Transferência em andamento |
| `completed` | Fundos entregues |
| `failed` | Execução falhou |
| `in_review` | Revisão manual necessária |

Se não houver endereço de liquidação configurado para a conta (ou sua organização pai) na rede necessária, a agregação registra um erro e ignora esse lote.

## Endereços de liquidação

Endereços de liquidação informam à Fluxis **para onde enviar seu líquido** por rede blockchain. Ordem de resolução:

1. **Endereço em nível de conta** para a rede (se configurado)
2. **Endereço em nível de organização** para a rede (padrão de fallback)

### REST API — escopo de organização

Chaves API de organização podem gerenciar endereços diretamente:

| Method | Endpoint | Description |
| ------ | -------- | ----------- |
| GET | `/v1/organization/settlement-addresses` | Listar endereços da organização |
| POST | `/v1/organization/settlement-addresses` | Criar endereço para uma rede |
| PUT | `/v1/organization/settlement-addresses` | Atualizar endereço para uma rede |
| DELETE | `/v1/organization/settlement-addresses?network=polygon` | Remover endereço para uma rede |

Corpo da solicitação (POST/PUT):

```json
{
  "network": "polygon",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "address_tag": null
}
```

### REST API — escopo de conta

```
GET /v1/account/{accountId}/settlement-addresses
```

Retorna endereços de liquidação efetivos para a conta (incluindo fallbacks da organização). Endpoints de criar/atualizar/excluir em nível de conta existem no código, mas **não estão expostos atualmente** na API pública — configure substituições específicas de conta pelo Fluxis Dashboard ou entre em contato com o suporte.

### Campos de resposta

| Field | Description |
| ----- | ----------- |
| `owner` | `organization` ou `account` |
| `settlement_type` | Categoria de taxa (ex.: `payment_net_amount`, `payment_service_fee`) |
| `settlement_address` | Endereço blockchain de destino |
| `address_type` | Identificador de rede (ex.: `polygon`, `base`) |
| `address_tag` | Memo/tag opcional para redes suportadas |

### Dashboard

Endereços de liquidação de conta também podem ser gerenciados no Fluxis Dashboard nas configurações da conta (seção de endereços de liquidação).

## Itens de liquidação

Cada liquidação pode conter múltiplos **items** representando divisões de taxas:

- Valor líquido ao comerciante (`payment_net_amount`)
- Taxas de serviço (`payment_service_fee`)
- Taxas de desenvolvedor (`payment_developer_fee`)
- Taxas de revenue share (`payment_revenue_shared_fee`)

Cada item mapeia para um endereço de liquidação do tipo correspondente quando configurado.

## O que comerciantes devem configurar

1. **Endereços de liquidação da organização** — no mínimo, um endereço por rede que você aceita (Polygon, Base, Avalanche, Arbitrum)
2. **Substituições de conta** (opcional) — destinos por conta quando subcomerciantes precisam de repasses separados
3. **Webhook + reconciliação de transações** — a liquidação é assíncrona; use [Webhook Events](/pt/docs/developers/webhook-events) e [Transactions](/pt/docs/developers/transactions) para rastrear confirmação de pagamento antes de esperar a liquidação

::::warning
A execução de liquidação depende de endereços válidos para cada rede e tipo de item. Endereços ausentes bloqueiam a liquidação dos lotes afetados — configure endereços antes de ir para produção.
:::::

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

| Payment request status | Consolidation | Settlement |
| ---------------------- | ------------- | ---------- |
| `completed` / `overpaid` / `underpaid` | Elegível após processamento | Após `confirmed` + transação de ledger |
| `confirmed` | Pode já estar consolidado | Elegível para agregação de liquidação |
| `expired` / `failed` | Não elegível | Não elegível |

## Documentação relacionada

- [Payment Requests](/pt/docs/key-concepts/payment-request) — ciclo de vida de status até `confirmed`
- [Transactions](/pt/docs/developers/transactions) — registros de ledger que alimentam a liquidação
- [API Integration Guide](/pt/docs/developers/tutorials/api-integration-guide) — Passo 4 configuração de liquidação
- [About Fluxis](/pt/docs/introduction/about) — redes suportadas e escopo de liquidação