Pular para o conteúdo principal

Boleto

Passo a passo para gerar boleto bancário na API Efí


Atualmente disponibilizamos dois procedimentos para a criação de uma transação do tipo Boleto bancário. Na primeira delas o titulo é criado em um passo único, assim fora convencionado como One Step. A segunda opção de criação da transação se da em dois passos, sendo assim convencionada como Two Steps.

Criação de Boleto (Bolix) 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.

Permite criar uma transação já associando um método de pagamento, podendo ser boleto bancário ou cartão de crédito, em apenas uma etapa.

Importante!

Para garantir que a criação de transações via One Step ocorra sem problemas, é necessário atualizar a sua SDK. Todos os arquivos necessários para essa atualização estão disponíveis através de nosso repositório e na nossa documentação.


Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"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"
POST /v1/charge/one-step
Requer ativação da API de Emissão de cobranças em sua aplicação


Requisição

{
"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": "2023-12-15",
"configurations": {
"fine": 200,
"interest": 33
},
"message": "Usando o atributo message, este conteúdo é exibido no campo OBSERVAÇÃO da cobrança emitida via API
e também no campo OBSERVAÇÃO DO VENDEDOR nos e-mails de cobrança enviados ao cliente
É possível utilizar até 4 linhas de conteúdo, com no máximo 100 caracteres por linha
Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê"
}
}
}

Respostas

As respostas abaixo representam Sucesso do consumo.

{
"code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
"data": {
"barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // linha digitável do boleto
"pix":{
"qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode ou copia e cola
"qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code imagem
},
"link": "link_https_para_acesso_o_bolix", // link responsivo do Bolix gerado
"billet_link":"link_https_para_acesso_o_bolix", // link do Bolix gerado
"pdf": {
"charge": "link_https_do_pdf_da_cobranca" // link do PDF do Bolix
},
"expire_at": "2023-12-15", // data de vencimento do boleto no seguinte formato: 2022-12-15 (ou seja, equivale a 15/12/2022)
"charge_id": numero_charge_id, // número da ID referente à transação gerada
"status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento ("waiting" equivale a "aguardando")
"total": 5990, // valor, em centavos. Por exemplo: 5990 (equivale a R$ 59,90)
"payment": "banking_billet" // forma de pagamento associada à esta transação ("banking_billet" equivale a "boleto bancário")
}
}

Informação

Ao usar o atributo message, deve-se utilizar o operador \n para efetuar a "quebra" da linha. No código que disponibilizamos já incluímos este operador.


Criação de Boleto em Two Steps (Dois passos)

Nesta opção é necessário seguir dois passos, enviando o body da requisição com todos os atributos mínimos obrigatórios para a emissão da cobrança.

  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 Efí foi instalada.

1. Criar transação

Para começar, o primeiro passo é gerar a transação, também conhecida como “cobrança”. Nesse momento, você informará o nome do item, produto ou serviço, o valor da transação, a quantidade e outras informações relevantes.

Após a criação da cobrança, você receberá um charge_idque é um identificador único para essa transação. Esse será usado para associar a forma de pagamento.

Inicialmente, a transação terá o status new, o que significa que a cobrança foi gerada e está aguardando a definição da forma de pagamento. O status será atualizado somente quando o método de pagamento for escolhido pela pessoa integradora.

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

Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"items"  
"name"
"value"
"amount"
"marketplace"
"payee_code"
"percentage"
"shippings"
"name"
"value"
"payee_code"
"metadata"
"custom_id"
"notification_url"
POST /v1/charge
Requer ativação da API de Emissão de cobranças em sua aplicação


Requisição

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

Respostas

As respostas abaixo representam Sucesso do consumo.

{
"code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
"data": {
"charge_id": numero_charge_id, // número da ID referente à transação gerada
"status": "new", // cobrança gerada, aguardando definição da forma de pagamento
"total": 8900, // valor total da transação (em centavos, sendo 8900 = R$89,00)
"custom_id": null, // identificador próprio opcional
"created_at": "2021-06-01 14:58:46" // data e hora da criação da transação
}
}

2. Associar à forma de pagamento via boleto

Após gerar a transação com sucesso, o próximo passo é associá-la à forma de pagamento desejada - neste caso, será o banking_billet(boleto bancário). Para isso, você precisará informar o charge_id que foi obtido ao criar a transação.

Ao selecionar o boleto bancário como forma de pagamento, o status da transação será alterado de new para waitingEssa mudança indica que a forma de pagamento foi escolhida 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.

Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"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"
POST /v1/charge/:id/pay
Requer ativação da API de Emissão de cobranças em sua aplicação


Requisição

{
"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": "2023-12-30",
"configurations": {
"fine": 200,
"interest": 33
},
"message": "Pague pelo código de barras ou pelo QR Code"
}
}
}

Respostas

As respostas abaixo representam Sucesso do consumo.

{
"code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
"data": {
"barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // linha digitável do boleto
"pix":{
"qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode ou copia e cola
"qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code imagem
},
"link": "link_https_para_acesso_o_bolix", // link responsivo do Bolix gerado
"billet_link":"link_https_para_acesso_o_bolix", // link do Bolix gerado
"pdf": {
"charge": "link_https_do_pdf_da_cobranca" // link do PDF do Bolix
},
"expire_at": "2023-12-30", // data de vencimento do boleto no seguinte formato: 2022-12-15 (ou seja, equivale a 15/12/2022)
"charge_id": numero_charge_id, // número da ID referente à transação gerada
"status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento ("waiting" equivale a "aguardando")
"total": 8900, // valor, em centavos. Por exemplo: 5990 (equivale a R$ 59,90)
"payment": "banking_billet" // forma de pagamento associada à esta transação ("banking_billet" equivale a "boleto bancário")
}
}

Pagamento realizado como Pessoa Jurídica (PJ)

O cliente associado à transação pode ser uma Pessoa Jurídica. Nesse caso, é necessário informar a Razão Social e o CNPJ da empresa pagadora no atributo juridical_person.


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

Todas as transações possuem um status que representa sua “situação”. É importante conhecer os possíveis status das transações na API para lidar adequadamente com elas em seu sistema.

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


Callbacks (notificações) das transações 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 aqui todos os detalhes sobre como implementar a sua URL de notificação.


Retornar informações de transação existente

Para retornar informações de uma transação (como um boleto, por exemplo), você deve enviar uma requisição GET para a rota /v1/charge/:id.

GET /v1/charge/:id
Requer ativação da API de Emissão de cobranças em sua aplicação


Requisição

Parâmetro de entrada: informe a "charge_id" da transação desejada

Respostas

As respostas abaixo representam Sucesso(200) do consumo.

{
"code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
"data": {
"charge_id": 1234567, // número da ID referente à transação gerada
"total": 8900, // valor total da transação (em centavos, sendo 8900 = R$89,00)
"status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento (o termo "waiting" equivale a "aguardando")
"custom_id": null, // identificador próprio opcional
"created_at": "2022-10-31 10:18:21", // data e hora da criação da transação
"notification_url": null,
"items": [
{
"name": "Meu Produto", // nome de seu item, produto ou serviço
"value": 8900, // valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00)
"amount": 1 // quantidade do item ou produto
}
],
"history": [
{
"message": "Cobrança criada",
"created_at": "2222-10-31 10:18:21"
},
{
"message": "Pagamento via boleto aguardando confirmação",
"created_at": "2022-10-31 10:19:05"
}
],
"customer": {
"name": "Gorbadoc Oldbuck",
"cpf": "94271564656",
"email": "[email protected]",
"phone_number": "5144916523",
"address": {
"street": "Avenida Juscelino Kubitschek",
"number": "909",
"complement": null,
"neighborhood": "Bauxita",
"city": "Ouro Preto",
"state": "MG",
"zipcode": "35400000"
}
},
"payment": {
"method": "banking_billet", // forma de pagamento da cobrança (banking_billet equivale a boleto bancário)
"created_at": "2022-10-31 10:19:05",
"message": "Usando o atributo message, este conteúdo é exibido no campo OBSERVAÇÃO da cobrança emitida via API
e também no campo OBSERVAÇÃO DO VENDEDOR nos e-mails de cobrança enviados ao cliente
É possível utilizar até 4 linhas de conteúdo, com no máximo 100 caracteres por linha
Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê",
"banking_billet": {
"barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
"pix":{
"qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode ou copia e cola
"qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code imagem
},
"link": "link_https_para_acesso_ao_boleto", // link do Bolix gerado
"pdf": {
"charge": "link_https_do_pdf_da_cobranca" // link do PDF do Bolix
},
"expire_at": "2023-12-30", // data de vencimento da cobrança no seguinte formato: 2022-12-30 (ou seja, equivale a 30/12/2022)
"configurations": {
"interest": 33, // valor cobrado de juros por dia após a data de vencimento (neste caso, 33 equivale a 0,033%)
"fine": 200 // valor cobrado de multa após o vencimento (neste caso, 200 equivale a 2%)
}
}
}
}
}

Incluir "notification_url" e "custom_id" em uma transação existente

Você pode definir ou modificar as informações enviadas na propriedade metadata da transação a qualquer momento. Este endpoint é de extrema importânciapara atualizar a URL de notificação vinculada às transações ou modificar o custom_id associado anteriormente.

Para alterar a notification_url e/ou custom_id de uma transação, você deve enviar uma requisição PUT para a rota /v1/charge/:id/metadata.

Casos de uso deste endpoint:
  1. A pessoa integradora alterou o IP do servidor que estava associado à URL de notificação das transações;
  2. A pessoa integradora atualizou a URL de notificação para as novas transações criadas (createCharge), mas precisa atualizar as transações anteriores (updateChargeMetadata) que foram geradas e que estão associadas com a URL incorreta/desatualizada;
  3. Foi instalado SSL (https) no servidor do cliente e mesmo que o cliente defina uma regra de redirecionamento 301 ou 302, será necessário definir a nova URL nas transações que estão usando a URL "antiga";
  4. A pessoa integradora gerou cobranças sem informar a URL de notificação ao enviar a requisição de criação da transação;
  5. Modificar ou acrescentar uma informação junto ao atributo custom_id associado às transações geradas previamente;
  6. Dentre outros possíveis cenários.
PUT /v1/charge/:id/metadata
Requer ativação da API de Emissão de cobranças em sua aplicação


Requisição

{
"notification_url": 'http://seu_dominio.com/notification',
"custom_id": 'REF0001'
}

Respostas

As respostas abaixo representam Sucesso(200) do consumo.

{
"code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
}

Alterar data de vencimento de uma transação existente

Possibilita alterar a data de vencimento de uma transação cuja forma de pagamento seja banking_billet (boleto bancário) e que ainda não foi paga.

Para tal, é necessário que você informe o charge_id da transação desejada e a nova data de vencimento em formato YYYY-MM-DD dentro do atributo expire_at. Deve-se enviar uma requisição PUT para a rota /v1/charge/:id/billet.

Importante!

A nova data de vencimento deve ser pelo menos maior que a data atual.


PUT /v1/charge/:id/billet
Requer ativação da API de Emissão de cobranças em sua aplicação


Requisição

{
"expire_at": "2023-12-30"
}

Respostas

As respostas abaixo representam Sucesso(200) do consumo.

{
"code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
}

Cancelar uma transação existente

Uma transação pode ser cancelada apenas se ela possuir o status new, waiting, unpaid ou link.

Quando uma transação é cancelada, há apenas uma condição para que o status seja alterado novamente: se o cliente imprimir o boleto antes do integrador cancelar a transação, ele poderá efetuar o pagamento normalmente em uma agência bancária. Nesse caso, tanto a pessoa integradora quanto a pessoa pagadora receberão a confirmação do pagamento como de costume, e o status da cobrança será alterado de canceled para paid.

Para cancelar uma transação (por exemplo, cancelar um boleto), você deve enviar uma requisição PUT para a rota /v1/charge/:id/cancel.

PUT /v1/charge/:id/cancel
Requer ativação da API de Emissão de cobranças em sua aplicação


Requisição

Parâmetro de entrada: informe a "charge_id" da transação desejada

Respostas

As respostas abaixo representam Sucesso(200) do consumo.

{
"code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
}

Reenvio do boleto bancário para o email desejado

Se a transação for um boleto bancário banking_billet e estiver com o status waiting ou unpaid, é possível reenviar o boleto por e-mail.

Basta enviar o charge_id da transação e o endereço de e-mail válido para o qual deseja enviar o boleto.

Para reenviar um boleto por e-mail, você deve enviar uma requisição POST para a rota /v1/charge/:id/billet/resend.

POST /v1/charge/:id/billet/resend
Requer ativação da API de Emissão de cobranças em sua aplicação


Requisição

{
"email": "[email protected]"
}

Respostas

As respostas abaixo representam Sucesso do consumo.

{
"code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
}

Acrescentar descrição ao histórico de uma transação

O histórico de uma transação mostra todas as ações que ocorreram até o momento, mas as mensagens personalizadas não afetam a transação em si, apenas aparecem no histórico. Você pode visualizar o histórico da transação na interface ou usando o endpoint de detalhes da transação.

Para isso, basta enviar o identificador charge_id e a mensagem que deseja adicionar ao histórico da transação. A descrição deve ter entre 1 e 255 caracteres.

Para adicionar mensagens personalizadas no histórico de uma transação, você deve enviar uma requisição POST para a rota /v1/charge/:id/history.

POST /v1/charge/:id/history
Requer ativação da API de Emissão de cobranças em sua aplicação


Requisição

{
"description": "Camisa Polo tamanho G cor azul, cobrança Bolix, pix com boleto."
}

Respostas

As respostas abaixo representam Sucesso do consumo.

{
"code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
}

Definir que a transação será do tipo boleto balancete

Após a criação da transação, será o momento de definirmos que o boleto a ser gerado será do tipo balancete.

Para isso, você deve enviar uma requisição POST para a rota /v1/charge/:id/balance-sheet.

NOTA
É importante destacar que não há um padrão fixo para os itens exibidos no boleto balancete. A própria pessoa integradora poderá definir, através dos atributos adequados, a quantidade de colunas (até 4), linhas, textos e valores que serão mostrados no boleto. De forma resumida, a pessoa integradora trabalha com uma tabela construída em HTML, mas em formato JSON.

POST /v1/charge/:id/balance-sheet
Requer ativação da API de Emissão de cobranças em sua aplicação


Requisição

{
"title": "Balancete Demonstrativo - Periodo 25/06/2018 a 25/07/2018",
"body": [{
"header": "Demonstrativo de Consumo",
"tables": [{
"rows": [[{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "Despesa de condomínio:",
"colspan": 2
},
{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "Total lançado",
"colspan": 1
},
{
"align": "right",
"color": "#000000",
"style": "bold",
"text": "Rateio",
"colspan": 1
}],
[{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Serviço de Vigilância Contratado:",
"colspan": 2
},
{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 300,00",
"colspan": 1
},
{
"align": "right",
"color": "#000000",
"style": "normal",
"text": "R$ 75,00",
"colspan": 1
}],
[{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Serviço de Zeladoria Contratado:",
"colspan": 2
},
{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 130,00",
"colspan": 1
},
{
"align": "right",
"color": "#000000",
"style": "normal",
"text": "R$ 32,00",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Serviço de Jardinagem:",
"colspan": 2
},
{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 80,00",
"colspan": 1
},
{
"align": "right",
"color": "#000000",
"style": "normal",
"text": "R$ 20,00",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Tarifa Bancária:",
"colspan": 2
},
{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 10,00",
"colspan": 1
},
{
"align": "right",
"color": "#000000",
"style": "normal",
"text": "R$ 2,50",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Despesa condomínio:",
"colspan": 2
},
{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 800,00",
"colspan": 1
},
{
"align": "right",
"color": "#000000",
"style": "normal",
"text": "R$ 320,00",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Reforma de prédio:",
"colspan": 2
},
{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 350,00",
"colspan": 1
},
{
"align": "right",
"color": "#000000",
"style": "normal",
"text": "R$ 140,00",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Investimentos:",
"colspan": 1
},
{
"align": "center",
"color": "#000000",
"style": "bold",
"text": "Total:",
"colspan": 1
},
{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "R$ 1320,00",
"colspan": 1
},
{
"align": "right",
"color": "#000000",
"style": "bold",
"text": "R$ 450,00",
"colspan": 1
}], [{
"align": "center",
"color": "#000000",
"style": "bold",
"text": " ",
"colspan": 1
},{
"align": "center",
"color": "#000000",
"style": "bold",
"text": "Total:",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "R$ 350,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "bold",
"text": "R$ 140,00",
"colspan": 1
}]]
},
{
"rows": [[{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "Despesas de Consumo",
"colspan": 4
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Leitura de gás:",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "Data: 25/11/2017",
"colspan": 3
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Anterior",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Atual Consumo",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "g/l",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "Total",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "49,000000",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "63,000000",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "14,000000",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "bold",
"text": "R$ 53,50",
"colspan": 1
}]]
},
{
"rows": [[{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Leitura de água:",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "Data: 25/11/2017",
"colspan": 3
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Anterior",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Atual Consumo",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "m³",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "Total",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "112,500000",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "114,900000",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "2,400000",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "bold",
"text": "R$ 43,00",
"colspan": 1
}]]
},
{
"rows": [[{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Leitura de esgoto:",
"colspan": 1
},
{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "Data: 25/11/2017",
"colspan": 3
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Anterior",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Atual Consumo",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "m³",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "Total",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "0,000000",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "0,000000",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "0,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "bold",
"text": "R$ 34,40",
"colspan": 1
}]]
}, {
"rows": [[{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "Resumo do rateio",
"colspan": 4
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Despesas de condomínio",
"colspan": 2
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 450,00",
"colspan": 2
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Investimento",
"colspan": 2
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 140,00",
"colspan": 2
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Fundo de reserva 10%",
"colspan": 2
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 79,59",
"colspan": 2
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Leitura de gás",
"colspan": 2
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 53,50",
"colspan": 2
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Leitura de água",
"colspan": 2
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 43,00",
"colspan": 2
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Leitura de esgoto",
"colspan": 2
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 34,40",
"colspan": 2
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Garagens",
"colspan": 2
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 5,00",
"colspan": 2
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Taxa de administradora",
"colspan": 2
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 25,00",
"colspan": 2
}], [{
"align": "right",
"color": "#DC143C",
"style": "bold",
"text": "Total geral:",
"colspan": 2
}, {
"align": "left",
"color": "#DC143C",
"style": "bold",
"text": "R$ 823,49",
"colspan": 2
}]]
}]
},
{
"header": "Balancete Geral",
"tables": [{
"rows": [[{
"align": "left",
"color": "#DC143C",
"style": "bold",
"text": "RECEITAS",
"colspan": 4
}], [{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "RECEITAS DE CONDOMÍNIO",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "bold",
"text": "R$ 2.090,12",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "bold",
"text": "100,00%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Taxa de Condominio",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 1.030,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "49,28%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Investimentos",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 280,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "13,40%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Gás",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 50,73",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "2,43%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Garagens",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 23,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "1,10%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Reserva Técnica",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 183,19",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "8,67%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Água",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 249,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "11,91%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Esgoto",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 199,20",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "9,53%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Taxa Administradora",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 75,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "3,59%",
"colspan": 1
}]] }, {
"rows": [[{
"align": "left",
"color": "#DC143C",
"style": "bold",
"text": "DESPESAS",
"colspan": 4
}], [{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "DESPESAS DE CONDOMÍNIO",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "bold",
"text": "R$ 1.670,12",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "bold",
"text": "100,00%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "DESPESAS DE AQUISIÇÕES",
"colspan": 4
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Despesas de condomínio",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 800,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "47,90%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Reformas do prédio",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 350,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "20,96%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": " ",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "bold",
"text": "R$ 1.150,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "bold",
"text": "68,86%",
"colspan": 1
}]] } , {
"rows": [[{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "DESPESAS COM SERVIÇOS",
"colspan": 4
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Serviço de Vigilância Contratado",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 300,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "17,96%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Serviço de Zeladoria Contratado",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 130,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "7,78%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Serviço de Jardinagem",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 80,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "4,79%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": " ",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "bold",
"text": "R$ 510,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "bold",
"text": "30,54%",
"colspan": 1
}]]} , {
"rows": [[{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "DESPESAS BANCÁRIAS",
"colspan": 4
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Tarifa Bancária",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "normal",
"text": "R$ 10,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "0,60%",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": " ",
"colspan": 2
}, {
"align": "center",
"color": "#000000",
"style": "bold",
"text": "R$ 10,00",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "bold",
"text": "0,60%",
"colspan": 1
}]] } , {
"rows": [[{
"align": "left",
"color": "#DC143C",
"style": "bold",
"text": "Resumo de Prestação de Contas",
"colspan": 4
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "RECEITAS",
"colspan": 2
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 2.090,12",
"colspan": 2
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "DESPESAS",
"colspan": 2
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 1.670,00",
"colspan": 2
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": " ",
"colspan": 2
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "(Receitas - Despesas)R$ 420,12",
"colspan": 2
}]]} , {
"rows": [[{
"align": "left",
"color": "#DC143C",
"style": "bold",
"text": "Resumo de Saldos",
"colspan": 4
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Conta",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Saldo Anterior",
"colspan": 1
},{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Entradas Saídas",
"colspan": 1
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "Saldo Atual",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "BANCOS",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "21.816,28",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "2.090,12 1670,00",
"colspan": 2
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "22.236,40",
"colspan": 2
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Banco do Brasil",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "21.816,28",
"colspan": 1
}, {
"align": "left",
"color": "#000000",
"style": "normal",
"text": "2.090,12 1670,00",
"colspan": 2
}, {
"align": "right",
"color": "#000000",
"style": "normal",
"text": "22.236,40",
"colspan": 2
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": " ",
"colspan": 2
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "(Bancos + Caixa)R$ 22.236,40",
"colspan": 2
}]] } , {
"rows": [[{
"align": "left",
"color": "#DC143C",
"style": "bold",
"text": "Contas a Receber",
"colspan": 4
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Contas a Receber até 30/09/2017",
"colspan": 3
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "R$ 2.271,27",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Contas a Receber no Período de 01/10/17 até 30/10/2017",
"colspan": 3
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "R$ 549,31",
"colspan": 1
}], [{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Total de Contas a Receber",
"colspan": 3
}, {
"align": "left",
"color": "#000000",
"style": "bold",
"text": "R$ 2.820,58",
"colspan": 1
}]]
}]
}]
}

Respostas

Como resultado do consumo do código do boleto balancete, é possível visualizar um exemplo de layout do boleto do tipo balancete, conforme demonstrado na imagem:

banner


Importante!

As informações contidas no balancete não são utilizadas pela Efí. Recebemos o conteúdo da requisição do seu sistema/aplicação e apenas montamos a cobrança da forma que a pessoa integradora espera, seguindo o layout de exemplo acima. Ou seja, a Efí não valida as informações nem faz cálculos no balancete; apenas processa e organiza os dados dentro do layout especificado pela sua requisição à rota POST /charge/:id/balance-sheet.


Importante!
As requisições para o endpoint de balancete não devem exceder 300 KB (body da requisição).

Marcar como pago (baixa manual) uma determinada transação

Às vezes, os clientes pagam as cobranças de outras maneiras, como em dinheiro ou por depósito bancário. Na conta Efí, somente é possível confirmar manualmente as cobranças feitas por boletos ou carnês. As cobranças realizadas através de links de pagamento, mesmo que o pagamento seja feito por boleto, não podem ser confirmadas manualmente.

Importante!
Quando uma transação é marcada como paga, nenhum valor de pagamento é retornado via API. Descontos, multas e moras não serão aplicados automaticamente.

Conheça as duas maneiras de confirmar manualmente o pagamento de uma cobrança na Efí:

1. Por meio do painel Efí:

  • Faça login em sua conta Efí;
  • Acesse o menu “Receber” e, logo em seguida, “Gestão de cobranças”;
  • Selecione a opção “Boletos”;
  • Escolha a cobrança que deseja confirmar;
  • Em seguida, clique no botão azul "Marcar como pago".

Esta operação não possui cobrança de tarifas.

Observação
Não é possível confirmar manualmente o pagamento de cobranças que foram canceladas.

2. Por meio de requisição via API:

Apenas transações com status waiting ou unpaid podem ser confirmadas manualmente. Existem dois endpoints responsáveis pelas confirmações manuais de pagamento:

  • settleCharge : permite marcar como pago (baixa manual) uma determinada transação;
  • settleCarnetParcel : permite marcar como pago (baixa manual) uma determinada parcela de um carnê.
NOTA

As confirmações de pagamento podem ser:

  • Confirmações Automáticas: é o mecanismo padrão oferecido pela API por meio da URL de notificação. Ou seja, disparamos um POST para sua URL de notificação assim que houver uma mudança no status da transação, seu sistema recepciona essa informação e realiza as tratativas para as quais foi designado. Em outras palavras, o status paid estará contido na notificação que enviamos. Logo, o status da transação será paid.
  • Confirmações Manuais: representada pelos endpoints settleCharge e settleCarnetParcel. É quando o pagamento foi realizado por formas de pagamento alternativas (ex: pagamento em mãos) e o integrador efetuou a confirmação manual pelo painel Efí, via requisição à API ou pelo seu próprio sistema de gestão. Neste caso, o status da transação será settled.

  • Marcar como pago determinada transação

    Permite marcar como pago (baixa manual) uma determinada transação.

    Para marcar uma transação como paga (baixa manual), você deve enviar uma requisição PUT para a rota /v1/charge/:id/settle.

    PUT /v1/charge/:id/settle
    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    Parâmetro de entrada: informe a "charge_id" da transação desejada

    Respostas

    As respostas abaixo representam Sucesso(201) do consumo.

    {
    "code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
    }

    Atenção!
    Transações marcadas como pagas não geram movimentações financeiras em uma conta Efí, uma vez que o fluxo financeiro não ocorre sob controle da Efí.