IntroductionIntrodução

What is the Partners API?O que é a Partners API?

Ecomilhas turns low-carbon trips — walking, cycling, public transport, ethanol and electric vehicles — into rewards, backed by GPS validation and a GHG Protocol methodology with limited assurance by KPMG. The Partners API lets your product plug into that engine: create and authenticate end users under your company, read their verified trips and balances, offer prize redemption and pull consolidated impact metrics for ESG reporting. A Ecomilhas transforma deslocamentos de baixo carbono — a pé, bicicleta, transporte público, etanol e veículos elétricos — em recompensas, com validação por GPS e metodologia GHG Protocol com asseguração limitada da KPMG. A Partners API conecta o seu produto a esse motor: crie e autentique usuários finais sob a sua empresa, leia trajetos e saldos verificados, ofereça resgate de prêmios e extraia métricas consolidadas de impacto para o reporte ESG.

AuthenticationAutenticação#

The API uses two credentials, combined per route: A API usa duas credenciais, combinadas conforme a rota:

• x-api-key — identifies your company. Issued in the admin panel; required on every partner route.identifica a sua empresa. Gerada no painel administrativo; obrigatória em toda rota de parceiro.
• Authorization: Bearer <accessToken> — identifies the end user. Returned by POST /auth/login or POST /auth/create-account; required on user routes (profile, trips, cash prizes). Renew with POST /auth/refresh before expiresAt.identifica o usuário final. Retornado por POST /auth/login ou POST /auth/create-account; obrigatório nas rotas de usuário (perfil, viagens, cash prizes). Renove com POST /auth/refresh antes de expiresAt.

# Base URL
https://ecomilhas-api-h-homologation.up.railway.app

# Conventions
Versioning:  path (/partners/v1)
Dates:       ISO 8601
Lists:       paginated (?page=1&limit=20)

Quickstart#

Three calls take you from zero to real data. Every request below runs against the live environment — you can also fire them from the playground without writing code. Três chamadas levam você do zero ao dado real. Toda requisição abaixo roda no ambiente ao vivo — você também pode dispará-las pelo playground sem escrever código.

# Creates the end user and links them to your company (the x-api-key owner)
curl -X POST https://ecomilhas-api-h-homologation.up.railway.app/partners/v1/auth/create-account \
  -H "x-api-key: $ECOMILHAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "novo.usuario@exemplo.com",
    "password": "senha-forte-123",
    "username": "Nome do Usuário"
  }'

# 201 → {"userId": 12345, "accessToken": "eyJ…", "refreshToken": "…", "expiresAt": "2026-08-18T18:00:00Z"}

# Verified trips of the authenticated user (GPS-validated, paginated)
curl "https://ecomilhas-api-h-homologation.up.railway.app/partners/v1/user/trips?page=1&limit=20" \
  -H "x-api-key: $ECOMILHAS_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 200 →
{
  "elements": [{
    "id": 101,
    "ecomilesValue": 12.5,
    "primaryVehicleType": "bicycle",
    "totalDistanceMeters": 4200,
    "wasAllApproved": true
  }],
  "totalElements": 1
}

# Company dashboard: users, monthly trips and avoided CO2 (approved trips)
curl "https://ecomilhas-api-h-homologation.up.railway.app/partners/v1/metrics?year=2026&month=9" \
  -H "x-api-key: $ECOMILHAS_KEY"

# 200 →
{
  "usersCount": 142,
  "tripsSubmittedCount": 318,
  "avoidedCo2Tons": 1.234
}

Integration pathsCaminhos de integração#

You don't need an engineering team to start. Pick the path that fits your organization today and upgrade later — everything runs on the same platform. Você não precisa de time de engenharia para começar. Escolha o caminho que cabe na sua organização hoje e evolua depois — tudo roda na mesma plataforma.

1. Program without ITPrograma sem TI

   For HR, benefits and sustainability teams: your people use the Ecomilhas app, you follow results in the business dashboard. No integration, live in weeks. Talk to our team →Para times de RH, benefícios e sustentabilidade: seus colaboradores usam o app Ecomilhas e você acompanha os resultados no painel business. Sem integração, no ar em semanas. Falar com nosso time →

