Trabalhando com boletos

Este documento apresenta as especificações técnicas dos endpoints para o processamento e pagamento de boletos bancários através da plataforma Ether.

1. Pagamento ou Simulação de Boleto

A API permite o pagamento de boletos de duas formas independentes: utilizando saldo em moeda fiduciária (FIAT) ou utilizando saldo em Criptomoedas (CRYPTO). O endpoint é unificado e seu comportamento adapta-se aos parâmetros fornecidos.

Endpoint: POST https://api.etherglobalassets.com.br/boletos/pay-boleto

1.1 Parâmetros do Corpo da Requisição (JSON)

Campo	Tipo	Obrigatoriedade	Descrição
`digitableLine`	string	✅	A linha digitável do boleto a ser pago.
`paymentMethod`	string	✅	Aceita apenas: `FIAT` ou `CRYPTO`.
`isSimulation`	boolean	✅	Se `true`, a transação não é executada. Retorna taxas e cotação.
`cryptoToken`	string	Condicional	Obrigatório se `paymentMethod` for `CRYPTO`. Símbolo do ativo.
`network`	string	Condicional	Obrigatório se `paymentMethod` for `CRYPTO`. Rede blockchain do ativo.

1.1.1 Criptomoedas e Redes Suportadas

Para pagamentos via CRYPTO, as seguintes combinações são aceitas de forma integral:

BTC: Rede Bitcoin.
USDT: Redes Ethereum (ERC20), Tron (TRC20) e Polygon.
USDC: Redes Ethereum (ERC20), Polygon, Base, Optimism e Solana.

1.2 Detalhamento das Respostas

Resposta: Cotação e Simulação (`isSimulation: true`)

A resposta indicará a viabilidade da transação e os custos detalhados. ⚠️ Dica: Recomenda-se exibir este retorno ao usuário final antes de processar o pagamento definitivo.

{
  "isSimulation": true,
  "canPay": true, 
  "reason": null,
  "paymentMethod": "CRYPTO",
  "boleto": {
    "assignor": "Empresa Recebedora Ltda.",
    "dueDate": "2026-05-10",
    "baseAmount": 150.50,
    "totalFeeAmount": 1.50,
    "netAmount": 152.00
  },
  "cryptoDetails": { 
    "token": "USDC",
    "network": "Polygon",
    "currentPrice": 4.95,
    "cryptoAmount": 30.7070,
    "availableBalance": 500.00,
    "totalFees": 1.50,
    "netAmountBrl": 152.00
  }
}

Resposta: Sucesso (`isSimulation: false`)

A requisição foi aceita e o pagamento enviado para finalização bancária.

{
  "success": true,
  "message": "Operação de pagamento de boleto criada com sucesso",
  "boletoId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "boletoCriptoOrderId": "a123-b456-c789",
  "transactionId": "t987-u654-v321"
}

2. Consulta de Status do Boleto

Como a retaguarda e a compensação do sistema bancário ocorrem de forma assíncrona, a sua aplicação deve implementar um modelo de polling (consultas periódicas).

Endpoint: GET https://api.etherglobalassets.com.br/boletos/{identifier}

2.1 Parâmetros

identifier (Path): Aceita o ID referenciado (UUID), a própria Linha Digitável ou o Código de Barras.

2.2 Exemplo de Resposta de Consulta

{
  "id": "e30f1d06-4b13-4ae3-94c6-30238e83b150",
  "providerIdReference": "ABC-12345",
  "status": "PAID",
  "transactionStatus": "COMPLETED",
  "executedAt": "2026-04-17T14:30:00Z",
  "barcode": "07797777051177160607318241876111313700000002000",
  "typeableLine": "07797777051177160607318241876111313700000002000",
  "providerPayload": {}
}

📊 Estados Possíveis (`status`)

PROCESSING: O pagamento está na fila bancária aguardando retorno.
PAID: Pagamento finalizado e garantido com sucesso. ✅
FAILED / REJECTED: O pagamento retornou uma desaprovação da câmera de conciliação. ❌

Obtendo transações de criptomoedas por ID

Executando SWAP