---
agentTools:
projectIndex: https://docs.grafeno.digital/llms.txt
---
# Criar cobrança - Boleto Bancário
Este recurso permite a criação de uma cobrança.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "API V2 Grafeno",
"version": "3.0.0"
},
"servers": [
{
"url": "https://pagamentos.grafeno.be/api/v2"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "apiKey",
"name": "Account-Number",
"in": "header"
},
"sec1": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-bearer-format": ""
}
}
},
"security": [
{
"sec0": [],
"sec1": []
}
],
"paths": {
"/charges": {
"post": {
"summary": "Criar cobrança - Boleto Bancário",
"description": "Este recurso permite a criação de uma cobrança.",
"operationId": "create-charge",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"paymentMethod",
"dueDate",
"value",
"payer"
],
"properties": {
"paymentMethod": {
"type": "string",
"description": "Método de pagamento da cobrança.
Valores permitidos: boleto, pix e ted .",
"enum": [
"boleto",
"ted",
"pix"
]
},
"dueDate": {
"type": "string",
"description": "Data de vencimento da cobrança.
Formato: YYYY-MM-DD.",
"format": "date"
},
"value": {
"type": "number",
"description": "Valor da cobrança. precisão 2.",
"format": "double"
},
"abatementValue": {
"type": "number",
"description": "Valor do Abatimento. precisão 2.",
"format": "double"
},
"interestType": {
"type": "string",
"description": "Tipo de juros que será aplicado a cobrança.
Valores permitidos fixed_value ou percentage.",
"enum": [
"fixed_value",
"percentage"
]
},
"interestValue": {
"type": "number",
"description": "Valor dos juros por mês. Valores inteiros ou decimais com precisão 2.",
"format": "double"
},
"applicableFine": {
"type": "number",
"description": "Multa por atraso em valor percentual. precisão 2 e limitado a até 100% do valor da transação.",
"format": "double"
},
"clientControlNumber": {
"type": "string",
"description": "Identificador próprio de uso da empresa.
Alfanumérico - 25 caracteres"
},
"expiresAfter": {
"type": "integer",
"description": "Dias para baixa após o vencimento. Caso não informado, o padrão é 90 dias.",
"format": "int32"
},
"discount": {
"type": "object",
"description": "DEPRECATED, deve-se utilizar a estrutura discounts. Desconto aplicado na cobrança.",
"properties": {
"range": {
"type": "string",
"description": "Data limite para aplicação do desconto.",
"format": "date"
},
"discountType": {
"type": "string",
"description": "tipo do desconto. valores possíveis fixed e percentage.",
"enum": [
"fixed_value",
"percentage"
]
},
"discountValue": {
"type": "number",
"description": "Valor do desconto.",
"format": "float"
}
}
},
"discounts": {
"type": "array",
"description": "Estrutura para regra de múltiplos descontos. Esta estrutura recebe no máximo até 3 regras de descontos.",
"items": {
"properties": {
"discountUntil": {
"type": "string",
"description": "Data máxima para aplicação do desconto.",
"format": "date"
},
"discountType": {
"type": "string",
"description": "Tipo de desconto.",
"enum": [
"fixed_value",
"percentage"
]
},
"discountValue": {
"type": "number",
"description": "Valor do desconto.",
"format": "double"
}
},
"required": [
"discountUntil",
"discountType",
"discountValue"
],
"type": "object"
}
},
"payer": {
"type": "object",
"description": "Dados do pagador da cobrança.
Caso o pagador já esteja cadastrado, é possível enviar apenas o documentNumber que a API completará os demais dados.",
"properties": {
"name": {
"type": "string",
"description": "Nome do pagador."
},
"documentNumber": {
"type": "string",
"description": "Documento do pagador."
},
"email": {
"type": "string",
"description": "E-mail do pagador."
},
"address": {
"type": "object",
"description": "Endereço do pagador.",
"properties": {
"street": {
"type": "string",
"description": "Rua do endereço do pagador ou avalista."
},
"neighborhood": {
"type": "string",
"description": "Bairro do pagador ou avalista."
},
"number": {
"type": "string",
"description": "número da residência do pagador ou avalista."
},
"state": {
"type": "string",
"description": "Estado do endereço do pagador ou avalista."
},
"city": {
"type": "string",
"description": "Cidade do endereço do pagador ou avalista."
},
"zipCode": {
"type": "string",
"description": "CEP do pagador ou avalista."
},
"complement": {
"type": "string",
"description": "Complemento do endereço do pagador ou avalista."
},
"country": {
"type": "string",
"description": "País do pagador ou avalista. (BRA)"
}
}
},
"phone": {
"type": "object",
"description": "Telefone do pagador.",
"properties": {
"number": {
"type": "string",
"description": "Número do telefone do pagador."
},
"areaCode": {
"type": "string",
"description": "Código de área do pagador."
},
"countryCode": {
"type": "string",
"description": "Código do país do pagador."
}
}
}
}
},
"boletoDetails": {
"type": "object",
"description": "Atributos do boleto bancário.",
"properties": {
"ourNumber": {
"type": "string",
"description": "Nosso número do boleto"
},
"yourNumber": {
"type": "string",
"description": "Seu número do boleto"
},
"registrationMethod": {
"type": "string",
"description": "Método de registro do boleto. Valores possíveis: online e offline.",
"default": "online",
"enum": [
"online",
"offline"
]
},
"messagingRuleId": {
"type": "string",
"description": "Régua de cobrança."
},
"titleType": {
"type": "string",
"description": "Natureza da cobrança.",
"default": "several",
"enum": [
"several",
"trade_bill",
"promissory_note",
"insurance_note",
"monthly_tuition",
"receipt",
"contract",
"cosseguros",
"service_bill",
"bill_exchange",
"debit_note",
"debt_document",
"condominium_fees",
"service_account"
]
},
"observation": {
"type": "string",
"description": "Instruções do boleto bancário."
}
}
},
"grantor": {
"type": "object",
"description": "Dados do Sacador / Avalista. *Obrigatório para abertura de protesto.*",
"required": [
"name",
"documentNumber"
],
"properties": {
"name": {
"type": "string",
"description": "Nome do Sacador / Avalista"
},
"documentNumber": {
"type": "string",
"description": "CPF ou CNPJ do Sacador / Avalista"
},
"Address": {
"type": "object",
"description": "Endereço do Sacador / Avalista. Obrigatório para abertura de protestos ",
"properties": {
"street": {
"type": "string",
"description": "Rua do endereço do pagador ou avalista."
},
"neighborhood": {
"type": "string",
"description": "Bairro do pagador ou avalista."
},
"number": {
"type": "string",
"description": "número da residência do pagador ou avalista."
},
"state": {
"type": "string",
"description": "Estado do endereço do pagador ou avalista."
},
"city": {
"type": "string",
"description": "Cidade do endereço do pagador ou avalista."
},
"zipCode": {
"type": "string",
"description": "CEP do pagador ou avalista."
},
"complement": {
"type": "string",
"description": "Complemento do endereço do pagador ou avalista."
},
"country": {
"type": "string",
"description": "País do pagador ou avalista. (BRA)"
}
}
}
}
},
"receiptNumber": {
"type": "string",
"description": "Número da nota fiscal vinculada a cobrança."
}
}
},
"examples": {
"Request Example": {
"value": {
"paymentMethod": "boleto",
"discount": {
"range": "2025-12-01",
"discountType": "percentage",
"discountValue": 5
},
"discounts": [
{
"discountType": "fixed_value",
"discountUntil": "2025-10-30",
"discountValue": "5.00"
},
{
"discountType": "percentage",
"discountUntil": "2025-11-05",
"discountValue": "12"
},
{
"discountType": "fixed_value",
"discountUntil": "2025-10-23",
"discountValue": "5.00"
}
],
"payer": {
"address": {
"street": "Dr Albuquerque Lins",
"neighborhood": "Santa Cecília",
"number": "4321",
"state": "SP",
"city": "São Paulo",
"zipCode": "01230000",
"complement": "ap 206",
"country": "BR"
},
"phone": {
"number": "988776655",
"areaCode": "11",
"countryCode": "55"
},
"name": "Andy Bernard",
"documentNumber": "12345679891",
"email": "nard.dog@cornell.edu"
},
"boletoDetails": {
"registrationMethod": "online",
"titleType": "several",
"ourNumber": "225700008091",
"yourNumber": "43212025",
"observation": "Pagar somente na rede bancária."
},
"grantor": {
"name": "Erin Hannon",
"documentNumber": "88771518460",
"address": {
"street": "Dr Albuquerque Lins",
"neighborhood": "Santa Cecília",
"number": "444",
"state": "SP",
"city": "São Paulo",
"zipCode": "01230000",
"complement": "ap 206",
"country": "BR"
}
},
"dueDate": "2025-01-01",
"value": 978.9,
"abatementValue": 2,
"interestType": "fixed_value",
"interestValue": 25.99,
"applicableFine": 1.5,
"clientControlNumber": "CHARGE-00001",
"expiresAfter": 60,
"receiptNumber": "32191105570714000825550010059146622233082968"
}
}
}
}
}
},
"responses": {
"200": {
"description": "200",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"data\": {\n \"id\": \"0e683d5d-61ce-445b-928e-3cc3340c0eda\",\n \"type\": \"charge\",\n \"attributes\": {\n \"createdAt\": \"2023-12-07T13:27:23.653-03:00\",\n \"updatedAt\": \"2023-12-07T13:27:23.653-03:00\",\n \"status\": \"pending\",\n \"paymentMethod\": \"boleto\",\n \"dueDate\": \"2023-12-10\",\n \"value\": 50,\n \"discount\": {\n \"range\": \"2023-12-08\",\n \"discountType\": \"percentage\",\n \"discountValue\": 5\n },\n \"abatementValue\": 5.2,\n \"interestType\": \"percentage\",\n \"interestValue\": 2,\n \"applicableFine\": 2,\n \"updateStatus\": null,\n \"updateDetails: [],\n \"payer\": {\n \"data\": {\n \"type\": \"payer\",\n \"attributes\": {\n \"name\": \"Han Solo\",\n \"documentNumber\": \"12345679891\",\n \"email\": \"han.solo@dunder-mifflin.paper\",\n \"address\": {\n \"street\": \"Rua Dr. Albuquerque Lins\",\n \"number\": \"2222\",\n \"complement\": \"Apt 222\",\n \"zipCode\": \"01230-000\",\n \"neighborhood\": \"Santa Cecília\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\"\n },\n \"phone\": {\n \"countryCode\": \"55\",\n \"areaCode\": \"51\",\n \"number\": \"995562211\"\n }\n }\n }\n },\n \"grantor\": {\n \"data\": {\n \"type\": \"grantor\",\n \"attributes\": {\n \"name\": \"Harrison Ford\",\n \"documentNumber\": \"88650081000116\",\n \"address\": {\n \"street\": \"Avenida Vinte de Setembro\",\n \"number\": \"456\",\n \"complement\": \"Apto 987\",\n \"zipCode\": \"93819-300\",\n \"neighborhood\": \"São Jacó\",\n \"city\": \"Sapiranga\",\n \"state\": \"RS\"\n }\n }\n }\n },\n \"fees\": {\n \"data\": []\n },\n \"boleto\": {\n \"data\": {\n \"id\": \"a55b20c8-7896-44a2-8b42-53137cd09208\",\n \"type\": \"boleto\",\n \"attributes\": {\n \"ourNumber\": 00000004321,\n \"ourNumberDv\": 8,\n \"barCode\": null,\n \"emv\": null,\n \"image\": null,\n \"quickPdfUrl\": null,\n \"lineCode\": null,\n \"registrationStatus\": null,\n \"pdf\": \"https://pagamentos.grafeno.be/charges/0e683d5d-61ce-445b-928e-3cc3340c0eda/download_boleto\",\n \"yourNumber\": \"11119998\",\n \"registrationMethod\": \"online\",\n \"messagingRuleId\": \"589f899a-9650-45ce-aeda-937f49c27156\",\n \"observation\": \"Sr(a) caixa, não receber o boleto após o vencimento\"\n }\n }\n },\n \"payments\": {\n \"data\": []\n },\n \"clientControlNumber\": \"7543649847645556555553425\",\n \"origin\": \"api\",\n \"receiptNumber\": \"51080701212344000127550010000000981364117781\",\n \"expiresAfter\": 90,\n \"titleType\": \"monthly_tuition\"\n }\n }\n}"
}
}
}
}
},
"400": {
"description": "400",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"success\": false,\n \"message\": \"Número de conta inválido.\"\n}"
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false,
"default": true
},
"message": {
"type": "string",
"example": "Número de conta inválido."
}
}
}
}
}
},
"401": {
"description": "401",
"content": {
"text/plain": {
"examples": {
"Result": {
"value": "Unauthorized"
}
}
}
}
},
"422": {
"description": "422",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"data\": {\n \"id\": \"\",\n \"type\": \"charge\",\n \"errors\": [\n {\n \"field\": \"field name\",\n \"messages\": [\n \"simple error message\"\n ]\n }\n ]\n },\n \"success\": false,\n \"message\": \"complete error message\"\n}"
}
},
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": ""
},
"type": {
"type": "string",
"example": "charge"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"example": "field name"
},
"messages": {
"type": "array",
"items": {
"type": "string",
"example": "simple error message"
}
}
}
}
}
}
},
"success": {
"type": "boolean",
"example": false,
"default": true
},
"message": {
"type": "string",
"example": "complete error message"
}
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true,
"_id": "64d50ab7b21b9e0063a215f9:64d50956330b890025bfa98e"
}
```