API v1

Integre o motor de rotas VAIGO ao seu aplicativo.

O parceiro conversa apenas com https://api.vaigo.online. O Gateway autentica, protege e encaminha a solicitação ao servidor central VAIGO, que escolhe um Route Node disponível e devolve uma resposta estável.

Começo rápido

Use a API key gerada pelo painel. Em produção, recomendamos que a chamada seja feita pelo backend do aplicativo parceiro; não coloque uma chave secreta permanente dentro de APK, IPA ou JavaScript público.

curl -X POST https://api.vaigo.online/v1/routes \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": {"lat": -23.5614, "lon": -46.6559},
    "destination": {"lat": -23.5505, "lon": -46.6333},
    "profile": "driving",
    "mode": "fastest",
    "professional_driver": true,
    "preferences": {"avoid_tolls": false, "avoid_ferries": true}
  }'

Autenticação

Envie Authorization: Bearer <API_KEY>. A chave completa aparece somente no momento da criação. O VAIGO guarda apenas o hash da credencial.

Não exponha a chave no app cliente. Se o aplicativo não tiver backend, crie um pequeno proxy próprio para assinar chamadas ao VAIGO.

Endpoint de rotas

POST/v1/routes

Perfis atuais: driving e motorcycle. Modos: fastest, safest, smart e quietest.

{
  "origin": {"lat": -23.5614, "lon": -46.6559},
  "destination": {"lat": -23.5505, "lon": -46.6333},
  "profile": "driving",
  "mode": "fastest",
  "depart_at": "now",
  "heading": 125,
  "speed_mps": 8.5,
  "reroute": false,
  "adaptive": true,
  "professional_driver": true,
  "local_hour": 18,
  "safety_bias": 68,
  "traffic_bias": 62,
  "preferences": {
    "avoid_ferries": true,
    "avoid_tolls": false,
    "avoid_unpaved": true
  }
}

Resposta

{
  "request_id": "req_...",
  "api_version": "v1",
  "mode": "fastest",
  "profile": "driving",
  "selected_id": 0,
  "routes": [{
    "id": 0,
    "distance_m": 5120.4,
    "duration_s": 742.0,
    "duration_min": 12.4,
    "geometry": {"type": "LineString", "coordinates": [[-46.65,-23.56]]},
    "steps": [],
    "badges": ["fastest"],
    "micro_route": true
  }],
  "meta": {"provider": "vaigo", "route_count": 1, "degraded": false}
}

Recalcular durante a corrida

Quando o motorista sair da rota, envie uma nova chamada com a posição atual como origin, reroute:true, além de heading e speed_mps quando disponíveis. Mantenha um intervalo razoável e evite recalcular a cada atualização de GPS.

Status

GET/v1/status

Use para monitoramento da sua integração. Este endpoint exige o escopo status:read.

Geocoding

O geocoding público está desligado neste ambiente. Ative somente após validar as licenças/contratos do provedor utilizado por baixo.

Headers úteis

X-Request-ID: identificador da chamada, também aceito na requisição.
X-RateLimit-Limit: teto técnico por minuto.
X-RateLimit-Remaining: chamadas restantes na janela atual.
X-RateLimit-Reset: timestamp Unix de reinício da janela.

Códigos de erro

HTTP	Código	Significado
400	INVALID_JSON	JSON inválido.
401	AUTH_MISSING / AUTH_INVALID	Credencial ausente ou inválida.
401	KEY_REVOKED / KEY_EXPIRED	Chave revogada ou expirada.
403	APP_SUSPENDED / SCOPE_DENIED / IP_NOT_ALLOWED	Aplicação, permissão ou origem bloqueada.
415	CONTENT_TYPE_REQUIRED	Use application/json.
422	VALIDATION_ERROR	Campos ou coordenadas inválidos.
429	RATE_LIMITED	Proteção técnica temporária.
503	CENTRAL_UNAVAILABLE / ROUTING_UNAVAILABLE	Serviço temporariamente indisponível.
504	UPSTREAM_TIMEOUT	Tempo do cálculo excedido.

Exemplo Node.js

const response = await fetch("https://api.vaigo.online/v1/routes", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.VAIGO_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    origin: {lat: -23.5614, lon: -46.6559},
    destination: {lat: -23.5505, lon: -46.6333},
    profile: "driving",
    mode: "fastest",
    professional_driver: true
  })
});
const route = await response.json();

Exemplo Python

import os, requests

r = requests.post(
    "https://api.vaigo.online/v1/routes",
    headers={"Authorization": f"Bearer {os.environ['VAIGO_API_KEY']}"},
    json={
        "origin": {"lat": -23.5614, "lon": -46.6559},
        "destination": {"lat": -23.5505, "lon": -46.6333},
        "profile": "driving",
        "mode": "fastest"
    },
    timeout=40,
)
r.raise_for_status()
print(r.json())

Contrato completo

O contrato OpenAPI pode ser importado no Postman, Insomnia, Swagger Editor ou geradores de SDK: openapi.yaml.