Financeiro

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.

Tudo em centavos. 83470 é R$ 834,70.

1. Confira o saldo

curl -s https://api.ephra.io/v1/balance \
  -H "Authorization: Bearer $TOKEN"

{
  "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 pode adiantar.

2. Leia o extrato

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

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

{
  "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:

curl -s https://api.ephra.io/v1/balance-operations/by-type \
  -H "Authorization: Bearer $TOKEN"

{
  "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

curl -s https://api.ephra.io/v1/fees \
  -H "Authorization: Bearer $TOKEN"

{
  "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
  }
}

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.

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

curl -s https://api.ephra.io/v1/bank-account \
  -H "Authorization: Bearer $TOKEN"

{
  "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:

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:

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

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

5. Peça o saque

O saque exige uma idempotencyKey. Sem ela, 422:

{ "success": false, "message": "idempotencyKey: Required" }

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"
  }'

{
  "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ó:

curl -s https://api.ephra.io/v1/balance -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": { "available": 33120, "receivable": 0, "reserved": 0 }
}

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

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.

Acompanhe pelo status, lendo o saque de volta:

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.

6. Antecipe o que ainda não liberou

Antes de pedir, simule:

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:

{
  "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:

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
  }'

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

{ "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.

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

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

{
  "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.

Todas as operações do domínio

Saldo e extrato

Saldo em três partes, lançamentos e totais por tipo.

Saques

Pedir, listar e consultar, com idempotência.

Antecipações

Simular o custo e efetivar.

Taxas e conta

Taxas por meio de pagamento, conta bancária e chave Pix.

Integração

API do vendedor

Cobranças

Assinaturas

Ajuda

1. Confira o saldo

2. Leia o extrato

3. Entenda o que a Ephra cobra

4. Cadastre para onde o dinheiro vai

5. Peça o saque

A idempotência funciona de verdade

6. Antecipe o que ainda não liberou

7. Veja o que está preso

Todas as operações do domínio

Saldo e extrato

Saques

Antecipações

Taxas e conta

​1. Confira o saldo

​2. Leia o extrato

​3. Entenda o que a Ephra cobra

​4. Cadastre para onde o dinheiro vai

​5. Peça o saque

​A idempotência funciona de verdade

​6. Antecipe o que ainda não liberou

​7. Veja o que está preso

​Todas as operações do domínio

Saldo e extrato

Saques

Antecipações

Taxas e conta

1. Confira o saldo

2. Leia o extrato

3. Entenda o que a Ephra cobra

4. Cadastre para onde o dinheiro vai

5. Peça o saque

A idempotência funciona de verdade

6. Antecipe o que ainda não liberou

7. Veja o que está preso

Todas as operações do domínio