Changelog API Grafeno: 2026-06-17
Added: [API de Cobranças] Inclusão da estrutura boleto no retorno da listagem de cobranças
boleto no retorno da listagem de cobrançasAdicionamos a estrutura boleto e o parâmetro transferState ao retorno do endpoint de listagem de cobranças.
Anteriormente, o endpoint de listagem retornava apenas informações gerais da cobrança (como status, vencimento, valores e demais atributos operacionais), exigindo chamadas adicionais ou processos manuais para obtenção dos dados do título de cobrança. Com esta atualização, os dados do boleto passam a ser disponibilizados diretamente na resposta da listagem.
Os seguintes atributos passam a ser retornados na estrutura boleto:
• ourNumber — Nosso Número do boleto.
• ourNumberDv — Dígito verificador do Nosso Número.
• yourNumber — Seu Número (identificador definido pelo emissor).
• registrationStatus — Status do registro do boleto bancário.
• registrationMethod — Método de registro do boleto bancário.
• messagingRuleId — Régua de cobrança utilizada na criação da cobrança.
• observation — Observações do boleto bancário.
• barCode — Código de barras do boleto bancário.
• lineCode — Linha digitável do boleto bancário.
• env — PIX Copia & Cola (aplicável apenas para boleto).
• image — Base64 com o QRCode de pagamento via PIX (aplicável apenas para boleto).
• pdf — URL para download do PDF do boleto.
• quickPdfUrl — URL assinada para download do PDF do boleto.
Adição do parâmetro transferState ao callback de retorno
• transferState — Status de transferência/titularidade (quando aplicável).
Exemplos de retorno
"transferState": null,
"boleto": {
"data": {
"id": "7feba75d-0700-4ecb-a6ae-aa1b25d2ab44",
"type": "boleto",
"attributes": {
"ourNumber": 14821,
"ourNumberDv": "0",
"barCode": "31091154400123456780001000101261000000014821",
"emv": null,
"image": null,
"quickPdfUrl": "https://grafeno-pagamentos-carrierwave-staging.s3.amazonaws.com/uploads/vortx/boleto/48249/file/20-08-2026-TESTES_DE_BOLETOS-pagador_gerador_cnab-1242762.pdf?X-Amz-Expires=259200&X-Amz-Date=20260526T141629Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA6GUDBFRJDLS2JG7S%2F20260526%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=67f33b82d5565c24b0ec824ae66276b44e708e9a4b281a6e6083ghx78rygfy7c3g",
"lineCode": "31090001030010126100123456788213115440000067268",
"registrationStatus": "registered",
"pdf": "https://pagamentos.dev.grafeno.be/charges/d0158062-b0fb-4c10-a1e8-f81c12ccab44/download_boleto",
"yourNumber": "0067993001",
"registrationMethod": "online",
"messagingRuleId": "bba53578-fa76-47eb-aa3f-fa3d8c0e1c47",
"observation": "mensagem 1"
}
}
}
"transferState": null
{
"data": [
{
"id": "aaff64e6-7214-4cda-888b-b212346fe3cf",
"type": "charge",
"attributes": {
"createdAt": "2026-05-26T10:35:29.399-03:00",
"transferState": null,
"boleto": {
"data": {
"id": "1676e2cf-d6f0-41db-8227-734f99075d3e",
"type": "boleto",
"attributes": {
"ourNumber": 14822,
"ourNumberDv": "9",
"barCode": "310981459063546354001000101261000000014822",
"emv": null,
"image": null,
"quickPdfUrl": "https://grafeno-pagamentos-carrierwave-staging.s3.amazonaws.com/uploads/vortx/boleto/48350/file/27-05-2026-TESTES_DE_BOLETOS-Sthe-1242863.pdf?X-Amz-Expires=259200&X-Amz-Date=20260526T191754Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA6GGYDEYFGDETYFG2JG7S%2F20260526%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=b7201bc2fbda6503097y3gf7g7fdf46630f23721dd8198eed5cc701013324a",
"lineCode": "310900010300101286325465780148221814590000005000",
"registrationStatus": "registered",
"pdf": "https://pagamentos.dev.grafeno.be/charges/aaff64e6-7214-4cda-888b-b212346fe3cf/download_boleto",
"yourNumber": "0000148229",
"registrationMethod": "online",
"messagingRuleId": "bba53578-fa76-47eb-aa3f-f32a8c0e1c47",
"observation": null
}
}
},
"updatedAt": "2026-05-26T10:35:29.672-03:00",
"origin": "platform",
"status": "pending",
"dueDate": "2026-05-27",
"expiresAfter": 90,
"value": 50.0,
"paymentMethod": "boleto",
"clientControlNumber": "",
"paidAt": null,
"payer": {
"data": {
"type": "payer",
"attributes": {
"name": "Michael Gary Scott",
"documentNumber": "12345679891",
"email": "[email protected]",
"address": {
"street": "Avenida Raul Bezerra da Silva",
"number": "123",
"complement": "Casa 3",
"zipCode": "55644-412",
"neighborhood": "Cruzeiro",
"city": "Gravatá",
"state": "PE"
},
"phone": {
"countryCode": "55",
"areaCode": "81",
"number": "982052022"
}
}
}
},
"fees": {
"data": [
{
"id": "571763",
"type": "event",
"attributes": {
"kind": "charge_boleto_online_register_cost",
"value": 2.79
}
}
]
},
"payments": {
"data": []
}
}
}
],
"meta": {
"search": {},
"pagination": {
"currentPage": 1,
"previousPage": null,
"nextPage": 2,
"perPage": 25,
"totalPages": 218,
"totalCount": 5434
}
}
}
Impacto esperado para integrações
• Nenhuma alteração foi feita nos campos existentes do retorno da listagem.
• A nova estrutura é aditiva e retrocompatível.
• Integrações podem consumir os dados do boleto diretamente na listagem, eliminando a necessidade de chamadas adicionais ao endpoint de detalhe da cobrança ou de processos manuais para obtenção dessas informações.
A inclusão da estrutura boleto na listagem simplifica integrações e fluxos operacionais, reduzindo o número de requisições necessárias e centralizando os dados do título de cobrança em uma única resposta.
Acesse a especificação técnica da API de Cobranças Grafeno para obter informações sobre como utilizar este recurso.