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

# Financeiro

> Leia o saldo e o extrato da empresa, entenda as taxas, cadastre a conta de recebimento e peça um saque com chave de idempotência.

Catorze operações cobrem o dinheiro da empresa: quanto tem, de onde veio, quanto a Ephra cobra, para onde vai e o que está retido. Este guia percorre um dia típico: conferir saldo, olhar o extrato, entender as taxas e sacar.

<Info>
  Tudo em centavos. `83470` é R\$ 834,70.
</Info>

## 1. Confira o saldo

```bash theme={null}
curl -s https://api.ephra.io/v1/balance \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": {
    "available": 83470,
    "receivable": 0,
    "reserved": 0
  }
}
```

| Campo        | Significado                                                               |
| ------------ | ------------------------------------------------------------------------- |
| `available`  | Liberado, sacável agora                                                   |
| `receivable` | Vendido e ainda em carência — libera nos próximos dias                    |
| `reserved`   | Retido como reserva financeira, conforme a política de risco da sua conta |

Só `available` entra num saque. `receivable` é o que a [antecipação](#5-antecipe-o-que-ainda-nao-liberou) pode adiantar.

## 2. Leia o extrato

Cada linha é um lançamento, com o saldo resultante já calculado:

```bash theme={null}
curl -s "https://api.ephra.io/v1/balance-operations?page=1&pageSize=5" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "92",
      "sourceId": "cmtxyt3710000eag1smxe72ee",
      "sourceType": "transaction",
      "type": "refund",
      "direction": "debit",
      "amount": 49900,
      "balance": 96460,
      "note": "Reembolso Venda #cmtxyt3710000eag1smxe72ee",
      "isCashback": false,
      "createdAt": "2026-09-12T05:50:09.003Z",
      "updatedAt": "2026-09-12T05:50:09.005Z"
    },
    {
      "id": "91",
      "sourceId": "cmtxytygq0000ueg118ueahet",
      "sourceType": "transfer",
      "type": "fee",
      "direction": "debit",
      "amount": 350,
      "balance": 146360,
      "note": "Taxa de Saque #cmtxytygq0000ueg118ueahet (reserva)",
      "isCashback": false,
      "createdAt": "2026-09-12T05:49:46.306Z",
      "updatedAt": "2026-09-12T05:49:46.307Z"
    },
    {
      "id": "86",
      "sourceId": "live-demo-venda-2",
      "sourceType": "transaction",
      "type": "sell",
      "direction": "credit",
      "amount": 129900,
      "balance": 178205,
      "note": "Venda da Mentoria de Copywriting",
      "isCashback": false,
      "createdAt": "2026-09-11T05:49:19.845Z",
      "updatedAt": "2026-09-12T05:49:19.845Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 5, "total": 7, "totalPages": 2 }
}
```

`sourceId` aponta para a venda ou o saque que originou a linha, e `sourceType` diz qual dos dois. É por esse par que você reconcilia o extrato da Ephra com o seu ERP.

`direction` só aceita `credit` ou `debit`. Mandar `in` ou `out` responde `422` com a lista de valores válidos.

Para fechar o mês sem somar linha por linha, peça os totais agrupados:

```bash theme={null}
curl -s https://api.ephra.io/v1/balance-operations/by-type \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": [
    { "type": "fee", "amount": 1945 },
    { "type": "reserve", "amount": 6495 },
    { "type": "refund", "amount": 49900 },
    { "type": "sell", "amount": 179800 }
  ],
  "pagination": { "page": 1, "pageSize": 10, "total": 4, "totalPages": 1 }
}
```

## 3. Entenda o que a Ephra cobra

```bash theme={null}
curl -s https://api.ephra.io/v1/fees \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": {
    "pix": {
      "receiveDays": 0,
      "limit": 0,
      "feeFixed": 99,
      "feePercentage": 299,
      "reserve": { "enabled": false, "days": 0, "percentage": 0 }
    },
    "card": {
      "receiveDays": 0,
      "limit": 0,
      "feeFixed": 99,
      "feePercentage": 499,
      "reserve": { "enabled": false, "days": 0, "percentage": 0 },
      "installmentFees": []
    },
    "boleto": { "receiveDays": 0, "limit": 0, "feeFixed": 299, "feePercentage": 0 },
    "withdrawal": { "feeFixed": 350, "feePercentage": 0 },
    "highTicket": null
  }
}
```

<Warning>
  `feePercentage` é **base 100**: `299` significa 2,99%, não 299%. `feeFixed` é centavos: `99` é R$ 0,99. Uma venda de R$ 499 no Pix custa `49900 * 0.0299 + 99 = 1591` centavos.
</Warning>

`receiveDays` é a carência em dias até o valor sair de `receivable` e virar `available`. `reserve.percentage` é quanto de cada venda fica retido, e por `reserve.days` dias.

## 4. Cadastre para onde o dinheiro vai

```bash theme={null}
curl -s https://api.ephra.io/v1/bank-account \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": {
    "id": "34",
    "type": "CURRENT",
    "bankCode": "341",
    "agency": "1234",
    "number": "56789",
    "digit": "0",
    "pixKey": "11111111000191",
    "createdAt": "2026-09-12T05:49:19.846Z",
    "updatedAt": "2026-09-12T05:49:19.846Z"
  }
}
```

Para cadastrar ou trocar, `POST /v1/bank-account` grava por cima:

```bash theme={null}
curl -s -X POST https://api.ephra.io/v1/bank-account \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CURRENT",
    "bankCode": "341",
    "agency": "1234",
    "number": "56789",
    "digit": "0",
    "pixKey": "11144477735",
    "pixKeyType": "CPF"
  }'
```

A chave Pix efetiva do saque fica em `GET /v1/pix-key`:

```json theme={null}
{
  "success": true,
  "data": {
    "pixKey": "11111111000191",
    "bankCode": "341",
    "agency": "1234",
    "accountNumber": "56789",
    "accountDigit": "0",
    "accountType": "CURRENT"
  }
}
```

<Warning>
  A conta de recebimento precisa estar no **mesmo CPF/CNPJ da empresa**. Chave de terceiro é recusada.
</Warning>

## 5. Peça o saque

O saque exige uma `idempotencyKey`. Sem ela, `422`:

```json theme={null}
{ "success": false, "message": "idempotencyKey: Required" }
```

```bash theme={null}
curl -s -X POST https://api.ephra.io/v1/transfers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "idempotencyKey": "saque-2026-09-12-001",
    "pixKey": "11144477735",
    "description": "Saque semanal"
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "requestedAmount": 50000,
    "transfers": [
      {
        "id": "cmty0qbks000dpyg10cd873qb",
        "status": "pending_analysis",
        "amount": 50000,
        "fees": 350,
        "netAmount": 49650,
        "pixKey": "11144477735",
        "method": "manual",
        "type": "send_analysis",
        "requestSource": "api",
        "source": "internal",
        "externalId": null,
        "endToEndId": null,
        "description": "Saque semanal",
        "message": null,
        "createdAt": "2026-09-12T06:42:55.901Z",
        "updatedAt": "2026-09-12T06:42:55.901Z",
        "processedAt": null
      }
    ]
  }
}
```

A resposta é uma **lista**: um pedido pode ser quebrado em mais de uma transferência conforme a origem do dinheiro. Some `netAmount` para saber o que cai na conta — `50000` menos a taxa de `350`.

### A idempotência funciona de verdade

Repita a mesma chamada, com a mesma `idempotencyKey`, e a resposta traz **o mesmo `id`**. O saldo cai uma vez só:

```bash theme={null}
curl -s https://api.ephra.io/v1/balance -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": { "available": 33120, "receivable": 0, "reserved": 0 }
}
```

`83470 − 50000 − 350 = 33120`. Dois `POST` idênticos, um único débito.

<Tip>
  Gere a `idempotencyKey` a partir de algo estável do seu lado — o id do lote de pagamento, a data mais um contador — e não de um UUID aleatório por tentativa. Um UUID novo a cada retentativa transforma a proteção em duplicidade.
</Tip>

Acompanhe pelo `status`, lendo o saque de volta:

```bash theme={null}
curl -s https://api.ephra.io/v1/transfers/cmty0qbks000dpyg10cd873qb \
  -H "Authorization: Bearer $TOKEN"
```

`pending_analysis` significa que o saque entrou na fila de conferência. `endToEndId` só é preenchido quando o Pix sai de fato — é o comprovante que o banco do destinatário reconhece. O evento em tempo real é [`transfer_completed`](/webhooks/eventos/transferencias).

## 6. Antecipe o que ainda não liberou

Antes de pedir, simule:

```bash theme={null}
curl -s "https://api.ephra.io/v1/anticipations/summary?amount=50000" \
  -H "Authorization: Bearer $TOKEN"
```

Sem volume em carência, a resposta é um `400` que explica o limite:

```json theme={null}
{
  "success": false,
  "message": "Valor solicitado (R$ 500.00) excede o limite disponível para antecipação (R$ 0.00). Você pode antecipar até 60% do volume liberado."
}
```

O teto é 60% do volume já liberado. Com folga, a simulação devolve o custo e o líquido — e aí sim vale efetivar:

```bash theme={null}
curl -s -X POST https://api.ephra.io/v1/anticipations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "idempotencyKey": "antecipacao-2026-09-12-001",
    "automaticTransfer": true
  }'
```

<Warning>
  A `idempotencyKey` é **obrigatória** nesta rota. Sem ela a chamada nem chega à regra de negócio:

  ```json theme={null}
  { "success": false, "message": "idempotencyKey: Required" }
  ```

  Ela existe porque antecipar é irreversível e tem taxa: repetir o `POST` com a mesma chave devolve a antecipação já criada, em vez de antecipar duas vezes e cobrar duas taxas. É o que protege você ao repetir a chamada depois de um `429`, de um `5xx` ou de um timeout de rede. Reenviar a mesma chave com um `amount` diferente responde `400`.
</Warning>

Derive a chave de algo estável do seu lado — o id do lote, a data mais um contador —, nunca de um UUID novo por tentativa: aí a proteção vira duplicidade. `automaticTransfer: true` (o padrão) credita o líquido no saldo assim que a adquirente liquidar.

## 7. Veja o que está preso

```bash theme={null}
curl -s "https://api.ephra.io/v1/blocked-amounts?page=1&pageSize=5" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "17",
      "amount": 12990,
      "reason": "Contestação de compra em análise pelo emissor do cartão",
      "infractionId": null,
      "createdAt": "2026-09-12T05:49:19.847Z",
      "updatedAt": "2026-09-12T05:49:19.847Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 5, "total": 1, "totalPages": 1 }
}
```

Quando `infractionId` vem preenchido, o bloqueio tem uma contestação por trás — acompanhe em [Reembolsos](/guias/reembolsos).

## Todas as operações do domínio

<CardGroup cols={2}>
  <Card title="Saldo e extrato" icon="wallet" href="/api-reference/financeiro/consultar-saldo">
    Saldo em três partes, lançamentos e totais por tipo.
  </Card>

  <Card title="Saques" icon="money-bill-transfer" href="/api-reference/financeiro/solicitar-saque">
    Pedir, listar e consultar, com idempotência.
  </Card>

  <Card title="Antecipações" icon="forward" href="/api-reference/financeiro/consultar-antecipação-disponível">
    Simular o custo e efetivar.
  </Card>

  <Card title="Taxas e conta" icon="percent" href="/api-reference/financeiro/consultar-taxas-da-conta">
    Taxas por meio de pagamento, conta bancária e chave Pix.
  </Card>
</CardGroup>