Skip to main content

Integrating

Step 1 - Acquiring the Access Token​

Using your endpoint testing software, create a request with the POST method and add the following approval URL to the API:

BASE URL
https://auth-hml.carbonext.com.br/auth/realms/co2free/protocol/openid-connect/token

In Body > x-www-form-urlencoded add the keys and their corresponding values following the request example below:

Example Request​

var axios = require('axios');
var qs = require('qs');
var data = qs.stringify({
        'client_id': '<your_client_id',
        'client_secret': '<your_client_secret>',
        'grant_type': 'client_credentials' 
});
var config = {
        method: 'post',
        url: 'https://auth-hml.carbonext.com.br/auth/realms/co2free/protocol/openid-connect/token',
        headers: { 
                'Content-Type': 'application/x-www-form-urlencoded'
        },
        data : data
};

axios(config)
        .then(function (response) {
                console.log(JSON.stringify(response.data));
        })
        .catch(function (error) {
                console.log(error);
        });

When sending the request, we will return the access_token that will allow us to interact with our endpoints.

Sample Answer​

{
        "access_token": "kRjvJJpQpwWHoWKi-K_5SO0w0dkAqiO2QudmyoJxlTI",
        "expires_in": 36000,
        "refresh_expires_in": 0,
        "token_type": "Bearer",
        "not-before-policy": 0,
        "scope": "profile email roles"
}

Step 2 - Querying the VCU Price​

Now that we have the necessary authorization, let's check the price of the VCU, create a request with the GET method and add the following URL:

BASE URL
https://api-b2b-hml.carbonext.com.br/v1/prices?vcu-amount=1

Note that we pass the amount of VCUs (vcu-amount) to the price query.

In Authorization, change the Type to Bearer Token and paste your access_token in Value.

Sample Request​

var axios = require('axios');

var config = {
        method: 'get',
        url: 'https://api-b2b-hml.carbonext.com.br/v1/prices?vcu-amount=1',
        headers: { 
                'Authorization': 'Bearer <access_token>'
        }
};

axios(config)
        .then(function (response) {
                console.log(JSON.stringify(response.data));
        })
        .catch(function (error) {
                console.log(error);
        });

Sample Answer​

{
        "vcuPrice": 110.5,
        "currency": "BRL"
}

Step 3 - Creating a VCU Order​

The time has come to place the first order, it is now that the amount of VCUs necessary to neutralize your emissions in the desired period will be indicated, create a new request with the POST method and add the URL:

BASE URL
https://api-b2b-hml.carbonext.com.br/v1/orders

In Authorization, change the Type to Bearer Token and paste your access_token in Value and in Body, select the type JSON with the following data:

{
        "vcuAmount":3,
        "targetCurrency":"BRL",
}

Sample Request​

var axios = require('axios');
var data = JSON.stringify({
        "vcuAmount": 3,
        "targetCurrency": "BRL"
});

var config = {
        method: 'post',
        url: 'https://api-b2b-hml.carbonext.com.br/v1/orders',
        headers: { 
                'Authorization': 'Bearer <access_token>', 
                'Content-Type': 'application/json'
        },
        data: data
};

axios(config)
        .then(function (response) {
                console.log(JSON.stringify(response.data));
        })
        .catch(function (error) {
                console.log(error);
        });

Sample Answer​

{
        "id": "5f9b8b6f-c8a1-48b1-be49-205fbb05a7db",
        "vcuAmount": 1.0,
        "vcuUnitPrice": 110.00,
        "totalPrice": 110.00,
        "targetCurrency": "BRL",
        "status": "Paid",
        "createdAt": "2023-03-03T18:10:48.1824733Z",
        "notifyCertificateTo": null,
        "type": "Prepaid",
        "paymentDate": "2023-03-03T18:10:48.1806031Z",
        "metaData": null,
        "retireForRecipient": false,
        "certificateRecipientInfo": {
                "name": "test test test",
                "email": "email@email.com.br",
                "taxId": "20.094.232/0001-63",
                "fileUploadKey": null,
                "origin": 7,
                "emailTemplateKey": null,
                "notificationEmailVariables": null,
                "fileTemplateKey": null,
                "certificateFileVariables": null
        }
}

Step 4 - Checking your Current Balance​

Now, you can check your updated balance, for that create a new request with the GET method and add the following URL.

BASE URL
https://api-b2b-hml.carbonext.com.br/v1/customers/balance

In Authorization, change the value of Type to Bearer Token and paste your access_token in Value.

Sample Request​

var axios = require('axios');

var config = {
        method: 'get',
        url: 'https://api-b2b-hml.carbonext.com.br/v1/customers/balance',
        headers: { 
                'Authorization': 'Bearer <access_token>'
        }
};

axios(config)
        .then(function (response) {
                console.log(JSON.stringify(response.data));
        })
        .catch(function (error) {
                console.log(error);
        });

Sample Answer​

{
        "startDate": "2022-07-12T14:12:13.714817",
        "endDate": "2022-07-21T17:00:25.0851306Z",
        "balancesByCurrency": [
                {
                        "currency": "BRL",
                        "vcuBalance": {
                                "type": "VCU",
                                "balance": 15.997878,
                                "credit": 16.0,
                                "debt": 37.53443683424,
                                "futureDebt": 9.0
                        }
                }
        ]
}
info

We'll see more about authorization requests and other concepts on the next page.