API Reference

Calcular pegada de carbono

post https://sandbox.api.compensa.eco/calculator

Realizar o cálculo da pegada de carbono para diversos tipos de fretes

Com a Compensa API, o cálculo da pegada de carbono de seus fretes pode ser feita de maneira bem simples e direta.

Vamos começar entendendo como deve ser criado o payload de input, para depois entender a resposta que a API retorna.

⬆️ Montando o input de dados

A calculadora da Compensa aceita 30+ tipos diferentes de combinações de inputs para o payload do request. Para tal, temos algumas configurações a ser feitas:

Autenticação

O request para o endpoint de cálculo é autenticado. A autenticação deve ser feita com o JWT obtido como resposta do endpoint de autenticar usuário, nos headers da requisição:

headers = {
  "Authorization": f"Bearer {token}"
}

Configurações iniciais

1. Abrangência do frete

A Compensa API permite que você faça o cálculo para fretes nacionais e internacionais. Esse configuração é feita no campo coverage do payload.

2. Modal de transporte principal

Você pode calcular suas emissões com fretes realizados via modal Terrestre, Aéreo ou Marítimo.

📘

Não sabe qual foi o modal utilizado?

Além disso, existe a opção "Modal desconhecido", em que a API usa uma heurística para determinar qual foi o modal utilizado, com base na distância percorrida e no tempo de entrega.

Esta configuração é feita no campo main_modal do payload de entrada.

3. Modelo de contratação do frete

O cálculo também pode ser feito para fretes sob modelo Fracionado ou Dedicado.

🚧

Exceções:

  • Para fretes aéreos, apenas o modelo fracionado está disponível.
  • Já para fretes marítimos, os modelos disponíveis são Contêiner fracionado (LCL), Contêiner dedicado (FCL) ou Carga não-conteinerizada.

Esta configuração é realizada no campo contract_modal do payload.

4. Dado disponível para o cálculo da distância

Uma parte importante do cálculo da pegada de carbono dos fretes é a distância percorrida no trajeto. Para tal, podem ser informados CEP de partida e destino, Cidade de partida e destino ou a distância percorrida em si.

🚧

Exceções:

  • Para fretes marítimos, a opção "distância percorrida" não está disponível.
  • Para fretes internacionais, não é possível informar os CEPs de partida e destino.

Esta configuração não é feita num campo específico do payload, mas sim nos campos de cada frete.

Tipos de payloads para a listagem de fretes

A Compensa API aceita como input um array de diferentes fretes, dada a mesma configuração de abrangência, modal de transporte e modelo de contratação.

Abaixo, estão listados todos os tipos de inputs aceitos na API. Os nomes dos inputs estão montados da seguinte forma:

FRETE <ABRANGÊNCIA> <MODAL> <MODELO DE CONTRATAÇÃO> COM <DADO PARA CÁLCULO DA DISTÂNCIA>

Vamos pegar um exemplo para esclarecer:

Exemplo de payload

FRETE_NACIONAL_MODALDESCONHECIDO_FRACIONADO_COMCIDADES:

  • coverage: national, pois o frete é nacional
  • main_modal: unknown, pois o modal é desconhecido
  • contract_modal: fractioned, pois o modelo é fracionado
  • data: array de fretes informando a cidade de partida e destino

O objeto data tem os campos bem descritos para cada um dos 30+ tipos de inputs listados abaixo.

⬇️ Entendendo a resposta

A Compensa API calcula as emissões de diferentes gases de efeito estufa. São eles:

  • CO2 - gás carbônico
  • CH4 - metano
  • N2O - óxido nitroso
  • CO2 biogênico - relacionado ao ciclo natural do carbono
  • CO2 equivalente (CO2e) - utilizado para compilar as emissões dos diferentes gases, com base no potencial de aquecimento global de cada um deles

Resposta sem erros - cálculo bem sucedido

Este é um objeto de resposta padrão:

