Pagando um boleto

Este endpoint permite iniciar o pagamento de um boleto.

Obs: O boleto só poderá ser pago das 08:00 até às 20:00.

📍 Endpoint

POST https://api.etherglobalassets.com.br/boletos/pay

🧾 Cabeçalhos obrigatórios (Headers)

🧰 Corpo da Requisição (JSON)

{
  "barcode": "85890000001097802702003248545820001312019037",
  "amount": 10978
}

OU

{
  "typeableLine": "85890000000109780270200324854582000131201903700",
  "amount": 10978
}

Explicação dos campos:

⚠️ Nota: Você deve fornecer apenas um dos campos: barcode OU typeableLine. O campo amount é opcional e só deve ser usado quando o boleto permite pagamento com valor divergente.

Formatos Aceitos:

📌 Exemplo com curl

curl https://api.etherglobalassets.com.br/boletos/pay \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "barcode": "85890000001097802702003248545820001312019037",
    "amount": 10978
  }'

✅ Dica: Substitua <token> pelo seu JWT de autenticação válido e use o código de barras ou linha digitável do boleto. O valor em amount deve ser em centavos.

✅ Resposta esperada (HTTP 202 - Accepted)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userId": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
  "barcode": null,
  "typeableLine": "85890000000109780270200324854582000131201903700",
  "assignor": "BANCO EXEMPLO S.A.",
  "dueDate": "2024-12-31",
  "type": "COMPENSATIONFORM",
  "baseAmount": 10000,
  "feeAmount": 250,
  "internalFees": 150,
  "totalFeeAmount": 400,
  "providerNetAmount": 9750,
  "netAmount": 9600,
  "status": "PENDING",
  "provider": "FOURALL",
  "providerReferenceId": "123456",
  "senderInfo": {
    "name": "ETHER GLOBAL ASSETS LTDA",
    "document": {
      "type": "CNPJ",
      "number": "47114408000158"
    }
  },
  "receiverInfo": {
    "name": "BANCO EXEMPLO S.A.",
    "document": {
      "type": "CNPJ",
      "number": "00416968000101"
    }
  },
  "providerData": {
    "id": "123456",
    "bank": {
      "code": "001",
      "name": null
    },
    "type": "COMPENSATIONFORM",
    "payer": {
      "name": "ETHER GLOBAL ASSETS LTDA",
      "document": {
        "type": "CNPJ",
        "number": "47114408000158"
      }
    },
    "status": "CREATED",
    "barcode": null,
    "dueDate": "2024-12-31",
    "assignor": "BANCO EXEMPLO S.A.",
    "feeAmount": 250,
    "paidAmount": null,
    "beneficiary": {
      "name": "BANCO EXEMPLO S.A.",
      "document": {
        "type": "CNPJ",
        "number": "00416968000101"
      }
    },
    "nextWorkday": null,
    "payerRecord": {
      "name": "JOÃO DA SILVA SANTOS",
      "document": {
        "type": "CPF",
        "number": "12345678901"
      }
    },
    "typeableLine": "85890000000109780270200324854582000131201903700",
    "maximumAmount": 10000,
    "minimumAmount": 10000,
    "nominalAmount": 10000,
    "rejectionDate": null,
    "scheduledDate": null,
    "updatedAmount": 10000,
    "paymentDateTime": null,
    "confirmationDate": null,
    "creationDateTime": "2024-12-15T10:30:00.000Z",
    "rejectionReasonCode": null,
    "allowDifferentAmount": true,
    "cancellationDateTime": null,
    "regulatoryInformation": "Este estabelecimento é um Correspondente prestador de serviços bancários nos termos da Resolução 4.935/2021, do Conselho Monetário Nacional, e está autorizado a realizar os serviços de pagamentos de boletos, faturas de concessionárias e tributos municipais e estaduais com código de barras."
  },
  "feeBatchId": null,
  "feeDistributionCompletedAt": null,
  "feeDistributionMetadata": null,
  "createdAt": "2024-12-15T10:30:00.000Z",
  "updatedAt": "2024-12-15T10:30:00.000Z"
}

Explicação da resposta:

Campos principais:

Estrutura senderInfo:

Estrutura receiverInfo:

Estrutura providerData:

Campos de distribuição de taxas:

Status possíveis:

Tipos de boleto:

Códigos de banco (exemplos do schema):

⚠️ Possíveis erros

Erros HTTP:

Erros específicos de boleto:

🎯 Como usar o pagamento

Fluxo completo de pagamento:

