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

# Receivables

> Receivable: registros de conciliação sincronizados do provider de billing.

O **Receivable** registra os valores a receber associados a um pagamento. O DEVMOB usa esses registros para conciliar o que foi reportado pelo provider de billing com os pagamentos e pedidos internos.

## Campos

| Campo                | Tipo             | Descrição                                              |
| -------------------- | ---------------- | ------------------------------------------------------ |
| `receivableId`       | UUID             | Identificador único                                    |
| `paymentId`          | UUID             | Pagamento que originou o recebível                     |
| `organizationId`     | UUID             | Organização da empresa beneficiária                    |
| `companyId`          | UUID             | Empresa beneficiária                                   |
| `externalProvider`   | string           | Provedor de pagamento                                  |
| `externalProviderId` | string           | ID do recebível no provedor                            |
| `amount`             | integer          | Valor líquido do recebível em centavos                 |
| `gatewayFeeRate`     | integer          | Rate do gateway inferido (bps)                         |
| `gatewayFee`         | integer          | Valor do gateway reportado pelo provedor (centavos)    |
| `status`             | ReceivableStatus | Status do recebível                                    |
| `createdBy`          | UUID?            | Usuário que criou o registro, quando aplicável         |
| `createdAt`          | datetime         | Data de criação                                        |
| `updatedBy`          | UUID?            | Usuário que fez a última atualização, quando aplicável |
| `updatedAt`          | datetime         | Data de última atualização                             |

<Info>
  O saque consulta o saldo diretamente no provedor; recebíveis e transferências não possuem vínculo individual.
</Info>

## ReceivableStatus

O status é copiado do provedor a cada sincronização (default `WAITING_FUNDS`):

| Status          | Descrição                         |
| --------------- | --------------------------------- |
| `WAITING_FUNDS` | Aguardando liquidação no provedor |
| `PREPAID`       | Antecipado                        |
| `PAID`          | Liquidado/pago                    |
| `CANCELLED`     | Cancelado                         |

## Sincronização de Recebíveis

O DEVMOB sincroniza recebíveis em dois momentos:

* Quando uma cobrança é confirmada pelo provider de billing.
* Pela rotina periódica de [Receivables Backfill](/scheduler/receivables-backfill), para evitar drift entre DEVMOB e provider.

```mermaid theme={null}
flowchart TD
    TRIGGER["Webhook ou rotina periódica"] --> LIST["Recebíveis do provider"]
    LIST --> MATCH["Localiza Payment por identificadores externos"]
    MATCH --> OWNER["Resolve empresa beneficiária"]
    OWNER --> UP["Receivables atualizados"]
```

Cada recebível é registrado de forma idempotente pelo par `externalProvider` + `externalProviderId`. Se o provider reenviar o mesmo recebível com status ou valores atualizados, o registro é atualizado.

## Gateway fee

O provider reporta o valor do gateway fee junto dos recebíveis. O DEVMOB armazena:

* `gatewayFee` — valor absoluto em centavos.
* `gatewayFeeRate` — rate derivado a partir do valor reportado e do amount do recebível.

## Ciclo de Vida

```mermaid theme={null}
flowchart LR
    SRC["Webhook / Backfill"] --> SYNC["Sincronização de recebíveis"]
    SYNC --> R["Receivable (status do provedor)"]
    R -->|"re-sync"| R2["Status atualizado<br/>(WAITING_FUNDS → PAID / CANCELLED)"]
```

<Info>
  O status efetivo de cada recebível é copiado do provedor a cada sincronização.
</Info>

## Relação com Transfer

Os recebíveis compõem a contabilidade do que a empresa tem a receber, mas o **saldo disponível para saque é consultado diretamente no provedor**. O saque é feito via [Transfer](/domain/billing/transfers).