Ecomilhas API

⚠️

Status: em planejamento — nenhum endpoint descrito nesta página está disponível em produção. Conteúdo sujeito a alterações até o lançamento.

🟣

Integração de Inventário de Emissões (CO2e)

Conecte seu sistema de inventário à Ecomilhas e automatize o envio, processamento e consolidação dos seus dados de emissões — com rastreabilidade e conformidade ao GHG Protocol.

Atalhos

Próximos passos
Endpoints (MVP)
Segurança

1) O que é

A Ecomilhas está desenvolvendo uma API de integração para inventário de emissões (CO2e), permitindo que empresas conectem seus próprios sistemas (ERPs, planilhas, plataformas ESG) diretamente à Ecomilhas para automatizar:

envio de dados de atividade (energia, combustível, frete etc.)
processamento e validação
retorno de resultados consolidados (CO2e total + detalhamento)

O objetivo é eliminar processos manuais (planilhas, e-mails, uploads avulsos) e oferecer uma integração direta, rastreável e auditável.

2) Por que isso importa

Benefício	O que você ganha
⚙️ Menos trabalho manual	Dados saem do seu sistema e chegam à Ecomilhas automaticamente, sem retrabalho.
🔍 Rastreabilidade	Cada envio é identificado e auditável, facilitando conferência e histórico.
📐 Padronização	Estrutura alinhada ao GHG Protocol, por escopo/categoria/período.
⏱️ Tempo de resposta	Acompanhe status e obtenha resultados assim que disponíveis.
🏢 Escalabilidade	Consolidação para múltiplas unidades/filiais/centros de custo.

3) Como vai funcionar (visão rápida)

Fluxo

Seu sistema (ERP / planilha / plataforma ESG)
Envia dados (energia, combustível, transporte…)
Ecomilhas processa (fatores de emissão + validações)
Resultado consolidado (CO2e total, pronto para relatórios)

Passo a passo

Sua empresa é cadastrada como organização na Ecomilhas.
Você envia os dados de atividade do período.
A Ecomilhas processa e valida os dados, aplicando fatores de emissão apropriados.
Você consulta o status do processamento quando quiser.
Ao concluir, você obtém o resultado consolidado (total + detalhamento por escopo/categoria), pronto para relatórios, auditorias e BI.

4) O que a API vai permitir fazer

Funcionalidade	Descrição
Enviar inventário	Registrar um novo período/lote de emissões da sua organização.
Enviar dados de atividade	Enviar as linhas que compõem o inventário (quantidade, unidade, categoria).
Acompanhar processamento	Consultar status: recebido → processamento → concluído/erro.
Consultar resultados	Obter total de CO2e + detalhamento por escopo/categoria.
Webhook (opcional)	Notificação automática quando o resultado estiver pronto.

5) Endpoints mínimos (MVP)

Abaixo está uma visão resumida dos 4 endpoints principais previstos para o lançamento.

POST `/v1/inventories` — Criar inventário

// Request
{
  "external_id": "INV-CLIENTE-2026-01",
  "organization": { "external_org_id": "ORG-123", "name": "Empresa Exemplo LTDA" },
  "period_start": "2026-01-01",
  "period_end": "2026-01-31"
}

// Response (201)
{
  "inventory_id": "inv_9f2c1a",
  "external_id": "INV-CLIENTE-2026-01",
  "status": "DRAFT",
  "created_at": "2026-07-01T14:10:00Z"
}

POST `/v1/inventories/{inventory_id}/items:bulk` — Enviar itens (bulk)

// Request
{
  "items": [
    {
      "external_item_id": "LINE-001",
      "scope": "SCOPE_2",
      "category": "ELECTRICITY",
      "quantity": 12000,
      "unit": "kWh"
    }
  ]
}

// Response (202)
{ "inventory_id": "inv_9f2c1a", "accepted": 1, "rejected": 0, "status": "RECEIVED" }

GET `/v1/inventories/{inventory_id}` — Consultar status

// Response (200)
{
  "status": "PROCESSING",
  "items_total": 124,
  "items_valid": 120,
  "items_invalid": 4
}

GET `/v1/inventories/{inventory_id}/results` — Obter resultados

// Response (200)
{
  "status": "COMPLETED",
  "totals": {
    "tco2e_total": 82.41
  }
}

6) Status do inventário

Status	O que significa
`DRAFT`	Inventário criado, aguardando envio dos itens.
`RECEIVED`	Itens recebidos, aguardando processamento.
`PROCESSING`	Em cálculo e validação.
`COMPLETED`	Resultados consolidados disponíveis.
`FAILED`	Erro de validação ou processamento — requer correção e reenvio.

7) Segurança, padrões e público-alvo

Segurança e acesso

Autenticação por chave de API exclusiva por cliente/organização.
external_id / external_item_id para conciliação com seus registros.
Header Idempotency-Key para evitar duplicidade em reenvios acidentais.

Padrões adotados

Metodologia baseada no GHG Protocol (Escopo 1, 2 e 3).
Datas e períodos em ISO 8601.
Estrutura pronta para operações de MRV (monitoramento, relato e verificação).

Para quem é

Times de TI e Produto com sistemas próprios de inventário de CO2e.
Consultorias e integradores ESG (múltiplos clientes).
Empresas com necessidade de consolidação multiunidade.

Próximos passos

✅

Esta API está em fase de planejamento técnico. Se sua empresa quer integrar cedo ou tem requisitos específicos (formato, sistemas de origem, volume), fale com o time Ecomilhas para definirmos o escopo final juntos.

Email: developers@ecomiles.app

Documento de apresentação comercial — sujeito a alterações até o lançamento.

Detalhamento técnico completo disponível em api-inventory-documentation.md.