Pedidos

Na API B2B, um pedido é uma chamada de uma quantidade específica de VCU, cujo valor será debitado do saldo do cliente e um certificado Carbonext emitido em seu nome ou de outra pessoa, através do atributo `certificateRecipientInfo``.

Pedido [POST]

BASE URL

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

Esta requisição irá criar um pedido. Em nossa plataforma, vamos emitir um certificado CARBOENXT cada pedido com status PAGO, esses pedidos vão acumular créditos que irão resultar em um certificado VERRA (emitidos na plataforma do VERRA). Entretanto, a plataforma do VERRA só permite a emissão de créditos com valores inteiros, por exemplo, um, dois, três, dez, etc.

Para ajudar a desenhar o melhor cenário de integração, nós disponibilizamos diferentes formas de acumular créditos para emissão de certificados VERRA (aposentadorias). Utilizando o atributo certificateRecipientInfo é possível determinar o destinatário dos certificados CARBONEXT e VERRA de forma separada. As opções são detalhadas abaixo:

Opções de aposentadorias

Você e recebe o certificado CARBONEXT e a quantidade de créditos do pedido é acumulada para o seu CNPJ. Neste cenário você NÃO precisa enviar o atributo certificateRecipientInfo.

{
        "vcuAmount": 0.02,
        "targetCurrency": "BRL",
        "payWithBalance": true
}

Outra pessoa recebe o certificado CARBONEXT e a quantidade de créditos do pedido é acumulada para o seu CNPJ. Neste cenário você precisa enviar as informações do destinatário do certificado Carbonext e enviar as suas informações como destinatário do certificado VERRA para que os créditos sejam acumulados para o seu CNPJ.

{
        "vcuAmount": 0.02,
        "targetCurrency": "BRL",
        "payWithBalance": true,
        "certificateRecipientInfo":{
                "name": "Example First",
                "email": "example@email.com",
                "taxId": "000.000.000-00",
                "retirementName": "<your-name>",
                "retirementEmail": "<your-email>",
                "retirementTaxId": "<your-taxid>"
        }
}

Outra pessoa recebe o certificado CARBONEXT e a quantidade do pedido é acumulada para o CPF/CNPJ dessa mesma pessoa. Neste cenário você só precisa enviar as informações do destinatário. O certificado CARBONEXT será emitido e os créditos serão acumulados para o CPF/CNPJ informado.

{
        "vcuAmount": 0.02,
        "targetCurrency": "BRL",
        "payWithBalance": true,
        "certificateRecipientInfo":{
                "name": "Example First",
                "email": "example@email.com",
                "taxId": "000.000.000-00"
        }
}

Pessoas diferentes recebem o certificado CARBONEXT e o certificado VERRA. A quantidade do pedido é acumulada para o CPF/CNPJ da pessoa destinatária do certificado VERRA. Nesse cenário, assim como no cenário 2, você envia as informações do destinatário do certificado CARBONEXT e do destinatário do certificado VERRA.

{
        "vcuAmount": 0.02,
        "targetCurrency": "BRL",
        "payWithBalance": true,
        "certificateRecipientInfo":{
                "name": "Example First",
                "email": "example@email.com",
                "taxId": "000.000.000-00",
                "retirementName": "Retirement Recipient",
                "retirementEmail": "retirement-recipient@email.com",
                "retirementTaxId": "00.000.000/0001-55"
        }
}

Atributos de Requisição

Atributo	Descrição
vcuAmount	A quantidade de VCUs atribuída ao pedido
targetCurrency	A moeda desejada para o pedido a ser cobrado
payWithBalance	Flag que informa se você deseja usar o saldo atual para emitir o pedido. Caso o pedido seja emitido com o saldo, seu status será alterado para PAGO automaticamente e o certificado será emitido em alguns instantes
certificateRecipientInfo	Informações da pessoa para quem o certificado será emitido, se não for preenchido será emitido com dados de sua empresa
metaData	Informações adicionais do pedido

CertificateRecipientInfo	Descrição
name	Nome da pessoa para quem o certificado será emitido
email	E-mail da pessoa para quem o certificado será emitido. O certificado será enviado para este e-mail
taxId	Número do documento (CPF/CNPJ) da pessoa para quem o certificado será emitido
retirementName	Nome da pessoa para quem o certificado VERRA será emitido
RetirementEmail	E-mail da pessoa para quem o certificado VERRA será emitido. O certificado será enviado para este e-mail
retirementTaxId	Número do documento (CPF/CNPJ) da pessoa para quem o certificado VERRA será emitido. Os créditos serão acumulados para este CPF/CNPJ e o certificado será emitido sempre que o saldo for maior que 1 VCU

Atributos de Resposta

Atributo	Descrição
id	O ID do pedido gerado
vcuAmount	A quantidade total de VCUs solicitada no pedido
vcuUnitPrice	O preço unitário de um VCU no momento da criação do pedido
targetCurrency	A moeda em que o pedido será cobrado
status	Nome do status atual do pedido
createdAt	A data e hora em que o pedido foi criado
metaData	Campo `string` para inserir informações adicionais do pedido. Máximo de 500 caracteres.
notifyCertificateTo	Campo string com email para envio do certificado
type	A forma de pagamento
paymentDate	A data e hora em que o pedido foi pago
retireForRecipient	Informa que o pedido será aposentado para outra empresa

CertificateRecipientInfo	Descrição
name	Nome da pessoa para quem o certificado será emitido
email	E-mail da pessoa para quem o certificado será emitido. O certificado será enviado para este e-mail
taxId	Número do documento (CPF/CNPJ) da pessoa para quem o certificado será emitido

Exemplo de Requisição

var axios = require('axios');
var data = JSON.stringify({
        "vcuAmount": 0.02,
        "targetCurrency": "BRL",
        "payWithBalance": true,
        "certificateRecipientInfo": {
                "name": "Example First",
                "email": "example@email.com",
                "taxId": "000.000.000-00",
                "retirementName": "Example Second",
                "retirementEmail": "second@email.com",
                "retirementTaxId": "000.000.000-01"
        }
});

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);
        });

Exemplo de Resposta

{
        "id": "4158d5d1-9364-46e6-8d0d-451f528261e7",
        "vcuAmount": 0.02,
        "vcuUnitPrice": 110.0,
        "totalPrice": 2.200,
        "targetCurrency": "BRL",
        "status": "Issued",
        "createdAt": "2022-07-24T18:26:44.4176783Z",
        "notifyCertificateTo": null,
        "type": "Postpaid",
        "paymentDate": null,
        "metaData": null,
        "payWithBalance": true,
        "certificateRecipientInfo": {
                "name": "Example First",
                "email": "example@email.com",
                "taxId": "000.000.000-00"
  }
}

Pedidos [GET]

BASE URL

https://api-b2b-hml.carbonext.com.br/v1/orders?page=1&page-size=6

Esta solicitação retorna uma lista paginada de pedidos.

Atributos de resposta

Atributo	Descrição
items	Um array de pedidos paginados do cliente

Exemplo de Requisição

var axios = require('axios');

var config = {
        method: 'get',
        url: 'https://api-b2b-hml.carbonext.com.br/v1/orders?page=1&page-size=100&sort-by=createdAt_desc',
        headers: { 
                'Authorization': 'Bearer <access_token>',
        }
};

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

Exemplo de Resposta

{
        "items": [
                {
                        "id": "4158d5d1-9364-46e6-8d0d-451f528261e7",
                        "vcuAmount": 0.02,
                        "vcuUnitPrice": 110.0,
                        "totalPrice": 2.200,
                        "targetCurrency": "BRL",
                        "status": "Cancelled",
                        "createdAt": "2022-07-24T18:26:44.417678",
                        "notifyCertificateTo": null,
                        "type": "Postpaid",
                        "paymentDate": null,
                        "metaData": null,
                        "retireForRecipient": false,
                        "certificateRecipientInfo": {
                                "name": "Example First",
                                "email": "example@email.com",
                                "taxId": "000.000.000-00"
                        },
                        "invoices": [],
                        "subscriptions": []
                  },
                  {
                        "id": "07c8543f-752f-43c7-af65-04a6cf3c8841",
                        "vcuAmount": 0.02,
                        "vcuUnitPrice": 110.00,
                        "totalPrice": 2.2000,
                        "targetCurrency": "BRL",
                        "status": "Issued",
                        "createdAt": "2022-07-21T19:11:05.698421",
                        "notifyCertificateTo": null,
                        "type": "Postpaid",
                        "paymentDate": null,
                        "metaData": null,
                        "retireForRecipient": false,
                        "certificateRecipientInfo": {
                                "name": "Example First",
                                "email": "example@email.com",
                                "taxId": "000.000.000-00"
                        },
                        "invoices": [],
                        "subscriptions": []
                }
        ],
        "pageIndex": 1,
        "totalPages": 1,
        "totalCount": 2,
        "aggregations": null,
        "hasPreviousPage": false,
        "hasNextPage": false
}

PARAMS

page: 1
page-size: 6

Cancelar Pedido [POST]

BASE URL

https://api-b2b-hml.carbonext.com.br/v1/orders/:orderId/cancel

Esta solicitação cancela um pedido pendente de pagamento (status Issued).

Atributos de Resposta

Atributo	Descrição
id	O ID do pedido gerado
vcuAmount	A quantidade total de VCU solicitada no pedido
vcuUnitPrice	O preço unitário de um VCU no momento da criação do pedido
targetCurrency	A moeda em que o pedido será cobrado
status	Nome do status atual do pedido, o valor será "Cancelled"
createdAt	A data e hora em que o pedido foi criado
metaData	Campo de string que você pode usar para escrever informações extras sobre seu pedido. Até 500 caracteres.

Exemplo de Requisição

var axios = require('axios');

var config = {
    method: 'post',
    url: 'https://api-b2b-hml.carbonext.com.br/v1/orders/4158d5d1-9364-46e6-8d0d-451f528261e7/cancel',
    headers: { 
        'Authorization': 'Bearer <access_token>',
    }
};

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

Exemplo de Resposta

{
        "id": "4158d5d1-9364-46e6-8d0d-451f528261e7",
        "vcuAmount": 0.02,
        "vcuUnitPrice": 110.0,
        "totalPrice": 2.200,
        "targetCurrency": "BRL",
        "status": "Cancelled",
        "createdAt": "2022-07-24T18:26:44.417678",
        "notifyCertificateTo": null,
        "type": "Postpaid",
        "paymentDate": null,
        "metaData": null,
        "retireForRecipient": false,
        "certificateRecipientInfo": {
                "name": "Example First",
                "email": "example@email.com",
                "taxId": "000.000.000-00"
        }
}

PATH VARIABLES

orderId: 4158d5d1-9364-46e6-8d0d-451f528261e7

Cancelar Pedidos [POST]

BASE URL

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

Os pedidos também podem ser cancelados em lotes.

Parâmetros de Requisição

Parâmetro	Descrição
ordersIds	Uma lista de IDs dos pedidos a serem cancelados

Exemplo de Requisição

var axios = require('axios');
var data = JSON.stringify({
        "ordersIds": [
                "c99a2da7-ab55-4156-ac4e-d6f3df7d3d28",
                "815873f3-54d3-4e11-bbbd-05f76aaec3df"
        ]
});

var config = {
        method: 'post',
        url: 'https://api-b2b-hml.carbonext.com.br/v1/orders/cancel',
        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);
        });

Exemplo de Resposta

{
     true
}

Pedidos

Pedido [POST]​

Opções de aposentadorias​

Exemplo de Requisição​

Exemplo de Resposta​

Pedidos [GET]​

Exemplo de Requisição​

Exemplo de Resposta​

Cancelar Pedido [POST]​

Exemplo de Requisição​

Exemplo de Resposta​

Cancelar Pedidos [POST]​

Exemplo de Requisição​

Exemplo de Resposta​

Pedido [POST]

Opções de aposentadorias

Exemplo de Requisição

Exemplo de Resposta

Pedidos [GET]

Exemplo de Requisição

Exemplo de Resposta

Cancelar Pedido [POST]

Exemplo de Requisição

Exemplo de Resposta

Cancelar Pedidos [POST]

Exemplo de Requisição

Exemplo de Resposta