{
    "message": "the calculation was successful",
    "modal": "land",
    "coverage": "national",
    "contract": "fractioned",
    "emission": [
        {
            "input": {
                "date": "2023-06-06",
                "cep_origin": "70070080",
                "cep_destination": "04602000",
                "total_weight": 876,
                "refrigerated_cargo": false,
                "freight_goal": "Entrega para cliente",
                "payment_modal": "FOB",
                "own_or_outsourced": "terceiro",
                "vehicle_type": ""
            },
            "distance": 1018,
            "fuel_quantity": 35.04363214303802,
            "fuel_type": "",
            "first_mile": {
                "emission_factor": {
                    "Name": "",
                    "Id": "",
                    "Category": "",
                    "Fuel": ""
                },
                "distance": 0,
                "ttw_emission": {
                    "co2e": 0,
                    "co2": 0,
                    "ch4": 0,
                    "n2o": 0,
                    "co2_biogenic": 0
                },
                "wtt_emission": {
                    "co2e": 0,
                    "co2": 0,
                    "ch4": 0,
                    "n2o": 0,
                    "co2_biogenic": 0
                },
                "total_emission": {
                    "co2e": 0,
                    "co2": 0,
                    "ch4": 0,
                    "n2o": 0,
                    "co2_biogenic": 0
                },
                "fuel_quantity": 0
            },
            "mid_mile": {
                "emission_factor": {
                    "Name": "Caminhão - caminhão (média)",
                    "Id": "f26a1a0c5d9949abb00a79f0da375c27",
                    "Category": "land",
                    "Fuel": "Óleo Diesel (comercial)"
                },
                "distance": 1013.2,
                "ttw_emission": {
                    "co2e": 81.154341192,
                    "co2": 79.85938648320001,
                    "ch4": 0.005325379200000001,
                    "n2o": 0.004437816000000001,
                    "co2_biogenic": 8.2871775984
                },
                "wtt_emission": {
                    "co2e": 19.808635497600005,
                    "co2": 15.7542468,
                    "ch4": 0.11982103200000001,
                    "n2o": 0.0026626896000000004,
                    "co2_biogenic": 0
                },
                "total_emission": {
                    "co2e": 100.96297668960001,
                    "co2": 95.61363328320002,
                    "ch4": 0.1251464112,
                    "n2o": 0.007100505600000001,
                    "co2_biogenic": 8.2871775984
                },
                "fuel_quantity": 34.08854545520845
            },
            "last_mile": {
                "emission_factor": {
                    "Name": "Van - média (até 3,5 toneladas)",
                    "Id": "5ed6ad24b6074cfdb3049132ff9b93ce",
                    "Category": "land",
                    "Fuel": "Óleo Diesel (comercial)"
                },
                "distance": 4.8,
                "ttw_emission": {
                    "co2e": 2.273766624,
                    "co2": 2.2374876095999996,
                    "ch4": 0.0001513728,
                    "n2o": 0.0001219392,
                    "co2_biogenic": 0.2321806464
                },
                "wtt_emission": {
                    "co2e": 0.5549957568,
                    "co2": 0.44140308480000007,
                    "ch4": 0.0033554304,
                    "n2o": 0.0000756864,
                    "co2_biogenic": 0
                },
                "total_emission": {
                    "co2e": 2.8287623807999998,
                    "co2": 2.6788906943999997,
                    "ch4": 0.0035068032000000002,
                    "n2o": 0.00019762559999999998,
                    "co2_biogenic": 0.2321806464
                },
                "fuel_quantity": 0.955086687829573
            },
            "total_emission": {
                "co2e": 103.79173907040001,
                "co2": 98.29252397760001,
                "ch4": 0.1286532144,
                "n2o": 0.007298131200000001,
                "co2_biogenic": 8.5193582448
            },
            "scope": [
                {
                    "scope": "Escopo 3",
                    "category": "Categoria 9",
                    "emission": {
                        "co2e": 103.79173907040001,
                        "co2": 98.29252397760001,
                        "ch4": 0.1286532144,
                        "n2o": 0.007298131200000001,
                        "co2_biogenic": 8.5193582448
                    }
                }
            ],
            "calculated": true,
            "errors": {
                "column": "",
                "message": ""
            }
        }
    ]
}

Vamos entendê-lo, atributo a atributo.

  • message: mensagem vinda da API. Se for diferente de "The calculation was successful.", houve erro de cálculo em algum dos fretes.
  • modal: modal informado no input
  • coverage: abragência informada no input
  • contract: modelo de contratação informado no input
  • emission: lista de fretes calculados
    • input: input informado para este frete
    • distance: distância total calculada, em km
    • first_mile, mid_mile, last_mile: informa as emissões relativas a cada etapa do frete (first mile, mid mile e last mile). Inclui as distâncias percorridas em km, assim como as emissões well-to-tank, tank-to-wheel e totais dos diversos gases em kg.
    • total_emission: emissões totais de cada gás, em kg
    • scope: emissões discretizadas por escopo e categoria para cada gás, também em kg
    • calculated: indica se o cálculo foi bem sucedido. Se não for true, houve algum erro no cálculo.
    • errors: indica qual foi o erro obtido no cálculo. Se os campos estão vazios, não houve erros.

