added
Changelog API Grafeno: 2026-03-16
15 days ago by Mario Dias
Added: [API de Cobranças] Novo evento de webhook
Adicionamos um novo evento ao webhook de cobranças: atualizacao-cobranca.
Este evento é disparado sempre que o processamento de uma solicitação de atualização de cobrança é concluído.
O evento será disparado nos seguintes cenários:
• Quando todas as solicitações de alteração forem concluídas com sucesso (completed).
• Quando todas as solicitações de alteração falharem (failed).
• Quando parte das solicitações de alteração for concluída e parte falhar (completed_with_errors).
O payload do webhook incluirá, além dos dados da cobrança, os dados da solicitação de alteração, contendo os campos updateStatus e updateDetails, permitindo que a sua integração identifique o resultado individual de cada alteração solicitada.
O evento atualizacao-cobranca será disparado ao término do processamento das atualizações, considerando que as alterações são processadas de forma assíncrona e podem levar até 30 minutos para conclusão.
Eventos
{
"signature": "sl+nb4iFuUYcIxAe7R4QxQpjL17gFynTZGpFVgqakJxUT9MSrbPmiogzefbC\nU4DwL5WMWW/FE4VX0CTVWqT/qUESUmKEUo8VyE2VelQabMddzeiKikxYeUJE\nzy2+cmG0kcok2zpqxQ/QrlGEkhDQNroDfshJxNsQMclLcjDYtE2yl1NOHGq4\nZvUdV3ZkOSuE9JMR/PJCd0mrlhfxaaEVgUI3nqSe7me3Cdu/fx150gOLNwgP\n+u20FUqQc/4+zloEC5KeVRworlO2HNIDSmQHWe9P6jIwqn0DUwsRboDhVy2B\n4FSze+/gkP/7d6Z6993/LGV1QL0OxsTjUvjbQjaKKJqdZEmvW87qgLREehS2\n6L63iRXfGpD8JCrvjy82ZYyln6P97vy9UGuCp1V1srY27utzJ+jIYg5inYt/\nB9WOVjcsfkX4yO0sG25J1htnKWoZsPOGJTjFrdxFivSvjrlkJymUgbyxu0l8\nnIfYpP0Ve5MzcBeY7Aq7LQoN5dx/C6U2GU2A6l3yC4Wi8tWD2SEDRn981oIE\nj1u7tmlKBWBTUxmRWFhsZbu+Yj3It+gEICtI4EZqZyf+UVl4s3Hzn1jE3EoS\nCNIJBSKDumTPZs+wsrqEDrS2OBPE3IWN2uIEfT60401G5rJ0ByinIk8tJmZ1\n7lOfC+G3IurAeH5Y8plShGI=\n",
"change": "cobranca-atualizacao",
"data": {
"createdAt": "2026-03-12T16:56:37.313-03:00",
"updatedAt": "2026-03-12T17:34:09.418-03:00",
"status": "pending",
"paymentMethod": "boleto",
"dueDate": "2026-10-18",
"value": "23.0",
"discount": {
"range": null,
"discount_value": null,
"discount_until": null
},
"discounts": [
{
"discount_type": "fixed_value",
"discount_value": "3.0",
"discount_until": "2026-05-10"
},
{
"discount_type": "percentage",
"discount_value": "7.0",
"discount_until": "2026-05-15"
},
{
"discount_type": "percentage",
"discount_value": "5.0",
"discount_until": "2026-05-20"
}
],
"abatementValue": "6.0",
"interestType": "percentage",
"interestValue": null,
"applicableFine": "2.0",
"payer": {
"data": {
"type": "payer",
"attributes": {
"email": "[email protected]",
"name": "Dwight Kurt Schrute",
"documentNumber": "12345679891",
"address": {
"city": "São Paulo",
"complement": "Apt 222",
"neighborhood": "Santa Cecília",
"number": "2222",
"state": "SP",
"street": "Rua Dr. Albuquerque Lins",
"zipCode": "01230-000"
},
"phone": {
"countryCode": "55",
"areaCode": "11",
"number": "988888888"
}
}
}
},
"grantor": {
"data": null
},
"fees": {
"data": [
{
"id": "57081960",
"type": "event",
"attributes": {
"kind": "charge_boleto_online_updated_cost",
"value": "1.99"
}
},
{
"id": "57079799",
"type": "event",
"attributes": {
"kind": "charge_boleto_online_register_cost",
"value": "0.0"
}
}
]
},
"boleto": {
"data": {
"id": "56fe8765-4782-4542-940f-e903fa994f47",
"type": "boleto",
"attributes": {
"ourNumber": 90000000010,
"ourNumberDv": "9",
"barCode": "31092152500000023000001012345807090000000010",
"emv": null,
"image": null,
"quickPdfUrl": "https://grafeno-pagamentos-carrierwave-production.s3-sa-east-1.amazonaws.com/uploads/vortx/boleto/445819/file/19-10-2026_-_DWIGHT_KURT_-_dwight_kurt_-_14593571.pdf?X-Amz-Expires=259200&X-Amz-Date=20260312T203410Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA6GUASARJNLE4KEJF%2F20260312%2Fsa-east-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=7140c0e9c522221a9714b503eba3359fe4ff104a1e294c602d45f4trtf1cb45",
"lineCode": "31090001030010480709400000000109215250000002300",
"registrationStatus": "registered",
"pdf": "https://pagamentos.grafeno.digital/charges/da039352-699a-4ba0-b09b-6b3e94eb3a47/download_boleto",
"yourNumber": "devxdebug-321",
"registrationMethod": "online",
"messagingRuleId": "1ae24331-5e6e-47ee-ac48-aede1ec2bcf2",
"observation": "Sr(a) caixa, não receber o boleto após o vencimento"
}
}
},
"payments": {
"data": []
},
"clientControlNumber": "CHA-0001032026",
"origin": "api",
"receiptNumber": "510807012123440001275534322320000981364117781",
"expiresAfter": 90,
"uuid": "da039352-699a-4ba0-b09b-6b3e94eb3a47",
"updateStatus": "completed",
"updateDetails": [
{
"field": "dueDate",
"status": "success",
"previousValue": "2026-08-01",
"newValue": "2026-10-18",
"updatedAt": "2026-03-12T17:24:25-03:00"
},
{
"field": "yourNumber",
"status": "success",
"previousValue": "11119999",
"newValue": "devxdebug-321",
"updatedAt": "2026-03-12T17:09:14-03:00"
},
{
"field": "abatementValue",
"status": "success",
"previousValue": "3.00",
"newValue": "6.00",
"updatedAt": "2026-03-12T17:34:09-03:00"
}
],
"titleType": "monthly_tuition"
}
}
{
"signature": "sl+nb4iFuUYcIxAe7R4QxQpjL17gFynTZGpFVgqakJxUT9MSrbPmiogzefbC\nU4DwL5WMWW/FE4VX0CTVWqT/qUESUmKEUo8VyE2VelQabMddzeiKikxYeUJE\nzy2+cmG0kcok2zpqxQ/QrlGEkhDQNroDfshJxNsQMclLcjDYtE2yl1NOHGq4\nZvUdV3ZkOSuE9JMR/PJCd0mrlhfxaaEVgUI3nqSe7me3Cdu/fx150gOLNwgP\n+u20FUqQc/4+zloEC5KeVRworlO2HNIDSmQHWe9P6jIwqn0DUwsRboDhVy2B\n4FSze+/gkP/7d6Z6993/LGV1QL0OxsTjUvjbQjaKKJqdZEmvW87qgLREehS2\n6L63iRXfGpD8JCrvjy82ZYyln6P97vy9UGuCp1V1srY27utzJ+jIYg5inYt/\nB9WOVjcsfkX4yO0sG25J1htnKWoZsPOGJTjFrdxFivSvjrlkJymUgbyxu0l8\nnIfYpP0Ve5MzcBeY7Aq7LQoN5dx/C6U2GU2A6l3yC4Wi8tWD2SEDRn981oIE\nj1u7tmlKBWBTUxmRWFhsZbu+Yj3It+gEICtI4EZqZyf+UVl4s3Hzn1jE3EoS\nCNIJBSKDumTPZs+wsrqEDrS2OBPE3IWN2uIEfT60401G5rJ0ByinIk8tJmZ1\n7lOfC+G3IurAeH5Y8plShGI=\n",
"change": "cobranca-atualizacao",
"data": {
"createdAt": "2026-03-12T16:56:37.313-03:00",
"updatedAt": "2026-03-12T17:34:09.418-03:00",
"status": "pending",
"paymentMethod": "boleto",
"dueDate": "2026-10-18",
"value": "23.0",
"discount": {
"range": null,
"discount_value": null,
"discount_until": null
},
"discounts": [
{
"discount_type": "fixed_value",
"discount_value": "3.0",
"discount_until": "2026-05-10"
},
{
"discount_type": "percentage",
"discount_value": "7.0",
"discount_until": "2026-05-15"
},
{
"discount_type": "percentage",
"discount_value": "5.0",
"discount_until": "2026-05-20"
}
],
"abatementValue": "6.0",
"interestType": "percentage",
"interestValue": null,
"applicableFine": "2.0",
"payer": {
"data": {
"type": "payer",
"attributes": {
"email": "[email protected]",
"name": "Dwight Kurt Schrute",
"documentNumber": "12345679891",
"address": {
"city": "São Paulo",
"complement": "Apt 222",
"neighborhood": "Santa Cecília",
"number": "2222",
"state": "SP",
"street": "Rua Dr. Albuquerque Lins",
"zipCode": "01230-000"
},
"phone": {
"countryCode": "55",
"areaCode": "11",
"number": "988888888"
}
}
}
},
"grantor": {
"data": null
},
"fees": {
"data": [
{
"id": "57081960",
"type": "event",
"attributes": {
"kind": "charge_boleto_online_updated_cost",
"value": "1.99"
}
},
{
"id": "57079799",
"type": "event",
"attributes": {
"kind": "charge_boleto_online_register_cost",
"value": "0.0"
}
}
]
},
"boleto": {
"data": {
"id": "56fe8765-4782-4542-940f-e903fa994f47",
"type": "boleto",
"attributes": {
"ourNumber": 90000000010,
"ourNumberDv": "9",
"barCode": "31092152500000023000001012345807090000000010",
"emv": null,
"image": null,
"quickPdfUrl": "https://grafeno-pagamentos-carrierwave-production.s3-sa-east-1.amazonaws.com/uploads/vortx/boleto/445819/file/19-10-2026_-_DWIGHT_KURT_-_dwight_kurt_-_14593571.pdf?X-Amz-Expires=259200&X-Amz-Date=20260312T203410Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA6GUASARJNLE4KEJF%2F20260312%2Fsa-east-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=7140c0e9c522221a9714b503eba3359fe4ff104a1e294c602d45f4trtf1cb45",
"lineCode": "31090001030010480709400000000109215250000002300",
"registrationStatus": "registered",
"pdf": "https://pagamentos.grafeno.digital/charges/da039352-699a-4ba0-b09b-6b3e94eb3a47/download_boleto",
"yourNumber": "devxdebug-321",
"registrationMethod": "online",
"messagingRuleId": "1ae24331-5e6e-47ee-ac48-aede1ec2bcf2",
"observation": "Sr(a) caixa, não receber o boleto após o vencimento"
}
}
},
"payments": {
"data": []
},
"clientControlNumber": "CHA-0001032026",
"origin": "api",
"receiptNumber": "510807012123440001275534322320000981364117781",
"expiresAfter": 90,
"uuid": "da039352-699a-4ba0-b09b-6b3e94eb3a47",
"updateStatus": "completed_with_errors",
"updateDetails": [
{
"field": "dueDate",
"status": "failed",
"message": "Não foi possível alterar a data de vencimento da cobrança, a data informada é inválida.",
"error_code": "DUE_DATE_ERROR"
},
{
"field": "yourNumber",
"status": "success",
"previousValue": "11119999",
"newValue": "devxdebug-321",
"updatedAt": "2026-03-12T17:09:14-03:00"
},
{
"field": "abatementValue",
"status": "success",
"previousValue": "3.00",
"newValue": "6.00",
"updatedAt": "2026-03-12T17:34:09-03:00"
}
],
"titleType": "monthly_tuition"
}
}
{
"signature": "sl+nb4iFuUYcIxAe7R4QxQpjL17gFynTZGpFVgqakJxUT9MSrbPmiogzefbC\nU4DwL5WMWW/FE4VX0CTVWqT/qUESUmKEUo8VyE2VelQabMddzeiKikxYeUJE\nzy2+cmG0kcok2zpqxQ/QrlGEkhDQNroDfshJxNsQMclLcjDYtE2yl1NOHGq4\nZvUdV3ZkOSuE9JMR/PJCd0mrlhfxaaEVgUI3nqSe7me3Cdu/fx150gOLNwgP\n+u20FUqQc/4+zloEC5KeVRworlO2HNIDSmQHWe9P6jIwqn0DUwsRboDhVy2B\n4FSze+/gkP/7d6Z6993/LGV1QL0OxsTjUvjbQjaKKJqdZEmvW87qgLREehS2\n6L63iRXfGpD8JCrvjy82ZYyln6P97vy9UGuCp1V1srY27utzJ+jIYg5inYt/\nB9WOVjcsfkX4yO0sG25J1htnKWoZsPOGJTjFrdxFivSvjrlkJymUgbyxu0l8\nnIfYpP0Ve5MzcBeY7Aq7LQoN5dx/C6U2GU2A6l3yC4Wi8tWD2SEDRn981oIE\nj1u7tmlKBWBTUxmRWFhsZbu+Yj3It+gEICtI4EZqZyf+UVl4s3Hzn1jE3EoS\nCNIJBSKDumTPZs+wsrqEDrS2OBPE3IWN2uIEfT60401G5rJ0ByinIk8tJmZ1\n7lOfC+G3IurAeH5Y8plShGI=\n",
"change": "cobranca-atualizacao",
"data": {
"createdAt": "2026-03-12T16:56:37.313-03:00",
"updatedAt": "2026-03-12T17:34:09.418-03:00",
"status": "pending",
"paymentMethod": "boleto",
"dueDate": "2026-10-18",
"value": "23.0",
"discount": {
"range": null,
"discount_value": null,
"discount_until": null
},
"discounts": [
{
"discount_type": "fixed_value",
"discount_value": "3.0",
"discount_until": "2026-05-10"
},
{
"discount_type": "percentage",
"discount_value": "7.0",
"discount_until": "2026-05-15"
},
{
"discount_type": "percentage",
"discount_value": "5.0",
"discount_until": "2026-05-20"
}
],
"abatementValue": "6.0",
"interestType": "percentage",
"interestValue": null,
"applicableFine": "2.0",
"payer": {
"data": {
"type": "payer",
"attributes": {
"email": "[email protected]",
"name": "Dwight Kurt Schrute",
"documentNumber": "12345679891",
"address": {
"city": "São Paulo",
"complement": "Apt 222",
"neighborhood": "Santa Cecília",
"number": "2222",
"state": "SP",
"street": "Rua Dr. Albuquerque Lins",
"zipCode": "01230-000"
},
"phone": {
"countryCode": "55",
"areaCode": "11",
"number": "988888888"
}
}
}
},
"grantor": {
"data": null
},
"fees": {
"data": [
{
"id": "57081960",
"type": "event",
"attributes": {
"kind": "charge_boleto_online_updated_cost",
"value": "1.99"
}
},
{
"id": "57079799",
"type": "event",
"attributes": {
"kind": "charge_boleto_online_register_cost",
"value": "0.0"
}
}
]
},
"boleto": {
"data": {
"id": "56fe8765-4782-4542-940f-e903fa994f47",
"type": "boleto",
"attributes": {
"ourNumber": 90000000010,
"ourNumberDv": "9",
"barCode": "31092152500000023000001012345807090000000010",
"emv": null,
"image": null,
"quickPdfUrl": "https://grafeno-pagamentos-carrierwave-production.s3-sa-east-1.amazonaws.com/uploads/vortx/boleto/445819/file/19-10-2026_-_DWIGHT_KURT_-_dwight_kurt_-_14593571.pdf?X-Amz-Expires=259200&X-Amz-Date=20260312T203410Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA6GUASARJNLE4KEJF%2F20260312%2Fsa-east-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=7140c0e9c522221a9714b503eba3359fe4ff104a1e294c602d45f4trtf1cb45",
"lineCode": "31090001030010480709400000000109215250000002300",
"registrationStatus": "registered",
"pdf": "https://pagamentos.grafeno.digital/charges/da039352-699a-4ba0-b09b-6b3e94eb3a47/download_boleto",
"yourNumber": "devxdebug-321",
"registrationMethod": "online",
"messagingRuleId": "1ae24331-5e6e-47ee-ac48-aede1ec2bcf2",
"observation": "Sr(a) caixa, não receber o boleto após o vencimento"
}
}
},
"payments": {
"data": []
},
"clientControlNumber": "CHA-0001032026",
"origin": "api",
"receiptNumber": "510807012123440001275534322320000981364117781",
"expiresAfter": 90,
"uuid": "da039352-699a-4ba0-b09b-6b3e94eb3a47",
"updateStatus": "failed",
"updateDetails": [
{
"field": "dueDate",
"status": "failed",
"message": "Não foi possível alterar a data de vencimento, a data informada é inválida.",
"error_code": "DUE_DATE_ERROR"
},
{
"field": "abatementValue",
"status": "failed",
"message": "Não foi possível incluir o abatimento.",
"error_code": "GENERIC_ERROR"
}
],
"titleType": "monthly_tuition"
}
}
Impacto esperado para integrações
• Nenhuma alteração foi feita nos eventos existentes.
• O novo evento é aditivo e retrocompatível.
• Integrações podem utilizar o evento para reagir automaticamente ao resultado das atualizações de cobrança, evitando a necessidade de consultas periódicas na API.
O evento atualizacao-cobranca permite que integrações acompanhem o resultado das atualizações de forma orientada a eventos, simplificando a implementação de fluxos automatizados e reduzindo a necessidade de polling na API.
Acesse a especificação técnica da API de Webhooks Grafeno para obter informações sobre como utilizar este recurso.