> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recebíveis

> O que cada venda paga vai depositar na carteira — por recebedor e por parcela, com data prevista, valores e o caminho até liquidar.

O **recebível** (`rcv_`) é a fatia de uma venda paga que vai cair na carteira de um recebedor
(`rec_`) numa data prevista. Cada pagamento confirmado gera **um recebível por recebedor do split e
por parcela**: uma venda de R\$ 300 em 3x com um único recebedor gera três; com dois recebedores no
split, seis. Pix, boleto e venda à vista geram um por recebedor, e toda venda tem ao menos o
recebedor da sua própria conta.

Até o adquirente confirmar a parcela, o recebível é **previsão**: nasce com `feeAmount` zero,
`netAmount` igual ao bruto e uma data que ainda pode mudar. Somar o líquido de recebíveis
`projected` como se fosse dinheiro certo é o erro mais comum — o valor só é definitivo a partir de
`confirmed`, e só está na carteira em `liquidated`.

<Info>
  Todas as rotas exigem o header `x-api-key` (sua chave de sandbox). Veja
  [Autenticação](/pt-BR/autenticacao). Os exemplos nas páginas de cada endpoint usam a base URL de
  sandbox `https://api.sandbox.z2pay.com/v1`.
</Info>

***

## Endpoints

Cada endpoint tem sua própria página, com os filtros aceitos, exemplos e o playground para testar.
Não há `POST`: o recebível nasce da venda, muda pelo que o adquirente informa e sai do futuro ao
liquidar.

| Método | Rota               | Descrição                                                                     |
| ------ | ------------------ | ----------------------------------------------------------------------------- |
| `GET`  | `/receivables`     | [Lista paginada de recebíveis da conta, com filtros](/pt-BR/receivables/list) |
| `GET`  | `/receivables/:id` | [Busca um recebível pelo ID](/pt-BR/receivables/get)                          |

***

## Status do recebível

Você nunca define o status: ele avança com o que o adquirente confirma, com o calendário e com a
liquidação na carteira. O caminho normal é `projected → confirmed → paid → liquidated` no cartão, e
`projected → confirmed → liquidated` em Pix e boleto, que não passam por `paid`.

| Status        | O que significa                        | Quando acontece                                                                                                                                                          |
| ------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `projected`   | Previsão feita na venda                | O pagamento foi confirmado; `expectedAt` segue o prazo de liberação da sua conta para o método, parcela a parcela — veja [Liquidação](/pt-BR/valores/liquidacao)         |
| `confirmed`   | O adquirente confirmou a parcela       | `grossAmount`, `feeAmount`, `netAmount`, `paymentAt` e `cardBrand` passam a ser os reais; falta só chegar a data                                                         |
| `paid`        | O adquirente pagou a parcela de cartão | Transitório: em até um minuto vira `liquidated`                                                                                                                          |
| `liquidated`  | O valor caiu na carteira               | `liquidatedAt` preenchida e `walletTransactionId` apontando o lançamento do extrato; sem `walletTransactionId`, o valor foi pago fora da carteira, por cessão a um fundo |
| `anticipated` | O valor foi adiantado antes do prazo   | Antecipação de recebíveis: `anticipationFeeAmount` é o custo, e o recebível segue para `paid` e `liquidated` quando o adquirente confirmar                               |
| `cancelled`   | Não será recebido                      | Reembolso ou chargeback total antes de liquidar, ou o adquirente cancelou a parcela                                                                                      |

### Estornos e chargebacks

Um reembolso ou um chargeback não apaga o histórico: ele muda o recebível da venda ou cria um
recebível de sinal contrário. Três regras explicam o que você vê.

<Note>
  **`type` diz a natureza e `flow` diz o sinal.** `credit` é a parcela da venda; `refund` e
  `chargeback` são débitos; `refund_reversal` e `chargeback_refund` devolvem um débito, como num
  chargeback ganho. Os valores são sempre positivos — `flow: "credit"` soma na carteira e
  `flow: "debit"` subtrai. Para uma prévia do que ainda vai cair, some `netAmount −
      anticipationFeeAmount` com o sinal do `flow` nos status `projected`, `confirmed` e `paid`.
</Note>

<Note>
  **Estorno total antes da liquidação cancela; depois dela, debita.** Se a venda é reembolsada ou
  contestada por inteiro enquanto o recebível ainda não caiu na carteira, ele vira `cancelled`. Se
  o dinheiro já caiu, nasce um recebível `refund` ou `chargeback` que liquida na data prevista e
  debita a carteira.
</Note>

<Note>
  **Reembolso parcial sempre gera débito.** Devolver parte de uma parcela não cancela a parcela:
  o recebível `credit` continua, e um recebível `refund` com o valor devolvido entra ao lado dele
  — mesmo antes da liquidação.
</Note>

***

## Veja também

<CardGroup cols={2}>
  <Card title="Carteiras" icon="wallet" href="/pt-BR/wallets">
    O saldo do recebedor e o extrato onde o recebível liquidado aparece como lançamento.
  </Card>

  <Card title="Liquidação" icon="calendar-clock" href="/pt-BR/valores/liquidacao">
    Os prazos de liberação por método de pagamento que definem `expectedAt`.
  </Card>

  <Card title="Transações" icon="receipt" href="/pt-BR/transactions">
    A venda de origem: filtre os recebíveis por `transactionId` para ver o cronograma dela.
  </Card>

  <Card title="Reembolsos" icon="rotate-ccw" href="/pt-BR/refunds">
    O estorno que cancela ou debita um recebível.
  </Card>
</CardGroup>