Resposta com erro no cálculo

{
    "message": "the calculation was completed with errors",
    "modal": "land",
    "coverage": "national",
    "contract": "fractioned",
    "emission": [
        {
            "input": {
                "date": "2023-06-06",
                "cep_origin": "10101010",
                "cep_destination": "04602000",
                "total_weight": 876,
                "refrigerated_cargo": false,
                "freight_goal": "Entrega para cliente",
                "payment_modal": "FOB",
                "own_or_outsourced": "terceiro"
            },
            "distance": 0,
            "fuel_quantity": 0,
            "fuel_type": "",
            "first_mile": {
                "emission_factor": {
                    "Name": "",
                    "Id": "",
                    "Category": "",
                    "Fuel": ""
                },
                "distance": 0,
                "ttw_emission": {
                    "co2e": 0,
                    "co2": 0,
                    "ch4": 0,
                    "n2o": 0,
                    "co2_biogenic": 0
                },
                "wtt_emission": {
                    "co2e": 0,
                    "co2": 0,
                    "ch4": 0,
                    "n2o": 0,
                    "co2_biogenic": 0
                },
                "total_emission": {
                    "co2e": 0,
                    "co2": 0,
                    "ch4": 0,
                    "n2o": 0,
                    "co2_biogenic": 0
                },
                "fuel_quantity": 0
            },
            "mid_mile": {
                "emission_factor": {
                    "Name": "",
                    "Id": "",
                    "Category": "",
                    "Fuel": ""
                },
                "distance": 0,
                "ttw_emission": {
                    "co2e": 0,
                    "co2": 0,
                    "ch4": 0,
                    "n2o": 0,
                    "co2_biogenic": 0
                },
                "wtt_emission": {
                    "co2e": 0,
                    "co2": 0,
                    "ch4": 0,
                    "n2o": 0,
                    "co2_biogenic": 0
                },
                "total_emission": {
                    "co2e": 0,
                    "co2": 0,
                    "ch4": 0,
                    "n2o": 0,
                    "co2_biogenic": 0
                },
                "fuel_quantity": 0
            },
            "last_mile": {
                "emission_factor": {
                    "Name": "",
                    "Id": "",
                    "Category": "",
                    "Fuel": ""
                },
                "distance": 0,
                "ttw_emission": {
                    "co2e": 0,
                    "co2": 0,
                    "ch4": 0,
                    "n2o": 0,
                    "co2_biogenic": 0
                },
                "wtt_emission": {
                    "co2e": 0,
                    "co2": 0,
                    "ch4": 0,
                    "n2o": 0,
                    "co2_biogenic": 0
                },
                "total_emission": {
                    "co2e": 0,
                    "co2": 0,
                    "ch4": 0,
                    "n2o": 0,
                    "co2_biogenic": 0
                },
                "fuel_quantity": 0
            },
            "total_emission": {
                "co2e": 0,
                "co2": 0,
                "ch4": 0,
                "n2o": 0,
                "co2_biogenic": 0
            },
            "scope": [
                {
                    "scope": "Escopo 3",
                    "category": "Categoria 9",
                    "emission": {
                        "co2e": 0,
                        "co2": 0,
                        "ch4": 0,
                        "n2o": 0,
                        "co2_biogenic": 0
                    }
                }
            ],
            "calculated": false,
            "errors": {
                "column": "route",
                "message": "Route not available for informed locations"
            }
        }
    ]
}

Nota-se, na resposta com algum erro, que o frete em que houve o erro vem com quase todos os campos vazios ou zerados.

O atributo que indica com clareza se houve algum erro de cálculo para determinado frete é calculated, que foi avaliado para false por conta do erro encontrado no cálculo da rota entre os CEPs informados.

Se forem informados múltiplos fretes para realizar o cálculo simultaneamente, e algum deles apresentar algum erro, a mensagem informada será "The calculation was completed with errors.".

Language
Authorization
Bearer
JWT
URL
Click Try It! to start a request and see the response here!