Referência da API

Documentação feita à mão para integradores que constroem sobre a plataforma multi-marca de aluguel de carros GreenFlow.

Chave de API demo — gire a sua

URL base: https://greenflow.live/api/v1/

Authorization: Bearer gfc_7s2wprmy_DWTZRBGBEV6La4dTOoFdMkEhWmWCsXdwc3zVMnqP

Início rápido

Três chamadas vão te levar do zero a uma reserva confirmada: listar frota, obter token, criar reserva. Tudo mais (webhooks, cupons, configuração do tenant) se apoia sobre esse fluxo central.

1. Teste sua chave

Bata em GET /me para confirmar que a chave resolve para seu tenant. Se retornar 401 aqui, o resto da API também vai.

bash

curl -s https://greenflow.live/api/v1/me \
  -H "Authorization: Bearer gfc_7s2wprmy_DWTZRBGBEV6La4dTOoFdMkEhWmWCsXdwc3zVMnqP"

2. Liste a frota para um intervalo de datas

POST em POST /fleet/list com datas de pickup/dropoff mais um office code, coordenadas ou place UUID. A resposta traz uma entrada por veículo reservável em todas as marcas habilitadas.

bash

curl -X POST https://greenflow.live/api/v1/fleet/list \
  -H "Authorization: Bearer gfc_7s2wprmy_DWTZRBGBEV6La4dTOoFdMkEhWmWCsXdwc3zVMnqP" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup_location": "AACGH",
    "pickup_date": "2026-05-15", "pickup_time": "10:00",
    "dropoff_date": "2026-05-18", "dropoff_time": "10:00",
    "passenger_country_code": "BR", "passenger_age": 30,
    "brands": [11]
  }'

3. Reserve um carro

Chame POST /fleet/show com um veículo do passo anterior para cunhar um tokenc, depois POST em /bookings para confirmar. O voucher PDF vai automaticamente por email.

Autenticação

Passe sua API key como Authorization: Bearer gfc_<prefix>_<secret> ou equivalentemente X-API-Key: gfc_<prefix>_<secret>. As chaves têm forma gfc_a3b1c2d4_... — o prefix é indexável, o secret é guardado como sha256. Escopadas a um único tenant; acesso cross-tenant retorna 404 (nunca 403).

HTTP	Body	Causa
401	{"message": "API key missing"}	No Authorization / X-API-Key header.
401	{"message": "Invalid API key"}	Hash mismatch, revoked or expired.

Versionamento

Todos os endpoints vivem sob /api/v1/. Mudanças incompatíveis saem sob um novo prefixo (ex. /api/v2/); v1 fica congelada exceto por correções.

Códigos HTTP

Semântica REST padrão. Erros de validação retornam 422 no formato Laravel. Erros de autenticação retornam 401. Recursos ausentes ou de outro tenant retornam 404. Erros do GDS upstream aparecem como 422 com a mensagem do provedor em error.message.

Limites de taxa

Hoje não há rate limit explícito na camada da aplicação. Proxies upstream (Cloudflare, nginx) podem limitar rajadas. Integradores de alto volume devem coordenar com o time de produto.

Locales

Passe X-Locale = en | es | pt para traduzir os campos visíveis ao usuário no payload da frota. Também faz parte da chave de cache: um request em pt é cacheado separado de um em en.

bash

curl -X POST https://greenflow.live/api/v1/fleet/list \
  -H "Authorization: Bearer gfc_7s2wprmy_DWTZRBGBEV6La4dTOoFdMkEhWmWCsXdwc3zVMnqP" \
  -H "X-Locale: pt" \
  -H "Content-Type: application/json" \
  -d '{ "pickup_location": "AACGH", "pickup_date": "2026-05-15", "pickup_time": "10:00", "dropoff_date": "2026-05-18", "dropoff_time": "10:00", "passenger_country_code": "BR", "passenger_age": 30, "brands": [11] }'

Convenções

Somente JSON UTF-8. Datas ISO-8601. Códigos de país ISO-3166-1 alpha-2. Moedas ISO-4217. Identificadores UUID v4.

Acessórios

Endpoints menores que complementam o fluxo principal — typeahead, sondas de identidade, catálogo de marcas, troca de locale. Alguns são rotas reais hoje; outros são stubs documentados para endpoints ainda não expostos (cada página deixa claro qual é qual).

Lugares — /places, /places/autocomplete, /places/search
Países — reference data (no standalone endpoint yet)
Lojas — surfaced via /places/search and /fleet/list internally
Marcas — /tenancy/brands
Utilitários — /me, /ping, /sandbox/defaults, locale switching