Others endpoints

There are another endpoints (services) available in the API and that can be used in carnês:

  1. Return information about a carnê

  2. Change notification URL (notification_url) and/or custom_id of a carnê

  3. Change the payment due date

  4. Cancel a carnê

  5. Cancel specific installment of a carnê

  6. Resend a carnê by e-mail

  7. Resend specific installment of a carnê by e-mail

  8. Add history informations about the carnê

  9. Mark as paid a certain installment of a carnê

Before proceeding, make sure that the Gerencianet SDK has been installed

The rest of this page presents the detailed procedures, but you need to install one of our libraries on your server to run the sample code.


1) Return information about a carnê

Returns information about a created carnê. Each transaction created via carnê has a unique identifier key that identifies it.

To return information from a carnê, you must send a GET request to the route /v1/carnet/:id, where :id is the carnet_id of the carnê.

If you want, you can explore and learn more about this resource using our Playground.

The example below shows how this can be done, using the SDK's available:

<?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 = desenvolvimento e false = producao)
];
// $carnet_id refere-se ao ID do carnê desejado
$params = [
'id' => $carnet_id
];
try {
$api = new Gerencianet($options);
$carnet = $api->detailCarnet($params, []);
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());
}

2) Change notification URL (notification_url) and/or custom_id of a carnê

It is possible to define or change the information sent in the metadata property of a carnê at any time. This endpoint is extremely important to update your notification URL linked to the carnê or modify the custom_id previously associated with your carnê.

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

Use cases for this endpoint:

  • Integrator changed the server IP that was associated in the notification URL of the carnês;

  • Integrator has updated the notification URL for new issues that are created (createCarnet), but needs to update also on previous transactions (updateCarnetMetadata) that were generated and that are associated with the incorrect/outdated URL;

  • SSL (https) was installed on the client's server and even if the client defines a 301 or 302 redirection rule, it will be necessary to define the new URL in the books that have the "old" URL;

  • Integrator generated charges and had not informed the notification URL when sending the request to create the booklets;

  • Modify or add information in the custom_id attribute associated with previously generated carnês;

  • Among other possible scenarios.

If you want, you can explore and learn more about this resource using our Playground.

The example below shows how this can be done, using the SDK's available:

<?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 = desenvolvimento e false = producao)
];
// $carnet_id refere-se ao ID do carnê desejado
$params = [
'id' => $carnet_id
];
$body = [
'custom_id' => 'Carnê 0001',
'notification_url' => 'http://domain.com/notification'
];
try {
$api = new Gerencianet($options);
$carnet = $api->updateCarnetMetadata($params, $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());
}

a) Hierarchical structure of Schema attributes that can be used:

"id": "/CarnetMetadataUpdate"
"notification_url"
"custom_id"

To more details, click here and explore it in our Playground.


b) Attributes that can be used to update notification URL and/or custom_id:

AttributeDescriptionRequiredType
notification_urlAddress of your valid URL that will receive notifications of changes in the status of the carnê and its parcels.
Minimum of 1 character and maximum of 255. 		NoString/null
custom_idAllows you to associate a Gerencianet carnê with a specific ID of your system or application, allowing you to identify it if you have a specific identification and want to keep it.
Minimum of 1 character and maximum of 255.		NoString

3) Change the payment due date

Allows you to change the due date of a certain installment of a carnê. Only installments that are in waiting or unpaid status can have their due dates changed.

To do so, you need to inform the carnet_id, the installment you want to change and the expire_at (new expiration date, in YYYY-MM-DD format).

To change the due date of a specific installment of a carnê, you must send a PUT request to the route /v1/carnet/:id/parcel/:parcel, where :id is the carnet_id of the carnê and :parcel is the number of the installment for which you want to update the due date (for example: 3 - if it is the third installment that you want to change the due date).

If you want, you can explore and learn more about this resource using our Playground.

The example below shows how this can be done, using the SDK's available:

<?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 = desenvolvimento e false = producao)
];
// $carnet_id refere-se ao ID do carnê desejado e parcel indica o número da parcela desejada
$params = ['id' => $carnet_id, 'parcel' => 1];
$body = [
'expire_at' => '2018-01-01'
];
try {
$api = new Gerencianet($options);
$carnet = $api->updateParcel($params, $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());
}

a) Hierarchical structure of Schema attributes that can be used:

"id": "/CarnetParcelUpdate"
"expire_at"

To more details, click here and explore it in our Playground.


b) Attributes that can be used to change the due date of the carnê installment:

AttributeDescriptionRequiredType
expire_atDue date of the specified installment of the carnê. The interval between the installments of a booklet is always 1 (one) month between them.

Format: YYYY-MM-DD		YesString

4) Cancel a carnê

Allows you to cancel a specific carnê. For this, you must inform the carnet_id that you want to cancel.

To cancel a certain carnê, you must send a PUT request to the route /v1/carnet/:id/cancel, where :id is the carnet_id of the carnê

If you want, you can explore and learn more about this resource using our Playground.

The example below shows how this can be done, using the SDK's available:

<?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 = desenvolvimento e false = producao)
];
// $carnet_id refere-se ao ID do carnê desejado
$params = [
'id' => $carnet_id
];
try {
$api = new Gerencianet($options);
$response = $api->cancelCarnet($params, []);
print_r($response);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

5) Cancel specific installment of a carnê

Allows you to cancel a specific portion of an existing carnê. To do so, you must inform the carnet_id and the number of the parcel you wish to cancel.

To cancel a specific installment of a carnê, you must send a PUT request to the route /v1/carnet/:id/parcel/:parcel/cancel, where :id is the carnet_id of the carnê and :parcel is the number of the installment you want to cancel (for example: 3 - if it is the third installment that you want to cancel).

If you want, you can explore and learn more about this resource using our Playground.

The example below shows how this can be done, using the SDK's available:

<?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 = desenvolvimento e false = producao)
];
// $carnet_id refere-se ao ID do carnê desejado e parcel indica o número da parcela desejada
$params = ['id' => $carnet_id, 'parcel' => 1];
try {
$api = new Gerencianet($options);
$response = $api->cancelParcel($params, []);
print_r($response);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

6) Resend carnê by email

It is possible that the carnê will be resent to a valid email address.

To resend a carnê by email, you must send a POST request to the route /v1/carnet/:id/resend, where :id is the carnet_id of the carnê you want to resend.

If you want, you can explore and learn more about this resource using our Playground.

The example below shows how this can be done, using the SDK's available:

<?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 = desenvolvimento e false = producao)
];
// $carnet_id refere-se ao ID do carnê desejado
$params = [
'id' => $carnet_id
];
$body = [
'email' => 'oldbuck@gerencianet.com.br'
];
try {
$api = new Gerencianet($options);
$response = $api->resendCarnet($params, $body);
print_r($response);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

a) Hierarchical structure of Schema attributes that can be used:

"id": "/CarnetResend"
"email"

To more details, click here and explore it in our Playground.


b) Attribute that can be used to resend carnê by email:

AttributeDescriptionRequiredType
emailPlease provide a valid email address to which the carnê should be sent.YesString

7) Resend specific installment of a carnê by email

It is possible that a specific installment of a carnê will be resent to a valid email address. To do so, you must enter the carnet_id.

To resend the parcel, it must have the status waiting.

To resend a specific parcel of a carnê by email, you must send a POST request to the route /v1/carnet/:id/parcel/:parcel/resend , where :id is the carnet_id of the carnê and :parcel is the parcel number you want to resend by email (for example: 3 - if it is the third installment you want to resend by email).

If you want, you can explore and learn more about this resource using our Playground.

The example below shows how this can be done, using the SDK's available:

<?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 = desenvolvimento e false = producao)
];
// $carnet_id refere-se ao ID do carnê desejado e parcel indica o número da parcela desejada
$params = ['id' => $carnet_id, 'parcel' => 1];
$body = [
'email' => 'oldbuck@gerencianet.com.br'
];
try {
$api = new Gerencianet($options);
$response = $api->resendParcel($params, $body);
print_r($response);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

a) Hierarchical structure of Schema attributes that can be used:

"id": "/CarnetParcelResend"
"email"

To more details, click here and explore it in our Playground.

b) Attributes that can be used to resend carnê installments by e-mail:

AttibuteDescriptionRequiredType
emailPlease provide a valid email address to which the carnê should be sent .YesString

8) Add information to the carnê's history

The history of a carnê is similar to the history of a transaction. However, it reflects the actions that the carnê itself suffered. And, in the same way, it is possible to add personalized messages to the history of a carnê, without influencing in the flow of it.

To add custom messages to a carnê's history, you must send a POST request to the /v1/carnet/:id/history route, where :id is the carnet_id of the dcarnê.

If you want, you can explore and learn more about this resource using our Playground.

The example below shows how this can be done, using the SDK's available:

<?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 = desenvolvimento e false = producao)
];
// $carnet_id refere-se ao ID do carnê desejado
$params = [
'id' => $carnet_id
];
$body = [
'description' => 'This carnet is about a service'
];
try {
$api = new Gerencianet($options);
$response = $api->createCarnetHistory($params, $body);
print_r($response);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

a) Hierarchical structure of Schema attributes that can be used:

"id": "/CarnetHistory"
"description"

To more details, click here and explore it in our Playground.


Attributes that can be used to add messages to the carnê's history:

AttributeDescriptionRequiredType
descriptionPallows adding information to the carnê's history without influencing its flow.
Minimum of 1 character and maximum of 255 characters .		YesString

9. Mark as paid a certain installment of a carnê

For details on how to mark as paid a certain installment of carnê, see this link .