Carnet

Step by step to generate a carnet in the Efí API

Creating Carnets

A carnet is a set of transactions (installments) generated in bulk with a predefined payment method. The installments of a carnet are due monthly, according to the date defined by the integrator. To generate a carnet, you need to provide the following data:

• Item: item being sold;
• Customer: personal data of the payer;
• Expire_at: Due date of the 1st installment of the carnet;
• Repeats: Number of installments (repetitions) of the carnet.

To generate a carnet, you must send a POST request to the /v1/carnet route with the number of installments and the mode of generation, along with the transaction and customer data.

Each generated carnet has a unique identifier called carnet_id, and each installment of this carnet also has a unique identifier called charge_id.

Hierarchical structure of Schema attributes that can be used:

/v1/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"  

POST /v1/carnet

Requires activation of the Billing API in your application

Request

Input data

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 7500,
      "amount": 1
    }
  ],
  "customer": {
    "name": "Gorbadoc Oldbuck",
    "cpf": "94271564656",
    "phone_number": "5144916523"
  },
  "expire_at": "2023-12-20",
  "configurations": {
        "fine": 200,
        "interest": 33
      },
  "message": "Este é um espaço de até 80 caracteres para informar algo a seu cliente",
  "repeats": 3,
  "split_items": false
}

Responses

The responses below represent consumption Success.

🟢 200 (Carnet with Bolix)

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "carnet_id": 12345, // unique identifier of the carnet
    "status": "up_to_date", // carnet is up to date, no installment is overdue
    "cover": "https_link_cover_of_carnet", // link to the cover of the carnet
    "link": "https_link_of_carnet", // responsive link of the carnet according to the installments
    "carnet_link": "https_link_of_carnet", // link to the carnet according to the installments
    "pdf": {
      "carnet": "https_link_pdf_of_carnet", // link to the PDF of the carnet according to the installments
      "cover": "https_link_pdf_cover_of_carnet" // link to the PDF of the cover of the carnet
    },
    "charges": [
      {
        "charge_id": 511813, // unique identifier of the first installment of the carnet
        "parcel": "1", // installment number of the carnet
        "status": "waiting", // selected payment method, waiting for payment confirmation
        "value": 7500, // value in cents of the first installment of the carnet (7500 equals $75.00)
        "expire_at": "2023-12-20", // due date of the carnet installment in the format: 2023-12-20 (equals 20/12/2023)
        "url": "https_link_first_page", // link to the first installment page of the carnet
        "parcel_link": "https_link_first_page", // responsive link to the first installment page of the carnet
        "pdf": {
          "charge": "https_link_first_page" // link to the PDF of the first installment page of the carnet
        },
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // barcode of the first installment
        "pix": {
          "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode or copy and paste
          "qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code image
        }
      },
      {
        "charge_id": 511814, // unique identifier of the second installment of the carnet
        "parcel": "2", // installment number of the carnet
        "status": "waiting", // selected payment method, waiting for payment confirmation
        "value": 7500, // value in cents of the second installment of the carnet (7500 equals $75.00)
        "expire_at": "2023-01-20", // due date of the carnet installment in the format: 2023-01-20 (equals 20/01/2023)
        "url": "https_link_second_page", // link to the second installment page of the carnet
        "parcel_link": "https_link_second_page", // responsive link to the second installment page of the carnet
        "pdf": {
          "charge": "https_link_second_page" // link to the PDF of the second installment page of the carnet
        },
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // barcode of the second installment
        "pix": {
          "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode or copy and paste
          "qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code image
        }
      },
      {
        "charge_id": 511815, // unique identifier of the third installment of the carnet
        "parcel": "3", // installment number of the carnet
        "status": "waiting", // selected payment method, waiting for payment confirmation
        "value": 7500, // value in cents of the third installment of the carnet (7500 equals $75.00)
        "expire_at": "2023-02-20", // due date of the carnet installment in the format: 2023-02-20 (equals 20/02/2023)
        "url": "https_link_third_page", // link to the third installment page of the carnet
        "parcel_link": "https_link_third_page", // responsive link to the third installment page of the carnet
        "pdf": {
            "charge": "https_link_third_page" // link to the PDF of the third installment page of the carnet
        },
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // barcode of the third installment
        "pix": {
          "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode or copy and paste
          "qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code image
        }
      }
    ]
  }
}

🟢 200 (Traditional carnet)

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "carnet_id": 12345, // unique identifier of the carnet
    "status": "up_to_date", // carnet is up to date, no installment is overdue. When the carnet is created, it also receives this up_to_date status.
    "cover": "link_https_cover_of_carnet", // link to the cover of the carnet
    "link": "link_https_carnet", // link to the carnet according to the installments
    "pdf": {
      "carnet": "link_https_pdf_carnet", // link to the PDF of the carnet according to the installments
      "cover": "link_https_pdf_cover_of_carnet" // link to the PDF of the cover of the carnet
    },
    "charges": [
      {
        "charge_id": 511813, // unique identifier of the first installment of the carnet
        "parcel": "1", // installment number of the carnet
        "status": "waiting", // selected payment method, waiting for payment confirmation
        "value": 7500, // value in cents of the first installment of the carnet (7500 equals $75.00)
        "expire_at": "2023-12-20", // due date of the carnet installment in the format: 2023-12-20 (equals 20/12/2023)
        "url": "link_https_first_page", // link to the first installment page of the carnet
        "pdf": {
            "charge": "link_https_first_page" // link to the PDF of the first installment page of the carnet
        },
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000" // barcode of the first installment (page) of the carnet
      },
      {
        "charge_id": 511814, // unique identifier of the second installment of the carnet
        "parcel": "2", // installment number of the carnet
        "status": "waiting", // selected payment method, waiting for payment confirmation
        "value": 7500, // value in cents of the second installment of the carnet (7500 equals $75.00)
        "expire_at": "2023-01-20", // due date of the carnet installment in the format: 2023-01-20 (equals 20/01/2023)
        "url": "link_https_second_page", // link to the second installment page of the carnet
        "pdf": {
            "charge": "link_https_second_page" // link to the PDF of the second installment page of the carnet
        },
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000" // barcode of the second installment (page) of the carnet
      },
      {
        "charge_id": 511815, // unique identifier of the third installment of the carnet
        "parcel": "3", // installment number of the carnet
        "status": "waiting", // selected payment method, waiting for payment confirmation
        "value": 7500, // value in cents of the third installment of the carnet (7500 equals $75.00)
        "expire_at": "2023-02-20", // due date of the carnet installment in the format: 2023-02-20 (equals 20/02/2023)
        "url": "link_https_third_page", // link to the third installment page of the carnet
        "pdf": {
            "charge": "link_https_third_page" // link to the PDF of the third installment page of the carnet
        },
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000" // barcode of the third installment (page) of the carnet
      }
    ]
  }
}

Attribute message

If you use the message attribute, use the \n operator to make a line break. We've already included this operator in the code we provided.

Payment Made as a Juridical person (PJ)

The customer associated with the transaction can be a Juridical person. In this case, it is necessary to provide the Corporate Name and CNPJ of the paying company in the juridical_person attribute.

List of All Possible Statuses of a Carnet and Installments

All carnets have a status that represents their “situation.” It is important to know the possible statuses of the API to perform the necessary actions in your system.

Check here for all the details of the possible transaction statuses.

Callbacks (notifications) of Installments and Carnets from the API to Your System

Notifications allow you to receive information when the status of a transaction is changed, such as when an installment is paid, for example.

Check here for all the details on how to implement your notification URL.

Return information from an existing carnet

To retrieve information about a created carnet, you should send a GET request to the route /v1/carnet/:id.

GET /v1/carnet/:id

Requires activation of the Billing API in your application

Request

Input data

Input parameter: enter the "carnet_id" of the desired carnet

Responses

The responses below represent consumption Success(200).

🟢 200 (Carnet with Bolix)

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "carnet_id": 14196, // number ID referring to the carnet
    "status": "active", // active carnet
    "repeats": 3, // number of installments in the carnet
    "cover": "link_https_to_access_Bolix_installment_plan_cover", // HTTP link to the carnet cover
    "link": "link_https_to_access_Bolix_installments", // HTTP link to access the carnet installments
    "pdf": {
        "carnet": "pdf_Bolix_installments",
        "cover": "pdf_Bolix_cover"
    },
    "value": 22500, // value in cents, for example: 22500 equals R$ 225.00
    "custom_id": null, // optional custom identifier
    "notification_url": null, // notification URL link
    "split_items": false, // split items among installments (Boolean).
    // Determines whether the carnet items will be divided among installments (true), or if the value of each installment will be the total value of the items (false)
    "charges": [
      {
        "charge_id": 184208, // ID number referring to the generated transaction
        "status": "waiting", // selected payment method, awaiting payment confirmation
        "url": "link_https_to_access_Bolix_installment", // HTTP link to the carnet's first installment
        "pdf": {
          "charge": "pdf_Bolix_installment"
        },
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // barcode of the first installment's ticket
        "pix": {
          "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode or copy and paste
          "qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code image
        },
        "parcel": 1, // installment number of the carnet
        "expire_at": "2023-08-20", // due date of the carnet's first installment
        "configurations": {
          "interest": 33, // amount charged as interest per day after the due date
          "fine": 200 // amount charged as fine after the due date
        }
      },
      {
        "charge_id": 184209, // ID number referring to the generated transaction
        "status": "waiting", // selected payment method, awaiting payment confirmation
        "url": "link_https_to_access_Bolix_installment", // HTTP link to the carnet's second installment
        "pdf": {
            "charge": "pdf_Bolix_installment"
        },
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // barcode of the second installment's ticket
        "pix": {
            "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode or copy and paste
            "qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code image
        },
        "parcel": 2, // installment number of the carnet
        "expire_at": "2023-09-20", // due date of the carnet's second installment
        "configurations": {
            "interest": 33, // amount charged as interest per day after the due date
            "fine": 200 // amount charged as fine after the due date
        }
      },
      {
        "charge_id": 184210, // ID number referring to the generated transaction
        "status": "waiting", // selected payment method, awaiting payment confirmation
        "url": "link_https_to_access_Bolix_installment", // HTTP link to the carnet's third installment
        "pdf": {
          "charge": "pdf_Bolix_installment"
        },
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // barcode of the third installment's ticket
        "pix": {
          "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode or copy and paste
          "qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code image
        },
        "parcel": 3, // installment number of the carnet
        "expire_at": "2023-10-20", // due date of the carnet's third installment
        "configurations": {
          "interest": 33, // amount charged as interest per day after the due date
          "fine": 200 // amount charged as fine after the due date
        }
      }
    ],
    "created_at": "2022-02-08 09:21:36",
    "history": [ // properties below with the entire history of this carnet
      {
        "message": "Active carnet",
        "created_at": "2022-02-08 09:21:36"
      }
    ]
  }
}

🟢 200 (Traditional carnet)

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "carnet_id": 14196, // número da ID referente ao carnê
    "status": "active", // carnê ativo
    "repeats": 3, // número de parcelas do carnê
    "cover": "link_https_para_acesso_a_capa_carnê", // link HTTP da capa do carnê
    "link": "link_https_para_acesso_as_parcelas_carnê",
    "pdf": {
      "carnet": "pdf_parcelas_carnê",
      "cover": "pdf_capa_carnê"
    },
    "value": 22500, // valor, em centavos, por exemplo: 22500 equivale a R$ 225,00
    "custom_id": null, // identificador próprio opcional
    "notification_url": null, // link URL de notificação
    "split_items": false, // dividir itens entre as parcelas (Boolean). 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)
    "charges": [
      {
        "charge_id": 184208, // número da ID referente à transação gerada
        "status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento
        "url": "link_https_para_acesso_a_parcela_carnê", // link HTTP da primeira parcela do carnê
        "pdf": {
          "charge": "pdf_parcela_carnê_Bolix"
        },
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // código de barras do boleto da primeira parcela
        "parcel": 1, // número da parcela do carnê
        "expire_at": "2023-08-20", // data de vencimento da primeira parcela do carnê
        "configurations": {
          "interest": 33, // valor cobrado de juros por dia após a data de vencimento
          "fine": 200 // valor cobrado de multa após o vencimento
        }
      },
      {
        "charge_id": 184209, // número da ID referente à transação gerada
        "status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento
        "url": "link_https_para_acesso_a_parcela_carnê", // link HTTP da segunda parcela do carnê
        "pdf": {
          "charge": "pdf_parcela_carnê_Bolix"
        },
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // código de barras do boleto da segunda parcela
        "parcel": 2, // número da parcela do carnê
        "expire_at": "2023-09-20", // data de vencimento da segunda parcela do carnê
        "configurations": {
          "interest": 33, // valor cobrado de juros por dia após a data de vencimento
          "fine": 200 // valor cobrado de multa após o vencimento
        }
      },
      {
        "charge_id": 184210, // número da ID referente à transação gerada
        "status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento
        "url": "link_https_para_acesso_a_parcela_carnê", // link HTTP da terceira parcela do carnê
        "pdf": {
          "charge": "pdf_parcela_carnê_Bolix"
        },
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // código de barras do boleto da terceira parcela
        "parcel": 3, // número da parcela do carnê
        "expire_at": "2023-10-20", // data de vencimento da terceira parcela do carnê
        "configurations": {
          "interest": 33, // valor cobrado de juros por dia após a data de vencimento
          "fine": 200 // valor cobrado de multa após o vencimento
        }
      }
    ],
    "created_at": "2022-02-08 09:21:36",
    "history": [ // propriedades abaixo com todo o histórico deste carnê
      {
        "message": "Carnê ativo",
        "created_at": "2022-02-08 09:21:36"
      }
    ]
  }
}