2. Deep link into the Ecomilhas appDeep link para o app Ecomilhas

   Your product creates the session and hands the user off to the Ecomilhas app already signed in, via single-use magic link (POST /auth/app-link-token). Minimal code, full experience.Seu produto cria a sessão e entrega o usuário no app Ecomilhas já autenticado, via link mágico de uso único (POST /auth/app-link-token). Pouco código, experiência completa.

3. Full APIAPI completa

   For engineering teams: build your own experience with the endpoints below — sessions, trips, prizes and metrics inside your product. Request keys →Para times de engenharia: construa sua própria experiência com os endpoints abaixo — sessões, viagens, prêmios e métricas dentro do seu produto. Solicitar chaves →

Typical journey: conversation → sandbox keys with synthetic data → pilot with a real group → production rollout with support and auditable reporting. Jornada típica: conversa → chaves de sandbox com dados sintéticos → piloto com um grupo real → rollout de produção com suporte e reporte auditável.

API referenceReferência da API#

REST, path-versioned (/partners/v1), ISO 8601 dates, paginated lists. Generated from the implementation — always in sync with the code. Try every call in the playground. REST, versionamento por path (/partners/v1), datas ISO 8601, listas paginadas. Gerada a partir da implementação — sempre em sincronia com o código. Teste cada chamada no playground.

Webhooks#

Security & complianceSegurança & conformidade#

• LGPD / GDPR — data minimization, deletion propagation; companies only ever see aggregates — never raw location.minimização de dados, propagação de exclusão; empresas só veem agregados — nunca localização bruta.
• GHG Protocol + MRV — versioned emission factors per modal/region; every tCO2e traceable to its trips. Methodology with limited assurance by KPMG.fatores de emissão versionados por modal/região; cada tCO2e rastreável até seus trajetos. Metodologia com asseguração limitada da KPMG.
• Anti-fraud — speed-vs-modal checks, spatio-temporal dedup, idempotency by external id, two-factor identity on the app.validação velocidade × modal, deduplicação espaço-temporal, idempotência por id externo, identidade com dois fatores no app.
• Mastercard MDES — card provisioning through network standards; the PAN is never exposed to partners.provisioning do cartão pelos padrões da bandeira; o PAN nunca é exposto a parceiros.
• Rate limiting & sandbox — tiered quotas and a full test environment before production keys.cotas por tier e ambiente de testes completo antes das chaves de produção.
• Hardened by default — TLS everywhere and strict security headers (CSP, X-Frame-Options, nosniff) on this portal.TLS em tudo e security headers estritos (CSP, X-Frame-Options, nosniff) neste portal.
• Responsible disclosure — found a vulnerability? See security.txt or write to contato@ecomiles.app.encontrou uma vulnerabilidade? Veja o security.txt ou escreva para contato@ecomiles.app.

PricingPreços#

Pricing scales with the volume of trips processed per month. Each tier includes a monthly fee; trips above the contracted tier are billed per trip at the overage rate. Values in euros. O preço escala com o volume de trajetos processados por mês. Cada faixa tem uma mensalidade; trajetos acima da faixa contratada são cobrados por trajeto, na tarifa de excedente. Valores em euro.

Setup & Sandbox is a one-time fee and includes test keys, synthetic data and onboarding. For pricing in BRL, annual agreements or enterprise volumes, contact contato@ecomiles.app. Setup e Sandbox é cobrança única e inclui chaves de teste, dados sintéticos e onboarding. Para valores em reais, contratos anuais ou volumes enterprise, fale com contato@ecomiles.app.

Roadmap#

Partners API v1 is live: auth, deep links, users & trips, cash prizes and company metrics. The next modules, in order: A Partners API v1 está no ar: auth, deep links, usuário & viagens, cash prizes e métricas da empresa. Os próximos módulos, em ordem:

SupportSuporte#