1. Pré-visualizar: Execute /boletos/preview para obter detalhes do boleto

2. Confirmar valores: Verifique taxas e valor final antes do pagamento

3. Executar pagamento: Use /boletos/pay com os dados confirmados

4. Rastrear operação: Use o providerReferenceId para acompanhar o status

5. Consultar status: Use /boletos/{identifier} para verificar o progresso

6. Notificar usuário: Informe sobre o status do pagamento

Campos importantes para monitoramento:

Integração com outros endpoints:

• Consulta: Use GET /boletos/{id} com o id retornado

• Histórico: Consulte transações relacionadas usando o userId

• Auditoria: Use providerData para informações detalhadas do provedor

💰 Cálculo de valores

Estrutura de valores:

Fórmula de cálculo:

Valor Final = Valor Base - Taxas Totais
netAmount = baseAmount - totalFeeAmount

Regras importantes:

• Formato: Todos os valores são em centavos (ex: R$ 100,00 = 10000 centavos)

• Valor padrão: Use o baseAmount do boleto original

• Valor divergente: Só permitido quando allowDifferentAmount: true

• Saldo: Verifique se há saldo suficiente antes do pagamento

• Taxas: Sempre transparentes e calculadas automaticamente

Exemplo prático:

{
  "baseAmount": 10000,      // R$ 100,00 (valor do boleto)
  "feeAmount": 250,         // R$ 2,50 (taxa do provedor)
  "internalFees": 150,      // R$ 1,50 (taxa interna)
  "totalFeeAmount": 400,    // R$ 4,00 (total de taxas)
  "netAmount": 9600         // R$ 96,00 (valor final debitado)
}

🛡️ Limitações e restrições

Horário de funcionamento:

Limites de valor:

Restrições de boleto:

Boas práticas:

✅ FAÇA:

• Execute a pré-visualização antes do pagamento

• Use o providerReferenceId para rastreamento

• Verifique o horário de funcionamento (08:00-20:00)

• Confirme se há saldo suficiente

• Monitore o campo status para acompanhar o progresso

• Valide todos os campos antes de processar

• Mantenha logs das operações para auditoria

❌ NÃO FAÇA:

• Tentar pagar fora do horário permitido

• Ignorar a pré-visualização

• Usar valores incorretos

• Tentar pagar sem saldo suficiente

• Processar pagamentos sem validação

• Ignorar mensagens de erro

• Tentar pagar boletos inválidos

🆘 Problemas comuns

Erros de validação:

“Estou recebendo erro 400!”

• Verifique se executou a pré-visualização primeiro

• Confirme se há saldo suficiente na conta

• Verifique se o valor está correto

• Valide se o código de barras/linha digitável está correto

• Confirme se todos os campos obrigatórios estão preenchidos

“Erro 404 - Boleto não encontrado!”

• Execute o endpoint de pré-visualização primeiro

• Verifique se o boleto existe

• Confirme se o código está correto

• Teste com outro boleto para verificar se o problema persiste

Erros de pagamento:

“Pagamento rejeitado!”

• Verifique se está dentro do horário permitido (08:00-20:00)

• Confirme se é dia útil

• Verifique se o boleto não está vencido

• Confirme se o boleto não foi bloqueado

• Verifique se o valor não excede os limites

“Status não está atualizando!”

• Aguarde alguns minutos para o processamento

• Use o endpoint de consulta para verificar o status

• Verifique se o pagamento foi realmente processado

• Entre em contato com suporte se persistir

Erros de autenticação:

“Erro 401!”

• Verifique se o token de autenticação é válido

• Faça uma nova autenticação se necessário

• Confirme se o token não expirou

• Verifique se o header Authorization está correto

“Erro 403!”

• Verifique se o usuário tem permissão para pagar boletos

• Confirme se a conta está ativa

• Entre em contato com suporte se necessário

Problemas de integração:

“Resposta não está no formato esperado!”

• Verifique se está usando a versão correta da API

• Confirme se o Content-Type está como application/json

• Valide se a resposta está sendo parseada corretamente

“Campos obrigatórios ausentes!”

• Verifique se todos os campos necessários estão sendo enviados

• Confirme se a estrutura do JSON está correta

• Valide se os tipos de dados estão corretos

📞 Suporte

Antes de entrar em contato:

1. Verifique o horário de funcionamento (08:00-20:00)

2. Confirme a pré-visualização foi executada

3. Valide os dados enviados na requisição

4. Teste com outro boleto para isolar o problema

5. Verifique os logs da aplicação para erros específicos

Mais Informações sobre esse endpoint: