Descrição:

Gerar Bolix

 

Passo a passo para gerar Bolix na API Gerencianet, o Bolix permite gerar cobranças com o pix no boleto, possibilitando mais de uma forma de pagamento aos clientes

---

O Bolix, pix no boleto, permite gerar transações do tipo boleto e carnê para seu cliente com o acréscimo do Pix como forma de pagamento.
O Bolix quando emitido na forma de boleto pode ser gerado via API em um passo, também conhecido como One Step ou em dois passos, o Two Steps.
Também é disponibilizado a emissão do Bolix como carnê, que consiste em um conjunto de transações (parcelas) geradas em lote e com forma de pagamento já definida com vencimento mensal.

Todos os fluxos e informações para emissões do Bolix tanto como boleto bancário quanto carnê estão detalhados a seguir:

1. Criando Bolix com o método de pagamento boleto bancário, transação em One Step (Um passo).

2. Criando Bolix com o método de pagamento boleto bancário, transação em Two Steps (Dois passos).

3. Criando Bolix com o método de pagamento carnê.

 Ativação do Bolix

Para que você consiga emitir cobranças Bolix, boleto com pix, primeiramente deve-se ativar o Bolix em sua conta Gerencianet, siga estes passos:

1- Acesse sua Conta Digital na plataforma web.
2- Clique no menu Cobranças > Configurações > Boletos Bancários e Carnês.
3- Por fim, habilite a função “Bolix” como nesta imagem.

 SDK's

 

O restante desta página apresenta os procedimentos detalhados para criação do Bolix com os métodos de pagamento boleto bancário e carnê, mas você precisa instalar uma de nossas bibliotecas em seu servidor para executar os códigos de exemplo. Certifique-se de que a SDK da Gerencianet foi instalada.

 

1. Criação do Bolix, boleto com pix, em One Step (Um passo)

Nesta opção é necessário que o body da requisição contenha todos os atributos mínimos obrigatórios para a emissão do titulo.
Abaixo temos os exemplos de implementação utilizando as SDK's disponíveis:

PHP·

NodeJS·

Python·

Java·

.NET·

Go·

Ruby·

Delphi

 

<?php
   require __DIR__ . '/../../vendor/autoload.php'; // caminho relacionado a SDK

   use Gerencianet\Exception\GerencianetException;
   use Gerencianet\Gerencianet;

   $clientId = 'informe_seu_client_id';// insira seu Client_Id, conforme o ambiente (Des ou Prod)
   $clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)

    $options = [
        'client_id' => $clientId,
        'client_secret' => $clientSecret,
        'sandbox' => true // altere conforme o ambiente (true = homologação e false = producao)
    ];
    
   $item_1 = [
       'name' => 'Item 1', // nome do item, produto ou serviço
       'amount' => 1, // quantidade
       'value' => 1000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.)
   ];
   $items = [
       $item_1
   ];
   $metadata = array('notification_url'=>'sua_url_de_notificacao_.com.br'); //Url de notificações onde vamos notificá-lo, independente se for pago pelo código de barras do boleto quanto pelo QR Code.
   $customer = [
       'name' => 'Gorbadoc Oldbuck', // nome do cliente
       'cpf' => '94271564656', // cpf válido do cliente
       'phone_number' => '5144916523', // telefone do cliente
   ];
   $discount = [ // configuração de descontos
       'type' => 'currency', // tipo de desconto a ser aplicado
       'value' => 599 // valor de desconto 
   ];
   $configurations = [ // configurações de juros e mora
       'fine' => 200, // porcentagem de multa
       'interest' => 33 // porcentagem de juros
   ];
   $conditional_discount = [ // configurações de desconto condicional
       'type' => 'percentage', // seleção do tipo de desconto 
       'value' => 500, // porcentagem de desconto
       'until_date' => '2019-08-30' // data máxima para aplicação do desconto
   ];
   $bankingBillet = [
       'expire_at' => '2022-09-01', // data de vencimento do titulo
       'message' => 'Pague pelo código de barras ou pelo QR Code', // mensagem a ser exibida no boleto
       'customer' => $customer,
       'discount' =>$discount,
       'conditional_discount' => $conditional_discount
   ];
   $payment = [
       'banking_billet' => $bankingBillet // forma de pagamento (banking_billet = Bolix)
   ];
   $body = [
       'items' => $items,
       'metadata' =>$metadata,
       'payment' => $payment
   ];
   try {
     $api = new Gerencianet($options);
     $pay_charge = $api->oneStep([],$body);
     echo '<pre>';
     print_r($pay_charge);
     echo '<pre>';
     
    } catch (GerencianetException $e) {
       print_r($e->code);
       print_r($e->error);
       print_r($e->errorDescription);
   } catch (Exception $e) {
       print_r($e->getMessage());
   }

 

 

Dados de entrada e saída do Bolix em One Step:

Dados de entrada·

Dados de saída

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 5990,
      "amount": 1
    }
  ],
  "payment": {
    "banking_billet": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "phone_number": "5144916523",
        "address": {
          "street": "Avenida Juscelino Kubitschek",
          "number": "909",
          "neighborhood": "Bauxita",
          "zipcode": "35400000",
          "city": "Ouro Preto",
          "complement": "",
          "state": "MG"
        }
      },
      "expire_at": "2022-12-15",
      "configurations": {
        "fine": 200,
        "interest": 33
      },
      "message": "Pague pelo código de barras ou pelo QR Code"
    }
  }
}

 

 

a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:

 

"OneStep": "/Charge/one-step"
    "items"
        "name"
        "value"
        "amount"
        "marketplace"
            "payee_code"
            "percentage"
    "shippings"
        "name"
        "value"
        "payee_code"
    "metadata"
        "custom_id"
        "notification_url"
    "payment"
        "banking_billet"
            "customer"
                "name"
                "cpf"
                "email"
                "phone_number"
                "birth"
                "address"
                    "street"
                    "number"
                    "neighborhood"
                    "zipcode"
                    "city"
                    "complement"
                    "state"
                "juridical_person"
                    "corporate_name"
                    "cnpj"
            "expire_at"
            "discount"
                "type"
                    "percentage",
                    "currency"
                "value"
            "conditional_discount"
                "type"
                    "percentage",
                    "currency"
                "value"
                "until_date"
            "configurations"
                "fine"
                "interest"
            "message"

 

 

b) Atributos que podem ser utilizados para criar um título:

 

 

Objeto items

Atributo	Descrição	Obrigatório	Tipo
items	Item que está sendo vendido. Uma mesma transação pode possuir ilimitados itens. Atributos de items   name* // Nome do item, produto ou serviço. Mínimo de 1 caractere e máximo de 255 caracteres (String).     value* // Valor, em centavos. Ex: R$ 10,00 = 1000. Integer.     amount // Quantidade. Integer (padrão: 1)	Sim	Array
shippings	Determina o(s) valor(es) de frete(s) de uma transação. Uma mesma transação pode possuir ilimitados valores de frete. Atributos de shippings   name* // Rótulo do frete. Máximo de 255 caracteres. String.     value* // Valor do frete, em centavos (1990 equivale a R$19,90). Integer.     payeeCode, // código da conta Gerencianet que receberá o repasse do valor total do frete - refere-se ao "identificador da conta" Gerencianet (onde localizar meu identificador?) (String)	Não	Array
metadata	Define dados específicos da transação. Atributos de metadata   custom_id // Permite associar uma transação Gerencianet a uma ID específica de seu sistema ou aplicação, permitindo identificá-la caso você possua uma identificação específica e queira mantê-la. Máximo de 255 caracteres. String/null.     notification_url // Endereço de sua URL válida que receberá as notificações de mudanças de status das transações. Máximo de 255 caracteres. String/null.	Não	Object

 

Objeto Payment

Atributo	Descrição	Obrigatório	Tipo
banking_billet	Forma de pagamento através de "boleto bancário"	Sim	Objeto Banking_Billet

 

Objeto Banking_Billet

Atributo	Descrição	Obrigatório	Tipo
name	Nome do cliente. Mínimo de 1 caractere e máximo de 255.	Sim Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
cpf	CPF válido do cliente (sem pontos, vírgulas ou hífen). Tamanho: 11 caracteres.	Sim Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
email	Email do cliente. Máximo de 255 caracteres. Ex.: [email protected]	Não	String
phone_number	Telefone do cliente. Formato: sem pontos ou vírgulas, com DDD de 2 caracteres (9º dígito é opcional). Ex.: 11988887777	Não	String
birth	Data de nascimento do cliente. Formato: YYYY-MM-DD	Não	String
address	Endereço do cliente. Atributos de address   street* // nome da rua (Object)     number* // número (String/Integer)     neighborhood* // Bairro (String)     zipcode* // CEP (sem pontos ou hífen) (String)     city* // cidade (String)     complement // complemento (String/null)     state* // estado (2 caracteres) (Object)	Não	Object
juridical_person	Dados de pessoa jurídica Atributos de juridical_person   corporate_name* // Nome da razão social. Mínimo de 1 caractere e máximo de 255. String.     cnpj* // CNPJ da empresa. Tamanho: 14 caracteres. String.	Não	Object
expire_at	Data de vencimento do boleto. Formato: YYYY-MM-DD	Sim	String
discount	Define dados de desconto sobre a cobrança. Atributos de discount   type*, // Tipo do desconto (String). Valores permitidos: currency: o desconto será informado em centavos; percentage: o desconto será informado em porcentagem.     value*, // Valor do desconto (Integer). Se o tipo do desconto for currency, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja percentage, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos: 1) currency // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar 599; 2) percentage // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar 1500.	Não	Object
conditional_discount	Define desconto condicional que é válido até uma data específica. Se o pagamento não for efetuado até aquela data, o desconto é invalidado. Atributos de conditional_discount   type*, // Tipo do desconto (String). Valores permitidos: currency: o desconto será informado em centavos; percentage: o desconto será informado em porcentagem.     value*, // Valor do desconto (Integer). Se o tipo do desconto for currency, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja percentage, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos: 1) currency // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar 599; 2) percentage // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar 1500.     until_date*, // Data máxima que o desconto será concedido. (String). Formato: YYYY-MM-DD	Não	Object
configurations	Permite incluir no boleto multa e juros caso seja pago após o vencimento. Atributos de configurations   fine, // valor cobrado de multa após o vencimento. Por exemplo: se você quiser 2%, você deve informar 200. Mínimo de 0 e máximo de 1000. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem multa, utilize 0 como valor do atributo fine     interest, // valor cobrado de juros por dia após a data de vencimento. Por exemplo: se você quiser 0,033%, você deve informar 33. Mínimo de 0 e máximo de 330. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem juros, utilize 0 como valor do atributo interest	Não	Object

• valor obrigatório

2. Criação do Bolix, boleto com pix, em Two Steps (Dois passos)

1. Crie a transação, informando o item/produto/serviço, valor, quantidade, etc;

2. Associe à forma de pagamento via boleto, informando o charge_id da transação e os dados do cliente.

O restante desta página apresenta os procedimentos detalhados, mas você precisa instalar uma de nossas bibliotecas em seu servidor para executar os códigos de exemplo. Certifique-se de que a SDK da Gerencianet foi instalada.

 

---

 

 

2.1. Criar transação

Primeiramente, precisamos gerar a transação (também chamada de "cobrança"). É neste momento que será informado o nome do item/produto/serviço, valor da transação, quantidade, dentre outras informações possíveis.

Após criá-la, será retornado o charge_id, que é o identificador único da transação e que será utilizado para associar à forma de pagamento.

Assim que essa transação é criada, ela recebe o status new, que significa que a cobrança foi gerada e está aguardando definição da forma de pagamento. Essa cobrança somente terá seu status alterado quando o integrador definir sua forma de pagamento.

Para gerar uma transação, você deve enviar uma requisição POST para a rota /v1/charge.

O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:

PHP·

NodeJS·

Python·

Java·

.NET·

Go·

Ruby·

Delphi

 

<?php
 
require __DIR__ . '/../../vendor/autoload.php';

use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;

$file = file_get_contents(__DIR__ . '/../config.json');
$options = json_decode($file, true);
unset($options['pix_cert']);
 
$item_1 = [
    'name' => 'Item 1', // nome do item, produto ou serviço
    'amount' => 1, // quantidade
    'value' => 1000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.)
];
 
$item_2 = [
    'name' => 'Item 2', // nome do item, produto ou serviço
    'amount' => 2, // quantidade
    'value' => 2000 // valor (2000 = R$ 20,00)
];
 
$items =  [
    $item_1,
    $item_2
];

// Exemplo para receber notificações da alteração do status da transação:
// $metadata = ['notification_url'=>'sua_url_de_notificacao_.com.br']
// Outros detalhes em: https://dev.gerencianet.com.br/docs/notificacoes

// Como enviar seu $body com o $metadata
// $body  =  [
//    'items' => $items,a
//    'metadata' => $metadata
// ];

$body  =  [
    'items' => $items
];

try {
    $api = new Gerencianet($options);
    $charge = $api->createCharge([], $body);
 
    print_r($charge);
} catch (GerencianetException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch (Exception $e) {
    print_r($e->getMessage());
}

Dados de entrada e saída na criação da transação:

Dados de entrada·

Dados de saída

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 8900,
      "amount": 1
    }
  ]
}

 

 

a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:

 

"id": "/Charge"
    "items"
        "name"
        "value"
        "amount"
        "marketplace"
            "payee_code"
            "percentage"
    "shippings"
        "name"
        "value"
        "payee_code"
    "metadata"
        "custom_id"
        "notification_url"

 

Para verificar mais detalhes, acesse aqui e explore em nosso Playground.

 

 

b) Atributos que podem ser utilizados para criar uma transação:

Atributo	Descrição	Obrigatório	Tipo
items	Item que está sendo vendido. Uma mesma transação pode possuir ilimitados itens. Atributos de items   name* // Nome do item, produto ou serviço. Mínimo de 1 caractere e máximo de 255 caracteres (String).     value* // Valor, em centavos. Ex: R$ 10,00 = 1000. Integer.     amount // Quantidade. Integer (padrão: 1)	Sim	Array
shippings	Determina o(s) valor(es) de frete(s) de uma transação. Uma mesma transação pode possuir ilimitados valores de frete. Atributos de shippings   name* // Rótulo do frete. Máximo de 255 caracteres. String.     value* // Valor do frete, em centavos (1990 equivale a R$19,90). Integer.     payeeCode, // código da conta Gerencianet que receberá o repasse do valor total do frete - refere-se ao "identificador da conta" Gerencianet (onde localizar meu identificador?) (String)	Não	Array
metadata	Define dados específicos da transação. Atributos de metadata   custom_id // Permite associar uma transação Gerencianet a uma ID específica de seu sistema ou aplicação, permitindo identificá-la caso você possua uma identificação específica e queira mantê-la. Máximo de 255 caracteres. String/null.     notification_url // Endereço de sua URL válida que receberá as notificações de mudanças de status das transações. Máximo de 255 caracteres. String/null.	Não	Object

* valor obrigatório

 

 

---

 

 

2.2. Associar à forma de pagamento via boleto

Com a transação gerada com sucesso, agora vamos associar com a forma de pagamento banking_billet (boleto bancário) e assim gerar o Bolix. Para tal, deverá ser informado o charge_id obtido ao criar a transação.

Neste momento, ao definir boleto bancário como forma de pagamento da transação, seu status será alterado de new para waiting. Isso significa que a forma de pagamento foi selecionada e está aguardando a confirmação do pagamento.

Para associar à forma de pagamento, você deve enviar uma requisição POST para a rota /v1/charge/:id/pay, onde :id é o charge_id da transação desejada.

O boleto bancário que será gerado já vem com a forma de pagamento Pix inclusa.

O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:

PHP·

NodeJs·

Python·

Java·

.NET·

Go·

Ruby·

Delphi

 

<?php
 
require __DIR__ . '/../../vendor/autoload.php';

use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;

$file = file_get_contents(__DIR__ . '/../config.json');
$options = json_decode($file, true);
unset($options['pix_cert']);
 
// $charge_id refere-se ao ID da transação gerada anteriormente
$params = [
  'id' => $charge_id
];
 
$customer = [
  'name' => 'Gorbadoc Oldbuck', // nome do cliente
  'cpf' => '94271564656' , // cpf válido do cliente
  'phone_number' => '5144916523' // telefone do cliente
];
 
$bankingBillet = [
  'expire_at' => '2022-12-12', // data de vencimento do boleto (formato: YYYY-MM-DD)
  'customer' => $customer
];
 
$payment = [
  'banking_billet' => $bankingBillet // forma de pagamento (banking_billet = boleto)
];
 
$body = [
  'payment' => $payment
];
 
try {
    $api = new Gerencianet($options);
    $charge = $api->payCharge($params, $body);
 
    print_r($charge);
} catch (GerencianetException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch (Exception $e) {
    print_r($e->getMessage());
}

 

Dados de entrada e saída na criação da transação:

Dados de entrada·

Dados de saída

{
  "payment": {
    "banking_billet": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "phone_number": "5144916523",
        "address": {
          "street": "Avenida Juscelino Kubitschek",
          "number": "909",
          "neighborhood": "Bauxita",
          "zipcode": "35400000",
          "city": "Ouro Preto",
          "complement": "",
          "state": "MG"
        }
      },
      "expire_at": "2022-12-30",
      "configurations": {
        "fine": 200,
        "interest": 33
      },
      "message": "Pague pelo código de barras ou pelo QR Code"
    }
  }
}

 

 

a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:

 

"id": "/Pay",
    "payment"
        "banking_billet"
            "customer"
                "name"
                "cpf"
                "email"
                "phone_number"
                "birth"
                "address"
                    "street"
                    "number"
                    "neighborhood"
                    "zipcode"
                    "city"
                    "complement"
                    "state"
                "juridical_person"
                    "corporate_name"
                    "cnpj"
            "expire_at"
            "discount"
                "type"
                    "percentage",
                    "currency"
                "value"
            "conditional_discount"
                "type"
                    "percentage",
                    "currency"
                "value"
                "until_date"
            "configurations"
                "fine"
                "interest"
            "message"

 

Para verificar mais detalhes, acesse aqui e explore em nosso Playground.

 

 

b) Atributos que podem ser utilizados para gerar um Bolix, pix no boleto bancário:

Atributo	Descrição	Obrigatório	Tipo
payment	Tag raiz	Sim	Objeto Payment

 

Objeto Payment

Atributo	Descrição	Obrigatório	Tipo
banking_billet	Forma de pagamento através de "boleto bancário"	Sim	Objeto Banking_Billet

 

Objeto Banking_Billet

Atributo	Descrição	Obrigatório	Tipo
name	Nome do cliente. Mínimo de 1 caractere e máximo de 255.	Sim Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
cpf	CPF válido do cliente (sem pontos, vírgulas ou hífen). Tamanho: 11 caracteres.	Sim Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
email	Email do cliente. Máximo de 255 caracteres. Ex.: [email protected]	Não	String
phone_number	Telefone do cliente. Formato: sem pontos ou vírgulas, com DDD de 2 caracteres (9º dígito é opcional). Ex.: 11988887777	Não	String
birth	Data de nascimento do cliente. Formato: YYYY-MM-DD	Não	String
address	Endereço do cliente. Atributos de address   street* // nome da rua (Object)     number* // número (String/Integer)     neighborhood* // Bairro (String)     zipcode* // CEP (sem pontos ou hífen) (String)     city* // cidade (String)     complement // complemento (String/null)     state* // estado (2 caracteres) (Object)	Não	Object
juridical_person	Dados de pessoa jurídica Atributos de juridical_person   corporate_name* // Nome da razão social. Mínimo de 1 caractere e máximo de 255. String.     cnpj* // CNPJ da empresa. Tamanho: 14 caracteres. String.	Não	Object
expire_at	Data de vencimento do boleto. Formato: YYYY-MM-DD	Sim	String
discount	Define dados de desconto sobre a cobrança. Atributos de discount   type*, // Tipo do desconto (String). Valores permitidos: currency: o desconto será informado em centavos; percentage: o desconto será informado em porcentagem.     value*, // Valor do desconto (Integer). Se o tipo do desconto for currency, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja percentage, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos: 1) currency // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar 599; 2) percentage // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar 1500.	Não	Object
conditional_discount	Define desconto condicional que é válido até uma data específica. Se o pagamento não for efetuado até aquela data, o desconto é invalidado. Atributos de conditional_discount   type*, // Tipo do desconto (String). Valores permitidos: currency: o desconto será informado em centavos; percentage: o desconto será informado em porcentagem.     value*, // Valor do desconto (Integer). Se o tipo do desconto for currency, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja percentage, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos: 1) currency // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar 599; 2) percentage // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar 1500.     until_date*, // Data máxima que o desconto será concedido. (String). Formato: YYYY-MM-DD	Não	Object
configurations	Permite incluir no boleto multa e juros caso seja pago após o vencimento. Atributos de configurations   fine, // valor cobrado de multa após o vencimento. Por exemplo: se você quiser 2%, você deve informar 200. Mínimo de 0 e máximo de 1000. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem multa, utilize 0 como valor do atributo fine     interest, // valor cobrado de juros por dia após a data de vencimento. Por exemplo: se você quiser 0,033%, você deve informar 33. Mínimo de 0 e máximo de 330. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem juros, utilize 0 como valor do atributo interest	Não	Object
message	Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. Até 4 linhas contendo 100 caracteres em cada linha. String. O operador \n é utilizado para efetuar a quebra de linha.	Não	String

• valor obrigatório

 

3. Gerando um Bolix com o método de pagamento carnê

O carnê é um método de pagamento que gera um conjunto de transações (parcelas) com as mesmas informações de pagamento e do cliente em todas elas, as parcelas de um carnê vencem mensalmente, de acordo com a data definida pelo integrador. Para gerar um carnê, você precisa informar os seguintes dados:

• Itens (ou serviço) oferecido;
• Data de vencimento da 1ª parcela;
• Número de parcelas (repetições).

A seguir, um código de exemplo de criação de um Bolix com o método de pagamento carnê utilizando as SDK's disponíveis. Note que já estamos definindo os itens, os dados do cliente, data de vencimento da primeira parcela do carnê e a quantidade de repetições (em meses):

PHP·

NodeJS·

Python·

Java·

.NET·

Go·

Ruby·

Delphi

 

<?php

require __DIR__ . '/../../vendor/autoload.php';

use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;

$file = file_get_contents(__DIR__ . '/../config.json');
$options = json_decode($file, true);
unset($options['pix_cert']);

$item_1 = [
    'name' => 'Item 1', // nome do item, produto ou serviço
    'amount' => 1, // quantidade
    'value' => 1000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.)
];
 
$item_2 = [
    'name' => 'Item 2', // nome do item, produto ou serviço
    'amount' => 2, // quantidade
    'value' => 2000 // valor (2000 = R$ 20,00)
];
 
$items =  [
    $item_1,
    $item_2
];
 
$customer = [
  'name' => 'Gorbadoc Oldbuck', // nome do cliente
  'cpf' => '94271564656' , // cpf do cliente
  'phone_number' => '5144916523' // telefone do cliente
];

// Exemplo para receber notificações da alteração do status do carne.
// $metadata = ['notification_url'=>'sua_url_de_notificacao_.com.br']
// Outros detalhes em: https://dev.gerencianet.com.br/docs/notificacoes

// Como enviar seu $body com o $metadata
// $body = [
// 'items' => $items,
// 'customer' => $customer,
// 'expire_at' => '2022-12-02',
// 'repeats' => 5,
// 'split_items' => false,
// 'metadata' => $metadata
// ];

$body = [
  'items' => $items,
  'customer' => $customer,
  'expire_at' => '2022-12-02', // data de vencimento da primeira parcela do carnê
  'repeats' => 5, // número de parcelas do carnê
  'split_items' => false // Define se os itens do carnê serão divididos entre as parcelas (true), ou se o valor de cada parcela será o valor total dos itens (false)
];

try {
    $api = new Gerencianet($options);
    $carnet = $api->createCarnet([], $body);
 
    print_r($carnet);
} catch (GerencianetException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch (Exception $e) {
    print_r($e->getMessage());
}

Dados de entrada e saída na criação do Bolix com o método de pagamento carnê:

Dados de entrada·

Dados de saída

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 7500,
      "amount": 1
    }
  ],
  "customer": {
    "name": "Gorbadoc Oldbuck",
    "cpf": "94271564656",
    "phone_number": "5144916523"
  },
  "expire_at": "2022-12-20",
  "configurations": {
        "fine": 200,
        "interest": 33
      },
  "message": "Este carnê aceita o pagamento por QR Code Pix e por código de barras",
  "repeats": 3,
  "split_items": false
}

 

 

a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:

 

"id": "/Carnet"
    "items"
        "name"
        "value"
        "amount"
    "customer"
        "name"
        "cpf"
        "email"
        "phone_number"
        "birth"
        "address"
            "street"
            "number"
            "neighborhood"
            "zipcode"
            "city"
            "complement"
            "state"
        "juridical_person"
            "corporate_name"
            "cnpj"
    "expire_at"
    "repeats"
    "split_items"
    "metadata"
        "custom_id"
        "notification_url"
    "configurations"
        "fine"
        "interest"
    "message"
    "discount"
        "type"
            "percentage",
            "currency"
        "value"
    "conditional_discount"
        "type"
            "percentage",
            "currency"
        "value"
        "until_date"

 

Para verificar mais detalhes, acesse aqui e explore em nosso Playground.

 

 

b) Atributos que podem ser usados para criar um carnê:

Atributo	Descrição	Obrigatório	Tipo
items	Item que está sendo vendido. Uma mesma transação pode possuir ilimitados itens. Atributos de items   name* // Nome do item, produto ou serviço. Mínimo de 1 caractere e máximo de 255 caracteres (String).     value* // Valor, em centavos. Ex: R$ 10,00 = 1000. Integer.     amount // Quantidade. Integer (padrão: 1)	Sim	Object
customer	Dados pessoais do pagador. Atributos de customer   name* // nome (String)     cpf* // CPF do cliente (sem pontos, vírgulas ou hífen) (String)     email // Endereço de email válido do cliente (String)     phone_number // Telefone válido do cliente, sem caracteres especiais (String)     birth // Data de Nascimento (data válida em formato YYYY-MM-DD) (String)     address // Endereço do Cliente (Object) (mais informações)     juridical_person // Dados de pessoa jurídica (Object) (mais informações)	Sim	Object
expire_at	Data de vencimento do carnê. O intervalo das parcelas de um carnê é sempre de 1 (um) mês entre elas. Formato: YYYY-MM-DD	Sim	String
repeats	Número de parcelas do carnê. Mínimo de 2 parcelas e máximo de 12 parcelas	Sim	Integer
split_items	Dividir itens entre as parcelas. Define se os itens do carnê serão divididos entre as parcelas (true), ou se o valor de cada parcela será o valor total dos itens (false).	Não	Boolean
metadata	Define dados específicos da transação.   custom_id // Permite associar uma transação Gerencianet a uma ID específica de seu sistema ou aplicação, permitindo identificá-la caso você possua uma identificação específica e queira mantê-la. Máximo de 255 caracteres. String/null.     notification_url // Endereço de sua URL válida que receberá as notificações de mudanças de status das transações. Máximo de 255 caracteres. String/null.	Não	Object
configurations	Permite incluir no carnê multa e juros caso seja pago após o vencimento. Atributos de configurations   fine, // valor cobrado de multa após o vencimento. Por exemplo: se você quiser 2%, você deve informar 200. Mínimo de 0 e máximo de 1000. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem multa, utilize 0 como valor do atributo fine     interest, // valor cobrado de juros por dia após a data de vencimento. Por exemplo: se você quiser 0,33%, você deve informar 33. Mínimo de 0 e máximo de 330. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem juros, utilize 0 como valor do atributo interest	Não	Object
message	Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. Máximo de 80 caracteres. String.	Não	String
discount	Define dados de desconto sobre a cobrança. Atributos de discount   type*, // Tipo do desconto (String). Valores permitidos: currency: o desconto será informado em centavos; percentage: o desconto será informado em porcentagem.     value*, // Valor do desconto (Integer). Se o tipo do desconto for currency, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja percentage, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos: 1) currency // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar 599; 2) percentage // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar 1500.	Não	Object
conditional_discount	Define desconto condicional que é válido até uma data específica. Se o pagamento não for efetuado até aquela data, o desconto é invalidado. Atributos de conditional_discount   type*, // Tipo do desconto (String). Valores permitidos: currency: o desconto será informado em centavos; percentage: o desconto será informado em porcentagem.     value*, // Valor do desconto (Integer). Se o tipo do desconto for currency, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja percentage, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos: 1) currency // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar 599; 2) percentage // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar 1500.     until_date*, // Data máxima que o desconto será concedido. (String). Formato: YYYY-MM-DD	Não	Object

* valor obrigatório

 

Pagamento do Bolix realizado como Pessoa Jurídica (PJ)

O cliente associado à transação pode ser uma Pessoa Jurídica. Nesse caso, devem ser informados a Razão Social e o CNPJ da empresa pagadora dentro do atributo juridical_person.

Veja detalhes neste link sobre como gerar um pagamento para um cliente que seja Pessoa Jurídica (PJ).

 

Relação de todos os possíveis status de uma transação

Todas as transações possuem status, que representa a "situação" dessa transação. Portanto, é importante conhecer os possíveis status de uma transação na API para fornecer as devidas tratativas em seu sistema.

Confira neste link todos os detalhes dos possíveis status das transações.

 

Callbacks (notificações) das transações Bolix da API para seu sistema

As notificações permitem que você seja informado quando uma transação tiver seu status alterado. Dessa forma, você poderá identificar quando um boleto for pago, por exemplo.

Confira neste link todos os detalhes sobre como implementar a sua URL de notificação.

 

 

---

 

 

4. Outros endpoints Bolix

Existem outros endpoints e métodos relacionados a pagamento via boleto bancário e carnê que estão disponíveis na API e podem ser explorados pelo integrador. Confira a relação completa:

• Alterar data de vencimento de boleto bancário

• Cancelar determinada transação

• Alterar URL de notificação (notification_url) e/ou custom_id de transação

• Reenviar boleto bancário por e-mail

• Acrescentar informações ao histórico da transação

• Retornar informações sobre transação

• Retornar informações sobre um carnê

• Alterar URL de notificação (notification_url) e/ou custom_id de carnês

• Alterar data de vencimento de parcela do carnê

• Cancelar um carnê

• Cancelar parcela específica de carnê

• Reenviar carnê por e-mail

• Reenviar parcela específica de carnê por e-mail

• Acrescentar informações ao histórico do carnê

 

5. Próximos Passos

Existem outras soluções da API que permitem a utilização do Bolix com o método de pagamento por boleto bancário, quer conhecê-las?

• Assinaturas (cobrança recorrente)
• Marketplace (split)
• Link de Pagamento
• Módulos e Plugins Gerencianet

<?php
   require __DIR__ . '/../../vendor/autoload.php'; // caminho relacionado a SDK

   use Gerencianet\Exception\GerencianetException;
   use Gerencianet\Gerencianet;

   $clientId = 'informe_seu_client_id';// insira seu Client_Id, conforme o ambiente (Des ou Prod)
   $clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)

    $options = [
        'client_id' => $clientId,
        'client_secret' => $clientSecret,
        'sandbox' => true // altere conforme o ambiente (true = homologação e false = producao)
    ];
    
   $item_1 = [
       'name' => 'Item 1', // nome do item, produto ou serviço
       'amount' => 1, // quantidade
       'value' => 1000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.)
   ];
   $items = [
       $item_1
   ];
   $metadata = array('notification_url'=>'sua_url_de_notificacao_.com.br'); //Url de notificações onde vamos notificá-lo, independente se for pago pelo código de barras do boleto quanto pelo QR Code.
   $customer = [
       'name' => 'Gorbadoc Oldbuck', // nome do cliente
       'cpf' => '94271564656', // cpf válido do cliente
       'phone_number' => '5144916523', // telefone do cliente
   ];
   $discount = [ // configuração de descontos
       'type' => 'currency', // tipo de desconto a ser aplicado
       'value' => 599 // valor de desconto 
   ];
   $configurations = [ // configurações de juros e mora
       'fine' => 200, // porcentagem de multa
       'interest' => 33 // porcentagem de juros
   ];
   $conditional_discount = [ // configurações de desconto condicional
       'type' => 'percentage', // seleção do tipo de desconto 
       'value' => 500, // porcentagem de desconto
       'until_date' => '2019-08-30' // data máxima para aplicação do desconto
   ];
   $bankingBillet = [
       'expire_at' => '2022-09-01', // data de vencimento do titulo
       'message' => 'Pague pelo código de barras ou pelo QR Code', // mensagem a ser exibida no boleto
       'customer' => $customer,
       'discount' =>$discount,
       'conditional_discount' => $conditional_discount
   ];
   $payment = [
       'banking_billet' => $bankingBillet // forma de pagamento (banking_billet = Bolix)
   ];
   $body = [
       'items' => $items,
       'metadata' =>$metadata,
       'payment' => $payment
   ];
   try {
     $api = new Gerencianet($options);
     $pay_charge = $api->oneStep([],$body);
     echo '<pre>';
     print_r($pay_charge);
     echo '<pre>';
     
    } catch (GerencianetException $e) {
       print_r($e->code);
       print_r($e->error);
       print_r($e->errorDescription);
   } catch (Exception $e) {
       print_r($e->getMessage());
   }

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 5990,
      "amount": 1
    }
  ],
  "payment": {
    "banking_billet": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "phone_number": "5144916523",
        "address": {
          "street": "Avenida Juscelino Kubitschek",
          "number": "909",
          "neighborhood": "Bauxita",
          "zipcode": "35400000",
          "city": "Ouro Preto",
          "complement": "",
          "state": "MG"
        }
      },
      "expire_at": "2022-12-15",
      "configurations": {
        "fine": 200,
        "interest": 33
      },
      "message": "Pague pelo código de barras ou pelo QR Code"
    }
  }
}

"OneStep": "/Charge/one-step"
    "items"
        "name"
        "value"
        "amount"
        "marketplace"
            "payee_code"
            "percentage"
    "shippings"
        "name"
        "value"
        "payee_code"
    "metadata"
        "custom_id"
        "notification_url"
    "payment"
        "banking_billet"
            "customer"
                "name"
                "cpf"
                "email"
                "phone_number"
                "birth"
                "address"
                    "street"
                    "number"
                    "neighborhood"
                    "zipcode"
                    "city"
                    "complement"
                    "state"
                "juridical_person"
                    "corporate_name"
                    "cnpj"
            "expire_at"
            "discount"
                "type"
                    "percentage",
                    "currency"
                "value"
            "conditional_discount"
                "type"
                    "percentage",
                    "currency"
                "value"
                "until_date"
            "configurations"
                "fine"
                "interest"
            "message"

<?php
 
require __DIR__ . '/../../vendor/autoload.php';

use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;

$file = file_get_contents(__DIR__ . '/../config.json');
$options = json_decode($file, true);
unset($options['pix_cert']);
 
$item_1 = [
    'name' => 'Item 1', // nome do item, produto ou serviço
    'amount' => 1, // quantidade
    'value' => 1000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.)
];
 
$item_2 = [
    'name' => 'Item 2', // nome do item, produto ou serviço
    'amount' => 2, // quantidade
    'value' => 2000 // valor (2000 = R$ 20,00)
];
 
$items =  [
    $item_1,
    $item_2
];

// Exemplo para receber notificações da alteração do status da transação:
// $metadata = ['notification_url'=>'sua_url_de_notificacao_.com.br']
// Outros detalhes em: https://dev.gerencianet.com.br/docs/notificacoes

// Como enviar seu $body com o $metadata
// $body  =  [
//    'items' => $items,a
//    'metadata' => $metadata
// ];

$body  =  [
    'items' => $items
];

try {
    $api = new Gerencianet($options);
    $charge = $api->createCharge([], $body);
 
    print_r($charge);
} catch (GerencianetException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch (Exception $e) {
    print_r($e->getMessage());
}

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 8900,
      "amount": 1
    }
  ]
}

"id": "/Charge"
    "items"
        "name"
        "value"
        "amount"
        "marketplace"
            "payee_code"
            "percentage"
    "shippings"
        "name"
        "value"
        "payee_code"
    "metadata"
        "custom_id"
        "notification_url"

<?php
 
require __DIR__ . '/../../vendor/autoload.php';

use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;

$file = file_get_contents(__DIR__ . '/../config.json');
$options = json_decode($file, true);
unset($options['pix_cert']);
 
// $charge_id refere-se ao ID da transação gerada anteriormente
$params = [
  'id' => $charge_id
];
 
$customer = [
  'name' => 'Gorbadoc Oldbuck', // nome do cliente
  'cpf' => '94271564656' , // cpf válido do cliente
  'phone_number' => '5144916523' // telefone do cliente
];
 
$bankingBillet = [
  'expire_at' => '2022-12-12', // data de vencimento do boleto (formato: YYYY-MM-DD)
  'customer' => $customer
];
 
$payment = [
  'banking_billet' => $bankingBillet // forma de pagamento (banking_billet = boleto)
];
 
$body = [
  'payment' => $payment
];
 
try {
    $api = new Gerencianet($options);
    $charge = $api->payCharge($params, $body);
 
    print_r($charge);
} catch (GerencianetException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch (Exception $e) {
    print_r($e->getMessage());
}

{
  "payment": {
    "banking_billet": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "phone_number": "5144916523",
        "address": {
          "street": "Avenida Juscelino Kubitschek",
          "number": "909",
          "neighborhood": "Bauxita",
          "zipcode": "35400000",
          "city": "Ouro Preto",
          "complement": "",
          "state": "MG"
        }
      },
      "expire_at": "2022-12-30",
      "configurations": {
        "fine": 200,
        "interest": 33
      },
      "message": "Pague pelo código de barras ou pelo QR Code"
    }
  }
}

"id": "/Pay",
    "payment"
        "banking_billet"
            "customer"
                "name"
                "cpf"
                "email"
                "phone_number"
                "birth"
                "address"
                    "street"
                    "number"
                    "neighborhood"
                    "zipcode"
                    "city"
                    "complement"
                    "state"
                "juridical_person"
                    "corporate_name"
                    "cnpj"
            "expire_at"
            "discount"
                "type"
                    "percentage",
                    "currency"
                "value"
            "conditional_discount"
                "type"
                    "percentage",
                    "currency"
                "value"
                "until_date"
            "configurations"
                "fine"
                "interest"
            "message"

<?php

require __DIR__ . '/../../vendor/autoload.php';

use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;

$file = file_get_contents(__DIR__ . '/../config.json');
$options = json_decode($file, true);
unset($options['pix_cert']);

$item_1 = [
    'name' => 'Item 1', // nome do item, produto ou serviço
    'amount' => 1, // quantidade
    'value' => 1000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.)
];
 
$item_2 = [
    'name' => 'Item 2', // nome do item, produto ou serviço
    'amount' => 2, // quantidade
    'value' => 2000 // valor (2000 = R$ 20,00)
];
 
$items =  [
    $item_1,
    $item_2
];
 
$customer = [
  'name' => 'Gorbadoc Oldbuck', // nome do cliente
  'cpf' => '94271564656' , // cpf do cliente
  'phone_number' => '5144916523' // telefone do cliente
];

// Exemplo para receber notificações da alteração do status do carne.
// $metadata = ['notification_url'=>'sua_url_de_notificacao_.com.br']
// Outros detalhes em: https://dev.gerencianet.com.br/docs/notificacoes

// Como enviar seu $body com o $metadata
// $body = [
// 'items' => $items,
// 'customer' => $customer,
// 'expire_at' => '2022-12-02',
// 'repeats' => 5,
// 'split_items' => false,
// 'metadata' => $metadata
// ];

$body = [
  'items' => $items,
  'customer' => $customer,
  'expire_at' => '2022-12-02', // data de vencimento da primeira parcela do carnê
  'repeats' => 5, // número de parcelas do carnê
  'split_items' => false // Define se os itens do carnê serão divididos entre as parcelas (true), ou se o valor de cada parcela será o valor total dos itens (false)
];

try {
    $api = new Gerencianet($options);
    $carnet = $api->createCarnet([], $body);
 
    print_r($carnet);
} catch (GerencianetException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch (Exception $e) {
    print_r($e->getMessage());
}

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 7500,
      "amount": 1
    }
  ],
  "customer": {
    "name": "Gorbadoc Oldbuck",
    "cpf": "94271564656",
    "phone_number": "5144916523"
  },
  "expire_at": "2022-12-20",
  "configurations": {
        "fine": 200,
        "interest": 33
      },
  "message": "Este carnê aceita o pagamento por QR Code Pix e por código de barras",
  "repeats": 3,
  "split_items": false
}

"id": "/Carnet"
    "items"
        "name"
        "value"
        "amount"
    "customer"
        "name"
        "cpf"
        "email"
        "phone_number"
        "birth"
        "address"
            "street"
            "number"
            "neighborhood"
            "zipcode"
            "city"
            "complement"
            "state"
        "juridical_person"
            "corporate_name"
            "cnpj"
    "expire_at"
    "repeats"
    "split_items"
    "metadata"
        "custom_id"
        "notification_url"
    "configurations"
        "fine"
        "interest"
    "message"
    "discount"
        "type"
            "percentage",
            "currency"
        "value"
    "conditional_discount"
        "type"
            "percentage",
            "currency"
        "value"
        "until_date"

Como Gerar Bolix API Gerencianet, Glossário com os termos mais comuns relacionados a API e Integrações no gerencianet, Cursos online completos e gratuitos, curso php 8, curso node.js, curso de react, curso de react.js, curso de arduino, curso de html, curso de css, curso javascript, Maykon Silveira, criando api com Maykon Silveira, curso de sheep php, sheep php, Gerando Boletos com QRCODE PIX no gerencianet treinamento completo