Consultando um boleto

Este endpoint permite consultar o status de um boleto por meio do identificador do boleto (código de barras, linha digitável ou id do boleto).

📍 Endpoint

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

🧾 Cabeçalhos obrigatórios (Headers)

Cabeçalho	Valor	Descrição
Authorization	Bearer <token>	Token JWT de autenticação

🧰 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
identifier	string	✅	Identificador do boleto (código de barras, linha digitável ou id do boleto)

Formatos Aceitos:

Tipo	Formato	Exemplo
Código de barras	44 dígitos	`85890000001097802702003248545820001312019037`
Linha digitável	47 dígitos	`85890000000109780270200324854582000131201903700`
ID do boleto	UUID	`c32524e8c-d3fc-4b16-b3a8-b67635c555bd`

📌 Exemplo com curl

curl https://api.etherglobalassets.com.br/boletos/85890000001097802702003248545820001312019037 \
  --request GET \
  --header 'Authorization: Bearer <token>'

✅ Dica: Substitua <token> pelo seu JWT de autenticação válido e {identifier} pelo código de barras, linha digitável ou ID do boleto.

✅ Resposta esperada (HTTP 200 - OK)

{
  "providerIdReference": "29051",
  "id": "c32524e8c-d3fc-4b16-b3a8-b67635c555bd",
  "status": "PAID",
  "transactionStatus": "COMPLETED",
  "executedAt": "2021-08-30T19:20:29.000Z",
  "barcode": "85890000001097802702003248545820001312019037",
  "typeableLine": "858900000018097802702000324854582009013120190372",
  "providerPayload": {
    "additionalData": "Dados adicionais do provedor"
  }
}

Explicação da resposta:

Campo	Tipo	Descrição	Exemplo
providerIdReference	string	ID da operação no provedor	“29051”
id	string	ID único do boleto no sistema	“c32524e8c-d3fc-4b16-b3a8-b67635c555bd”
status	string	Status do boleto no provedor	“PAID”
transactionStatus	string	Status da transação no sistema	“COMPLETED”
executedAt	string	Data/hora de execução do pagamento	“2021-08-30T19:20:29.000Z”
barcode	string	Código de barras do boleto	“85890000001097802702003248545820001312019037”
typeableLine	string	Linha digitável do boleto	“858900000018097802702000324854582009013120190372”
providerPayload	object	Dados adicionais do provedor para auditoria	-

Status possíveis:

Status	Descrição
CREATED	Boleto criado
WAITING	Aguardando processamento
PENDING	Pendente de pagamento
PROCESSING	Em processamento
SCHEDULED	Agendado para pagamento
PAID	Pago
REJECTED	Rejeitado
CANCELLED	Cancelado

Status da Transação:

Status	Descrição
PENDING	Pendente
COMPLETED	Concluída
FAILED	Falhou
CANCELED	Cancelada

⚠️ Possíveis erros

Código	Erro	Causa comum
401	Unauthorized	Token inválido ou ausente
404	Not Found	Boleto não encontrado
500	Internal Server Error	Erro interno do serviço

🎯 Como usar a consulta

Após receber a resposta, você pode:

Verificar o status: Use os campos status e transactionStatus
Rastrear a operação: Use o providerIdReference para consultas externas
Confirmar pagamento: Verifique se status é “PAID” e transactionStatus é “COMPLETED”
Auditar transações: Use o providerPayload para dados detalhados

💰 Cálculo de valores

Tempo de processamento: Pagamentos instantâneos geralmente confirmam em segundos
Pagamentos agendados: Confirmação no horário agendado
Pagamentos manuais: Podem levar até 24 horas
Consultas: Recomendado aguardar 5-10 minutos após pagamento

🛡️ Limitações e restrições

✅ FAÇA:

Use o providerIdReference para rastreamento
Verifique ambos os status (status e transactionStatus)
Aguarde alguns minutos após pagamento para consultar
Use o executedAt para confirmar data/hora

❌ NÃO FAÇA:

Consultar imediatamente após pagamento
Ignorar o transactionStatus
Confiar apenas no status do provedor
Tentar consultar boletos inexistentes

🆘 Problemas comuns

“Estou recebendo erro 404!”

Verifique se o identificador está correto
Confirme se o boleto existe
Teste com outro formato de identificador

“Status não está atualizando!”

Aguarde alguns minutos após o pagamento
Verifique se o pagamento foi realmente processado
Consulte novamente em alguns instantes

“Erro 401!”

Verifique se o token de autenticação é válido
Faça uma nova autenticação se necessário

“Status inconsistente!”

Verifique ambos os campos de status
Consulte o providerPayload para mais detalhes
Entre em contato com suporte se necessário

📞 Suporte

Se nada funcionar:

Verifique o identificador do boleto
Confirme a autenticação está válida
Aguarde alguns minutos e tente novamente
Entre em contato com nossa equipe de suporte

Mais Informações sobre esse endpoint:

Acesse aqui