> ## 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.

# Transfers

> Saque do saldo da empresa (consultado no provedor) para sua conta bancária.

Uma **Transfer** representa um saque do saldo disponível de uma empresa para sua conta bancária. É a etapa final do ciclo financeiro.

## Máquina de Estados

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING

    PENDING --> PROCESSING : Em processamento
    PENDING --> PAID : Efetivada
    PROCESSING --> PAID : Efetivada
    PENDING --> FAILED : Falha
    PROCESSING --> FAILED : Falha
    PENDING --> CANCELED : Cancelada

    PAID --> [*]
    FAILED --> [*]
    CANCELED --> [*]
```

### TransferStatus

Default `PENDING`. `PAID` indica transferência efetivada.

| Status       | Descrição                        |
| ------------ | -------------------------------- |
| `PENDING`    | Criada, aguardando processamento |
| `PROCESSING` | Em processamento no provedor     |
| `PAID`       | Efetivada com sucesso            |
| `FAILED`     | Falhou                           |
| `CANCELED`   | Cancelada                        |

## Pré-requisitos

* A Company deve ter um **BankAccount** cadastrado.
* A Company deve estar apta a receber saldo no provider de billing.
* O saldo disponível (consultado no provedor) deve cobrir o valor solicitado.

## BankAccount

| Campo                | Descrição                                              |
| -------------------- | ------------------------------------------------------ |
| `bankAccountId`      | Identificador único                                    |
| `organizationId`     | Organização da empresa dona da conta                   |
| `companyId`          | Empresa dona da conta                                  |
| `externalProvider`   | Provedor vinculado                                     |
| `externalProviderId` | ID da conta no provedor                                |
| `bankCode`           | Código do banco                                        |
| `bankName`           | Nome do banco                                          |
| `agencyNumber`       | Número da agência                                      |
| `accountNumber`      | Número da conta                                        |
| `accountType`        | `CHECKING` ou `SAVINGS`                                |
| `holderName`         | Nome do titular                                        |
| `holderDocument`     | Documento do titular                                   |
| `holderDocumentType` | `CPF`, `CNPJ` ou `RG`                                  |
| `status`             | `ACTIVE` ou `INACTIVE`                                 |
| `createdBy`          | Usuário que criou o registro, quando aplicável         |
| `createdAt`          | Timestamp da criação                                   |
| `updatedBy`          | Usuário que fez a última atualização, quando aplicável |
| `updatedAt`          | Timestamp da última atualização                        |

<Info>
  Cada empresa possui uma única conta bancária. Alterações de conta bancária são sincronizadas com o provider de billing e com o cadastro da empresa.
</Info>

## Withdrawal Flow

```mermaid theme={null}
sequenceDiagram
    participant Op as Operator/Admin
    participant O as DEVMOB
    participant B as Provider de billing

    Op->>O: Solicita saque
    Note over O: Conta bancária e empresa aptas para saque
    O->>B: Consulta saldo disponível
    Note over O: Valor solicitado coberto pelo saldo
    O->>B: Solicita transferência
    Note over O: Transfer nasce PENDING

    Note over B: Processamento assíncrono
    B->>O: Webhook de resultado
    Note over O: Status da Transfer atualizado
```

### Saldo disponível

O saldo disponível é sempre obtido pelo provider de billing, que é a fonte da verdade para valores liquidados e disponíveis para saque.

<Warning>
  Consultas de saldo devem usar a visão retornada pelo provider de billing.
</Warning>

### Atualização via webhook

A transferência nasce `PENDING`. O resultado chega pelo webhook do provedor (`UPDATE_TRANSFER`), que atualiza o status para `PAID`, `FAILED` ou `CANCELED`.

### Rastreamento externo

O par `externalProvider` + `externalProviderId` identifica a transferência externa e evita duplicidade de processamento.

## Ciclo financeiro completo

```mermaid theme={null}
flowchart LR
    P["Payment PAID"] --> SYNC["Receivables sincronizados"]
    SYNC --> BAL["Saldo no provedor"]
    BAL --> T["Transfer (saque sob demanda)"]
    T --> BA["BankAccount da Company"]
```