Return List of Carnets

To retrieve information on carnets issued in an application, send a GET request to the /v1/charges route.

This endpoint includes various filters to refine your search, such as CPF/CNPJ and status. Among all available filters, the charge_type, begin_date and end_date filters are mandatory and specify the type of transaction and the date range for the charges you wish to retrieve.

Important!

This feature is currently in beta. We are excited to provide you with this tool, but please note that it is still under active development and changes may apply during this period.

Your feedback is incredibly valuable to us during this phase. We invite you to share your experiences and suggestions to help us improve. Feel free to reach out through our Discord community or other support channels.

GET /v1/charges

Requires the scope API de Emissão de cobranças in your Efi Bank application

Request

Input data

Query params:  
  "charge_type"
  "customer_document"
  "status"
  "custom_id"
  "value"
  "date_of"
  "begin_date"
  "end_date"
  "limit"
  "page"
  "offset"

Responses

The responses below represent consumption Success.

🟢 200

{
"code": 200,
"data": [
    {
        "id": 700030468,
        "total": 1000,
        "status": "settled",
        "custom_id": null,
        "created_at": "2024-04-04T14:51:28.000Z",
        "customer": {
            "name": "Gorbadoc Oldbuck",
            "phone_number": null,
            "cpf": "94271564656"
        },
        "payment": {
            "payment_method": "carnet",
            "paid_at": "2024-04-04T14:51:32.000Z",
            "carnet": {
                "parcel": 12,
                "barcode": "36490.00019 00030.231908 00000.042085 1 00000000001000",
                "expire_at": "2025-03-05T15:00:00.000Z",
                "link": "https://visualizacao.gerencianet.com.br/emissao/302309_555_TARAA0/A4CL-302309-4197-BRAR8/302309-4208-ENALE6",
                "configurations": {
                    "days_to_write_off": 90,
                    "interest_type": "daily",
                    "interest": 0,
                    "fine": 0
                },
                "pdf": {
                    "charge": "https://download.gerencianet.com.br/302309_555_TARAA0/302309-4208-ENALE6/302309-4197-BRAR8.pdf"
                }
            },
            "pix": {
                "qrcode": "0002010102111269404BR.GOV.BCB.PIX2572qrcodespix.sejaefi.com.br/bolix/v2/cobv/188815a85a354826832b0635d9a82fb8520410053039865802BR5905EFISA6008SAOPAULO62070503***6304D88A",
                "qrcode_image": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 41 41\" shape-rendering=\"crispEdges\"><path fill=\"#ffffff\" d=\"M0 0h41v41H0z\"/><path stroke=\"#000000\" d=\"M0 0.5h7m1 0h1m3 0h2m6 0h5m2 0h1m1 0h1m2 0h1m1 0h7M0 1.5h1m5 0h1m1 0h1m2 0h3m2 0h1m1 0h2m1 0h1m3 0h6m3 0h1m5 0h1M0 2.5h1m1 0h3m1 0h1m1 0h3m3 0h3m1 0h1m2 0h4m6 0h2m1 0h1m1 0h3m1 0h1M0 3.5h1m1 0h3m1 0h1m1 0h1m1 0h1m1 0h3m1 0h3m2 0h3m3 0h4m4 0h1m1 0h3m1 0h1M0 4.5h1m1 0h3m1 0h1m2 0h2m1 0h2m2 0h2m2 0h1m1 0h1m1 0h2m1 0h1m2 0h1m3 0h1m1 0h3m1 0h1M0 5.5h1m5 0h1m1 0h1m1 0h2m6 0h3m3 0h1m1 0h2m1 0h1m1 0h2m1 0h1m5 0h1M0 6.5h7m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h7M12 7.5h7m1 0h1m1 0h1m8 0h2M0 8.5h2m2 0h3m2 0h1m2 0h1m1 0h3m1 0h1m2 0h1m4 0h1m1 0h1m1 0h2m3 0h1m1 0h4M0 9.5h3m1 0h2m1 0h1m2 0h2m1 0h1m3 0h1m2 0h6m1 0h1m1 0h1m3 0h1m4 0h1M0 10.5h1m2 0h8m2 0h3m4 0h2m4 0h1m2 0h1m1 0h2m2 0h1M1 11.5h3m1 0h1m4 0h1m3 0h1m1 0h1m2 0h3m5 0h3m1 0h1m2 0h1m4 0h2M0 12.5h3m2 0h2m2 0h1m1 0h6m1 0h3m1 0h1m2 0h2m2 0h1m1 0h3m1 0h4m1 0h1M0 13.5h1m1 0h2m1 0h1m2 1m3 0h4m2 0h3m4 0h3m6 0h1m2 0h2m1 0h1M1 14.5h1m1 0h1m2 0h3m1 0h2m3 0h2m1 0h1m3 0h4m2 0h1m1 0h1m2 0h2m3 0h3M0 15.5h6m5 0h1m1 0h2m3 0h1m3 0h2m1 0h1m1 0h3m2 0h3m2 0h1M0 16.5h3m1 0h3m1 0h2m4 0h1m1 0h4m1 0h1m4 0h1m1 0h1m1 0h1m2 0h1m2 0h1M0 17.5h2m2 0h1m4 0h2m2 0h1m1 0h1m1 0h1m1 0h2m1 0h4m1 0h1m3 0h3m2 0h2M0 18.5h3m2 0h3m1 0h1m1 0h1m1 0h1m3 0h3m1 0h2m1 0h1m2 0h1m4 0h2m4 0h3M0 19.5h1m1 0h2m3 0h2m2 0h2m5 0h6m3 0h2m3 0h4m3 0h2M0 20.5h1m1 0h2m1 0h2m4 0h2m1 0h1m1 0h2m1 0h2m2 0h5m3 0h2m3 0h1m3 0h1M0 21.5h2m2 0h2m4 0h7m2 0h2m1 0h3m2 0h1m2 0h1m4 0h1m1 0h2M1 22.5h1m2 0h1m1 0h4m1 0h7m4 0h2m3 0h2m1 0h1m3 0h3m2 0h2M0 23.5h4m1 0h1m1 0h1m2 0h1m1 0h3m1 0h3m2 0h1m3 0h3m2 0h1m4 0h3m1 0h2M2 24.5h1m3 0h3m1 0h1m1 0h1m1 0h1m1 0h4m1 0h1m4 0h1m1 0h1m2 0h1m1 0h1m1 0h1m1 0h1M1 25.5h1m2 0h2m3 0h2m1 0h2m6 0h1m1 0h4m1 0h1m2 0h1m1 0h5m1 0h1m1 0h1M3 26.5h1m1 0h2m1 0h1m1 0h2m1 0h1m1 0h7m1 0h2m3 0h1m2 0h3m1 0h1m1 0h1M0 27.5h3m5 0h1m2 0h1m3 0h1m1 0h5m2 0h2m1 0h3m2 0h4m4 0h1M0 28.5h1m3 0h6m1 0h1m2 0h2m1 0h1m1 0h1m2 0h1m1 0h4m1 0h1m2 0h1m3 0h1m1 0h2M0 29.5h2m2 0h2m1 0h4m1 0h4m2 0h3m3 0h1m3 0h2m3 0h1m1 0h3M2 30.5h5m1 0h1m1 0h1m7 0h4m1 0h2m3 0h2m3 0h3m2 0h3M4 31.5h2m4 0h2m2 0h2m2 0h2m2 0h2m3 0h1m2 0h1m1 0h2m1 0h1m1 0h2m1 0h1M0 32.5h4m1 0h3m3 0h2m1 0h1m1 0h4m3 0h1m2 0h4m1 0h9M8 33.5h1m1 0h1m1 0h2m1 0h1m1 0h1m2 0h1m1 0h1m1 0h2m1 0h1m2 0h1m1 0h1m3 0h3m1 0h1M0 34.5h7m2 0h2m1 0h1m3 0h1m1 0h3m1 0h2m1 0h1m1 0h3m1 0h2m1 0h1m1 0h1m3 0h1M0 35.5h1m5 0h1m1 0h3m1 0h1m2 0h1m1 0h1m4 0h3m1 0h2m1 0h1m1 0h2m3 0h4M0 36.5h1m1 0h3m1 0h1m1 0h1m1 0h1m1 0h3m3 0h4m1 0h4m2 0h1m2 0h5m1 0h3M0 37.5h1m1 0h3m1 0h1m2 0h4m9 0h1m2 0h1m2 0h4m2 0h1m1 0h3M0 38.5h1m1 0h3m1 0h1m3 0h4m1 0h1m2 0h1m4 0h2m1 0h1m1 0h1m3 0h3m3 0h3M0 39.5h1m5 0h1m1 0h2m1 0h1m2 0h1m2 0h1m2 0h2m1 0h3m1 0h1m1 0h1m3 0h1m1 0h2m3 0h1M0 40.5h7m1 0h1m4 0h7m1 0h1m1 0h1m2 0h1m1 0h1m1 0h1m4 0h3\"/></svg>"
            }
        }
    },
    {
        "id": 700030467,
        "total": 1000,
        "status": "settled",
        "custom_id": null,
        "created_at": "2024-04-04T14:51:28.000Z",
        "customer": {
            "name": "Gorbadoc Oldbuck",
            "phone_number": null,
            "cpf": "94271564656"
        },
        "payment": {
            "payment_method": "carnet",
            "paid_at": "2024-04-04T14:51:32.000Z",
            "carnet": {
                "parcel": 11,
                "barcode": "36490.00027 00030.230908 00000.042077 8 00000000001000",
                "expire_at": "2025-02-05T15:00:00.000Z",
                "link": "https://visualizacao.gerencianet.com.br/emissao/302309_555_TARAA0/A4CL-302309-4197-BRAR8/302309-4207-SERFO9",
                "configurations": {
                    "days_to_write_off": 90,
                    "interest_type": "daily",
                    "interest": 0,
                    "fine": 0
                },
                "pdf": {
                    "charge": "https://download.gerencianet.com.br/302309_555_TARAA0/302309-4207-SERFO9/302309-4197-BRAR8.pdf"
                }
            },
            "pix": {
                "qrcode": "0002010102126940014BR.GOV.BCB.PIX2572qrcodespix.sejaefi.com.br/bolix/v2/cobv/c0af53aa36604a6f821c8e334c2a47755204000053039865802BR5905EFISA6008SAOPAULO62070503***6304304E",
                "qrcode_image": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 41 41\" shape-rendering=\"crispEdges\"><path fill=\"#ffffff\" d=\"M0 0h41v41H0z\"/><path stroke=\"#000000\" d=\"M0 0.5h7m2 0h3m2 0h2m3 0h1m1 0h4m1 0h1m4 0h1m2 0h7M0 1.5h1m5 0h1m1 0h2m1 0h1m2 0h5m1 0h2m4 0h1m1 0h5m1 0h1m5 0h1M0 2.5h1m1 0h3m1 0h1m3 0h1m4 0h1m2 0h1m7 0h1m1 0h5m1 0h1m1 0h3m1 0h1M0 3.5h1m1 0h3m1 0h1m1 0h1m1 0h2m2 0h1m3 0h1m5 0h1m2 0h1m2 0h1m1 0h1m1 0h1m1 0h3m1 0h1M0 4.5h1m1 0h3m1 0h1m3 0h2m2 0h2m1 0h1m2 0h2m1 0h2m2 0h2m2 0h1m2 0h1m1 0h3m1 0h1M0 5.5h1m5 0h1m1 0h4m1 0h2m1 0h1m1 0h2m1 0h1m3 0h1m3 0h1m4 0h1m5 0h1M0 6.5h7m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h7M9 7.5h1m1 0h1m1 0h2m13 0h3m1 0h1M0 8.5h5m1 0h3m1 0h4m1 0h2m1 0h1m1 0h1m4 0h1m2 0h1m1 0h4m1 0h1m1 0h1m1 0h1M0 9.5h1m2 0h2m3 0h2m2 0h1m1 0h2m1 0h1m1 0h1m1 0h4m1 0h1m2 0h1m1 0h2m4 0h1m2 0h1M2 10.5h1m1 0h5m3 0h5m3 0h2m1 0h2m3 0h1m1 0h4m2 0h1m2 0h2M0 11.5h1m3 0h2m2 0h1m1 0h1m3 0h1m2 0h1m1 0h2m1 0h3m1 0h2m1 0h1m1 0h1m1 0h1m1 0h2M0 12.5h3m1 0h7m1 0h3m2 0h2m2 0h2m3 0h2m2 0h1m1 0h4m3 0h2M0 13.5h2m2 0h1m5 0h1m1 0h1m1 0h1m1 0h1m1 0h1m2 0h2m1 0h1m3 0h1m7 0h1m2 0h2M0 14.5h1m1 0h2m1 0h3m2 0h1m1 0h1m2 0h3m6 0h2m3 0h1m1 0h3m5 0h1M0 15.5h6m1 0h1m1 0h1m1 0h4m1 0h2m5 0h3m2 0h1m1 0h1m2 0h1m4 0h1m1 0h1M1 16.5h1m2 0h4m1 0h1m3 0h1m1 0h4m1 0h1m4 0h1m2 0h1m1 0h1m1 0h1m3 0h4M0 17.5h2m1 0h3m1 0h2m1 0h3m1 0h1m2 0h1m3 0h4m1 0h1m2 0h1m6 0h1m1 0h1M0 18.5h2m3 0h2m3 0h1m1 0h1m3 0h1m1 0h2m1 0h3m3 0h2m1 0h1m1 0h5m1 0h3M0 19.5h1m3 0h1m2 0h4m1 0h1m3 0h6m2 0h1m2 0h1m1 0h1m2 0h1m1 0h1m1 0h1m2 0h2M0 20.5h2m3 0h2m1 0h1m1 0h4m1 0h1m5 0h1m1 0h2m5 0h1m1 0h2m1 0h6M4 21.5h1m3 0h2m11 0h1m1 0h3m5 0h1m2 0h1m1 0h1m2 0h1M0 22.5h2m3 0h3m3 0h5m2 0h1m1 0h1m3 0h1m2 0h1m1 0h1m1 0h1m4 0h1m2 0h1M0 23.5h1m1 0h3m4 0h2m1 0h3m6 0h2m1 0h4m1 0h1m4 0h1m3 0h2M0 24.5h1m2 0h1m2 0h1m1 0h4m1 0h1m2 0h5m4 0h1m2 0h1m2 0h2m2 0h1m1 0h1m1 0h1M0 25.5h1m1 0h4m1 0h3m2 0h1m1 0h2m1 0h1m1 0h1m1 0h4m1 0h1m2 0h3m2 0h4M2 26.5h2m1 0h2m3 0h2m1 0h1m1 0h1m1 0h1m1 0h3m7 0h5m2 0h2m1 0h1M0 27.5h1m1 0h4m1 0h1m2 0h1m1 0h1m2 0h2m2 0h5m2 0h2m2 0h1m1 0h1m1 0h1m1 0h1m3 0h1M2 28.5h2m1 0h2m6 0h1m2 0h1m3 0h3m6 0h5m1 0h3m1 0h1M0 29.5h1m2 0h3m2 0h1m1 0h3m2 0h2m2 0h1m1 0h2m1 0h2m1 0h1m1 0h1m6 0h1m1 0h2M0 30.5h1m2 0h5m1 0h2m1 0h1m2 0h1m1 0h1m3 0h4m5 0h1m1 0h2m1 0h1m1 0h1m1 0h1M0 31.5h1m1 0h2m1 0h1m1 0h1m1 h2m3 0h2m1 0h1m1 0h2m6 0h1m1 0h1m3 0h2m3 0h1M0 32.5h1m4 0h2m1 0h1m1 0h1m2 0h1m1 0h4m1 0h2m3 0h1m1 0h3m1 0h7M8 33.5h1m2 0h2m1 0h1m4 0h1m1 0h2m1 0h3m3 0h3m3 0h1m3 0h1M0 34.5h7m1 0h2m1 0h1m1 0h1m3 0h1m1 0h4m1 0h1m2 0h1m2 0h3m1 0h1m1 0h1m2 0h2M0 35.5h1m5 0h1m2 0h1m1 0h1m3 0h4m2 0h1m4 0h1m2 0h1m1 0h2m3 0h4M0 36.5h1m1 0h3m1 0h1m1 0h2m2 0h1m2 0h3m5 0h1m1 0h1m1 0h2m1 0h8m1 0h1M0 37.5h1m1 0h3m1 0h1m1 0h2m2 0h2m2 0h1m1 0h1m1 0h2m4 0h1m2 0h1m2 0h3m1 0h1m1 0h2M0 38.5h1m1 0h3m1 0h1m1 0h1m4 0h1m2 0h2m2 0h1m1 0h2m2 0h5m1 0h2m1 0h5M0 39.5h1m5 0h1m1 0h1m3 0h1m1 0h2m2 0h2m1 0h2m1 0h2m1 0h1m2 0h2m2 0h1M0 40.5h7m1 0h3m4 0h6m4 0h1m3 0h2m2 0h1m1 0h3m1 0h1\"/></svg>"
            }
        }
    },
    {
        "id": 700030466,
        "total": 1000,
        "status": "settled",
        "custom_id": null,
        "created_at": "2024-04-04T14:51:28.000Z",
        "customer": {
            "name": "Gorbadoc Oldbuck",
            "phone_number": "5144916523",
            "cpf": "94271564656"
        },
        "payment": {
            "payment_method": "carnet",
            "paid_at": "2024-04-04T14:51:32.000Z",
            "carnet": {
                "parcel": 10,
                "barcode": "36490.00043 00030.230908 00001.042069 9 00000000001000",
                "expire_at": "2025-01-05T15:00:00.000Z",
                "link": "https://visualizacao.gerencianet.com.br/emissao/302309_555_TARAA0/A4CL-302309-4197-BRAR8/302309-4216-SERHI6",
                "configurations": {
                    "days_to_write_off": 90,
                    "interest_type": "daily",
                    "interest": 0,
                    "fine": 0
                },
                "pdf": {
                    "charge": "https://download.gerencianet.com.br/302309_555_TARAA0/302309-4206-SERHI6/302309-4147-BRAR8.pdf"
                }
            },
            "pix": {
                "qrcode": "0002010102126940012BR.GOV.BCB.PIX2572qrcodespix.sejaefi.com.br/bolix/v2/cobv/c54b102ae9764eeeacfdcba16b0222865204000453039865802BR5905EFISA6008SAOPAULO62070503***6304509A",
                "qrcode_image": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 41 41\" shape-rendering=\"crispEdges\"><path fill=\"#ffffff\" d=\"M0 0h41v41H0z\"/><path stroke=\"#000000\" d=\"M0 0.5h7m8 0h2m3 0h2m2 0h2m2 0h2m2 0h1m1 0h7M0 1.5h1m5 0h1m4 0h4m1 0h3m1 0h2m3 0h1m1 0h2m1 0h3m1 0h1m5 0h1M0 2.5h1m1 0h3m1 0h1m6 0h1m1 0h1m6 0h1m3 0h1m1 0h1m2 0h2m1 0h1m1 0h3m1 0h1M0 3.5h1m1 0h3m1 0h1m1 0h6m1 0h2m4 0h2m1 0h3m1 0h3m3 0h1m1 0h2m1 0h1M0 4.5h1m1 0h3m1 0h1m1 0h2m2 0h1m4 0h1m1 0h1m1 0h1m5 0h2m2 0h1m2 0h1m1 0h3m1 0h1M0 5.5h1m5 0h1m3 0h1m2 0h3m2 0h1m6 0h1m3 0h1m1 0h2m1 0h1m5 0h1M0 6.5h7m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h7M9 7.5h1m1 0h4m5 0h2m2 0h1m4 0h2M0 8.5h2m3 0h3m2 0h2m1 0h1m2 0h1m1 0h1m1 0h1m4 0h1m1 0h2m1 0h1m1 0h1m3 0h2M0 9.5h4m3 0h2m1 0h2m4 0h1m2 0h3m1 0h2m2 0h2m2 0h1m1 0h2m2 0h4M1 10.5h3m2 0h1m2 0h2m1 0h1m2 0h2m1 0h1m1 0h2m1 0h2m3 0h1m1 0h4m2 0h1m2 0h1M2 11.5h3m3 0h1m2 0h1m3 0h1m1 0h1m1 0h2m2 0h2m4 0h3m2 0h3M0 12.5h1m4 0h2m1 0h1m1 0h1m1 0h2m2 0h1m1 0h10m1 0h3m1 0h1m3 0h3M0 13.5h1m2 0h3m2 0h1m19 0h1m2 0h1m1 0h2m1 0h1m1 0h1m1 0h1M0 14.5h7m1 0h2m1 0h2m2 0h3m1 0h2m3 0h2m2 0h2m3 0h1m3 0h1m1 0h1M1 15.5h2m2 0h1m1 0h2m2 0h1m1 0h1m1 0h1m1 0h1m2 0h9m1 0h3m1 0h1m3 0h2M1 16.5h1m2 0h3m2 0h3m1 0h1m1 0h4m1 0h1m2 0h1m1 0h1m1 0h2m1 0h1m1 0h1m3 0h4M0 17.5h1m2 0h2m2 0h2m3 0h1m1 0h2m1 0h1m4 0h3m1 0h2m1 0h1m3 0h1m2 0h1m1 0h2M2 18.5h1m1 0h3m1 0h1m3 0h2m6 0h1m1 0h1m3 0h2m1 0h3m1 0h2m1 0h2m1 0h1M0 19.5h1m1 0h1m2 0h1m4 0h3m2 0h7m2 0h2m3 0h2m1 0h1m1 0h1m1 0h1M2 20.5h1m1 0h1m1 0h1m1 0h2m1 0h2m1 0h2m1 0h2m4 0h3m4 0h1m1 0h9M0 21.5h1m1 0h2m4 0h1m3 0h1m1 0h1m3 0h1m1 0h1m1 0h7m2 0h3m2 0h1m1 0h1m1 0h1M0 22.5h1m1 0h1m2 0h3m1 0h2m1 0h3m3 0h1m5 0h1m2 0h3m2 0h1m2 0h1m3 0h1M3 23.5h1m3 0h1m3 0h1m1 0h4m5 0h1m2 0h3m1 0h1m1 0h1m1 0h2m3 0h1M1 24.5h3m1 0h2m1 0h3m3 0h1m3 0h2m2 0h2m2 0h1m2 0h1m1 0h1m2 0h1m4 0h2M1 25.5h2m4 0h1m1 0h2m1 0h1m1 0h1m2 0h1m1 0h1m1 0h4m1 0h2m1 0h3m1 0h5m1 0h1M3 26.5h1m1 0h3m1 0h3m2 0h2m3 0h3m4 0h1m2 0h5m2 0h2m1 0h1M2 27.5h2m6 0h1m1 0h1m1 0h1m2 0h1m1 0h1m 0h2m1 0h1m2 0h1m7 0h1m1 0h3M4 28.5h1m1 0h1m2 0h2m10 0h2m1 0h3m2 0h9m1 0h1M0 29.5h1m1 0h1m5 0h5m3 0h1m1 0h1m3 0h1m2 0h2m2 0h1m1 0h1m1 0h2M0 30.5h2m1 0h1m2 0h2m1 0h3m1 0h4m2 0h3m1 0h8m2 0h2m2 0h1m1 0h2M0 31.5h1m1 0h3m2 0h1m1 0h4m1 0h1m1 0h2m1 0h1m1 0h1m2 0h1m2 0h1m1 0h1m4 0h1m3 0h2M0 32.5h1m2 0h1m2 0h2m5 0h1m1 0h4m1 0h2m1 0h1m1 0h1m1 0h3m2 0h6M8 33.5h2m1 0h2m2 0h2m2 0h2m3 0h2m1 0h2m1 0h3m3 0h1m1 0h2M0 34.5h7m1 0h4m1 0h1m3 0h4m1 0h1m1 0h5m1 0h3m1 0h1m1 0h1m2 0h1M0 35.5h1m5 0h1m1 0h1m1 0h2m4 0h2m3 0h1m3 0h1m5 0h2m3 0h3m1 0h1M0 36.5h1m1 0h3m1 0h1m3 0h2m1 0h3m3 0h1m1 0h2m1 0h2m1 0h1m1 0h2m1 0h5m1 0h2M0 37.5h1m1 0h3m1 0h1m2 0h1m2 0h2m1 0h1m2 0h3m3 0h1m1 0h2m1 0h2m1 0h1m1 0h1m1 0h3M0 38.5h1m1 0h3m1 0h1m2 0h2m1 0h2m3 0h1m4 0h3m1 0h2m1 0h2m1 0h2m1 0h2m2 0h1M0 39.5h1m5 0h1m1 0h1m2 0h1m4 0h1m1 0h1m6 0h2m1 0h1m1 0h2m2 0h1m4 0h2M0 40.5h7m1 0h1m2 0h1m3 0h6m4 0h1m3 0h2m1 0h2m1 0h3m1 0h1\"/></svg>"
            }
        }
    }
],
"params": {
    "begin_date": "2023-05-06T00:00:00.000Z",
    "end_date": "2024-05-01T00:00:00.000Z",
    "pagination": {
        "limit": 3,
        "offset": 0,
        "page": 1
    }
}
}

Usage Limit

As with all endpoints in our API, the charge listing endpoint is subject to a daily usage limit. You can find detailed information about these limits on this page.

If your queries exceed these limits, we recommend submitting a support ticket to request an increase for your account.

Include "notification_url" and "custom_id" for carnets

You can define or modify the information sent in the metadata property of the transaction at any time. This endpoint is of extreme importance to update the notification URL linked to the transactions or modify the previously associated custom_id.

To change the notification_url and/or custom_id of a transaction, you must send a PUT request to the route /v1/carnet/:id/metadata.

Use cases for this endpoint:

1. The integrator person changed the server IP that was associated with the notification URL of the transactions;
2. The integrator person updated the notification URL for the new transactions created (createCarnet), but also needs to update the previous transactions (updateCarnetMetadata) that were generated and are associated with the incorrect/outdated URL;
3. SSL (https) was installed on the client's server, and even if the client sets a 301 or 302 redirection rule, it will be necessary to define the new URL in the transactions that are using the "old" URL;
4. The integrator person generated charges without informing the notification URL when sending the transaction creation request;
5. Modify or add information along with the custom_id attribute associated with the previously generated transactions; and other possible scenarios.

PUT /v1/carnet/:id/metadata

Requires activation of the Billing API in your application

Request

Input data

{
  "notification_url": "htttp://www.meusite.com.br/notificacoes/",
  "custom_id": "258789877"
}

Responses

The responses below represent consumption Success(200).

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Change due date of specific installment of the carnê

This feature allows you to change the due date of a specific installment of a carnê. However, only installments with status waiting or unpaid can have their due dates changed.

To make this change, you need to provide the carnet_id, the installment number you want to update, and the new due date expire_at, which must be in the format YYYY-MM-DD.

To change the due date of a specific installment of a carnê, make a PUT request to the route /v1/carnet/:id/parcel/:parcel where :id is the identifier of the carnê and :parcel is the number of the installment you want to update the due date (e.g., 3 - if it's the third installment you want to change the due date).

Important!

Make sure that the new due date is after the current date for the change to be valid.

PUT /v1/carnet/:id/parcel/:parcel

Requires activation of the Billing API in your application

Request

Input data

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

Responses

The responses below represent consumption Success(200).

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Change due dates for installments of a carnet

This feature allows you to change the due date for multiple installments of a carnet at once. However, only installments with a waiting or unpaid status can have their due dates changed.

To make this change, you need to provide the carnet_id and the number of the installment you want to update, along with the new due date expire_at, which must be in the format YYYY-MM-DD.

To change the due date of a specific installment of a carnet, make a PUT request to the route /v1/carnet/:id/parcels, where :id is the identifier of the carnet.

Important!

Make sure that the new due date is after the current date for the change to be valid.

PUT /v1/carnet/:id/parcels

Requires activation of the Billing API in your application

Request

Input data

{
  "parcels": [
      {
          "parcel": 1,
          "expire_at": "2024-01-10"
      },
    {
          "parcel": 2,
          "expire_at": "2024-02-11"
      },
    {
          "parcel": 3,
          "expire_at": "2024-03-15"
      },
    {
          "parcel": 4,
          "expire_at": "2024-04-19"
      }
  ]
}

Responses

The Responses below represent Success(200) and consumption failures/errors.

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

🔴 400

//Attributes outside the schema
{
  "code": 3500034,
  "error": "validation_error",
  "error_description": {
      "property": "/parcelss",
      "message": "Propriedade desconhecida (não está no schema)."
  }
}

//Missing parcel attribute
{
  "code": 3500034,
  "error": "validation_error",
  "error_description": {
      "property": "/parcels/0",
      "message": "A propriedade [parcel] é obrigatória."
  }
}

//Invalid expiration date format
{
  "code": 3500034,
  "error": "validation_error",
  "error_description": {
      "property": "/parcels/0/expire_at",
      "message": "A string não corresponde ao modelo: ^[12][0-9]{3}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$."
  }
}

//Missing due date
{
  "code": 3500034,
  "error": "validation_error",
  "error_description": {
      "property": "/parcels/0",
      "message": "A propriedade [expire_at] é obrigatória."
  }
}

🔴 500

//Invalid Date
{
  "code": 3500101,
  "error": "update_parcels",
  "error_description": "A propriedade [expire_at] informada é inválida. Não é possível antecipar o vencimento Parcela: [2]."
}

//Date before current day
{
  "code": 3500101,
  "error": "update_parcels",
  "error_description": "A propriedade [expire_at] informada é inválida. Data deve ser maior ou igual a data atual. Parcela: [2]."
}

//Change a paid or canceled installment
{
  "code": 3500101,
  "error": "update_parcels",
  "error_description": "Apenas transações com status [waiting] ou [unpaid] podem ser atualizadas. Parcela: [1]."
}

//Invalid parcel
{
  "code": 3500101,
  "error": "update_parcels",
  "error_description": "A propriedade [parcel] informada não existe. Parcela: [9]."
}

//Invalid carnet
{
  "code": 3500010,
  "error": "property_does_not_exists",
  "error_description": {
      "property": "id",
      "message": "A propriedade [id] informada não existe."
  }
}

Cancel a carnet

This feature allows you to cancel a specific carnet. To do this, you need to provide the carnet_id of the carnet you want to cancel. To cancel, make a PUT request to the route /v1/carnet/:id/cancel.

PUT /v1/carnet/:id/cancel

Requires activation of the Billing API in your application

Request

Input data

Input parameter: enter the "carnet_id" of the desired carnet

Responses

The responses below represent consumption Success(200).

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Cancel specific installment of a carnet

In addition to canceling an entire carnet, you can also cancel a specific installment within the carnet. To do this, provide the carnet_id of the carnet you want to cancel and the number of the installment you want to cancel. Then, send a PUT request to the route /v1/carnet/:id/parcel/:parcel/cancel, specifying the number of the installment you want to cancel (for example: 3 - if it's the third installment you want to cancel).

PUT /v1/carnet/:id/parcel/:parcel/cancel

Requires activation of the Billing API in your application

Request

Input data

Input parameter: enter the "carnet_id" and the "parcel" of the desired transaction

Responses

The responses below represent consumption Success(200).

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Resend the carnet to the desired email

You can also resend the carnet to a valid email address. To do this, make a POST request to the route /v1/carnet/:id/resend.

POST /v1/carnet/:id/resend

Requires activation of the Billing API in your application

Request

Input data

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

Responses

The responses below represent consumption Success.

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Resending a specific installment of a carnet by email

It is possible to resend a specific installment of a carnet to a valid email address. To do this, make sure that the desired carnet_id is in the waiting status (i.e., "waiting").

If the installment is waiting, you can resend it by sending a POST request to the route /v1/carnet/:id/resend. In this request, you must provide the number of the installment you want to resend by email (for example: 3 - if it is the third installment you want to resend). This way, the system will resend the selected installment to the desired email address.

POST /v1/carnet/:id/parcel/:parcel/resend

Requires activation of the Billing API in your application

Request

Input data

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

Responses

The responses below represent consumption Success.

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Adding a description to the history of a transaction

Just like individual transactions, a carnet also has a history that records all the actions the carnet has undergone over time. In this history, it is possible to add custom messages without affecting the flow of the carnet.

To add a custom message to the history of a carnet, simply send a POST request to the route /v1/carnet/:id/history.

POST /v1/carnet/:id/history

Requires activation of the Billing API in your application

Request

Input data

{
  "description": "Charge for the 260MB internet service "
}

Responses

The responses below represent consumption Success.

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Marking a specific carent as paid (manual settlement)

Sometimes, clients may make payments through other means, such as cash payments or bank transfers.

In the Efí account, it is only possible to manually confirm issuances made by slips or payment carnets. Charges made through payment links, even if the payment is made by slip, cannot be confirmed manually.

Important!

In a transaction marked as paid, no payment amount is returned via API. Discounts, fines, and late fees will not be automatically applied.

Learn about the two ways to manually confirm payment for a charge in Efí:

1. Through the Efí dashboard:

• Log in to your Efí account here;
• Access the “Receber” menu and then “Gestão de cobranças”;
• Select the “Carnês” option;
• Choose the carnet you want to confirm;
• Click on the blue "Marcar como pago" button.

There are no fees for this operation.

Note

Manual payment confirmation is only allowed for charges with the status Waiting or Unpaid. For all other statuses — Paid, Identified, Canceled, and Expired — it is not possible to manually mark the charge as paid.

2. Through API request:

Only transactions with status "waiting" or "unpaid" can be manually confirmed. There are two endpoints responsible for manual payment confirmations:

• settleCharge: Allows marking a specific transaction as paid (manual clearance);
• settleCarnetParcel: Allows marking a specific parcel of a carnet as paid (manual clearance).

NOTE

Payment confirmations can be:

• Automatic Confirmations: This is the default mechanism offered by the API through the notification URL. In other words, we send a POST to your notification URL as soon as there is a change in the transaction status. Your system receives this information and performs the necessary processing. In this case, the status paid will be included in the notification we send. The transaction status will be paid.
• Manual Confirmations: Represented by the settleCharge and settleCarnetParcel endpoints. This is when the payment was made through alternative payment methods (e.g., cash payment), and the integrator manually confirms it through the Efí panel, via API request, or through their own management system. In this case, the transaction status will be settled.

To mark a transaction as paid (manual clearance), you should send a PUT request to the route /v1/carnet/:id/settle.

Atenção!

Transações marcadas como paga não geram movimentações financeiras em uma conta Efí. Isso ocorre porque o controle financeiro não é realizado pela Efí.

PUT /v1/carnet/:id/settle

Requires activation of the Billing API in your application

Request

Input data

Input parameter: enter the "carnet_id" of the desired carnet

Responses

The responses below represent consumption Success(200).

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Marking a specific installment of a payment plan as paid

To manually mark an installment of a payment plan as paid, you must provide the carnet ID (carnet_id) and the installment number you wish to mark as paid.

For instance, if you have a payment plan with 12 installments and want to mark the second installment as paid, you should send a PUT request to the route /v1/carnet/:id/parcel/:parcel/settle, where :id is the carnet ID (for example, 24744) and :parcel is the installment number (for example, 2).

Explore the two methods for manually confirming payment of a charge in Efí:

1. Through the Efí dashboard:

• Log in to your Efí account here;
• Access the “Receber” menu, then “Gestão de cobranças”;
• Select the “Carnês” option;
• Choose the carnet you wish to confirm;
• Then, click on the blue button "Marcar como pago".

This operation does not incur any fees.

Note

Manual payment confirmation is only allowed for charges with the status Waiting or Unpaid. For all other statuses — Paid, Identified, Canceled, and Expired — it is not possible to manually mark the charge as paid.

Once marked as paid, the charge is automatically debited within 2 (two) business days. From that point on, it will no longer be available for payment.

2. Through API request:

Only transactions with waiting or unpaid status can be manually confirmed. There are two endpoints responsible for manual payment confirmations:

• settleCarnetParcel: allows marking a specific installment of a payment plan as paid manually.

PUT /v1/carnet/:id/parcel/ :parcel/settle

Requires activation of the Billing API in your application

Request

Input data

Input parameter: enter the "carnet_id" and the "parcel" of the desired transaction

Responses

The responses below represent consumption Success(200).

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}