Integracao API de Parceiros

A API de Parceiros permite que sistemas externos se integrem com o Levy Fleets, habilitando acesso programatico a veiculos, viagens, clientes, zonas e dados de precos. Use webhooks para receber notificacoes em tempo real de eventos da frota.

Visao Geral

A API de Parceiros fornece endpoints RESTful para gerenciar sua frota programaticamente. Todas as requisicoes sao autenticadas usando chaves de API e limitadas por taxa baseada na sua configuracao.

Recursos Principais

• API RESTful - Metodos HTTP padrao e respostas JSON
• Autenticacao por Chave de API - Acesso seguro com permissoes escopadas
• Limitacao de Taxa - Limites configuraveis por minuto, hora e dia
• Webhooks - Notificacoes de eventos em tempo real com logica de retry
• Registro de Requisicoes - Trilha de auditoria completa de uso da API

URL Base

https://app.levyelectric.com/api/partner/v1

Primeiros Passos

Criando uma Chave de API

Formato da Chave de API

Chaves de API usam o formato: lf_pk_<32 caracteres aleatorios>

Exemplo: lf_pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Apenas os primeiros 12 caracteres (prefixo) sao armazenados para exibicao. A chave completa e hasheada usando SHA-256 para armazenamento seguro.

Autenticacao

Cabecalhos de Requisicao

Todas as requisicoes de API devem incluir o cabecalho da chave de API:

curl -X GET "https://app.levyelectric.com/api/partner/v1/vehicles" \
  -H "X-Partner-Api-Key: lf_pk_sua_chave_api_aqui" \
  -H "Content-Type: application/json"

Cabecalhos Opcionais

Erros de Autenticacao

Permissoes

Chaves de API recebem permissoes especificas que controlam quais operacoes podem realizar.

Permissoes Disponiveis

Permissoes Padrao

Novas chaves de API recebem acesso somente leitura por padrao:

• vehicles:read
• rides:read
• customers:read
• zones:read
• pricing:read

Escopos de Chave

Limitacao de Taxa

Requisicoes de API sao limitadas por taxa para prevenir abuso e garantir uso justo.

Limites Padrao

Cabecalhos de Resposta

Status de limite de taxa e incluido nos cabecalhos de resposta:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 2025-01-15T10:31:00Z

Limite de Taxa Excedido

Quando os limites sao excedidos, voce recebera uma resposta 429:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de taxa excedido para janela de minuto. Tentar novamente apos 2025-01-15T10:31:00Z",
    "details": {
      "limit": 60,
      "window": "minute",
      "retry_after": 45
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:15Z"
  }
}

Endpoints da API

Veiculos

Listar Veiculos

GET /api/partner/v1/vehicles
GET /api/partner/v1/vehicles?status=available&limit=50

Obter Veiculo

GET /api/partner/v1/vehicles/{id}

Atualizar Status do Veiculo

PATCH /api/partner/v1/vehicles/{id}
{
  "status": "maintenance"
}

Veiculos Proximos

GET /api/partner/v1/vehicles/nearby?lat=40.7128&lng=-74.0060&radius=500

Viagens

Listar Viagens

GET /api/partner/v1/rides
GET /api/partner/v1/rides?status=active

Obter Viagem

GET /api/partner/v1/rides/{id}

Iniciar Viagem (requer rides:write)

POST /api/partner/v1/rides
{
  "customer_id": "uuid",
  "vehicle_id": "uuid"
}

Pausar Viagem

POST /api/partner/v1/rides/{id}/pause

Retomar Viagem

POST /api/partner/v1/rides/{id}/resume

Encerrar Viagem

POST /api/partner/v1/rides/{id}/end
{
  "end_latitude": 40.7128,
  "end_longitude": -74.0060
}

Clientes

Listar Clientes

GET /api/partner/v1/customers
GET /api/partner/v1/customers?email=usuario@exemplo.com

Obter Cliente

GET /api/partner/v1/customers/{id}

Obter Saldo da Carteira

GET /api/partner/v1/customers/{id}/wallet

Creditar Carteira (requer wallet:write)

POST /api/partner/v1/customers/{id}/wallet
{
  "action": "credit",
  "amount_cents": 1000,
  "description": "Credito promocional"
}

Zonas

Listar Zonas

GET /api/partner/v1/zones
GET /api/partner/v1/zones?type=parking

Precos

Obter Precos

GET /api/partner/v1/pricing

Formato de Resposta

Resposta de Sucesso

{
  "data": {
    "id": "uuid",
    "vehicle_number": "V001",
    "status": "available"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Resposta de Lista

{
  "data": [
    { "id": "uuid-1", "vehicle_number": "V001" },
    { "id": "uuid-2", "vehicle_number": "V002" }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 125,
    "has_next": true,
    "has_prev": false
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Resposta de Erro

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Veiculo nao encontrado",
    "details": {
      "vehicle_id": "uuid"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Webhooks

Webhooks enviam requisicoes HTTP POST em tempo real para seu servidor quando eventos ocorrem.

Configurando Webhooks

Eventos de Webhook

Payload de Webhook

{
  "event": "ride.ended",
  "event_id": "evt_abc123def456",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "ride_id": "uuid",
    "customer_id": "uuid",
    "customer_number": 12345,
    "vehicle_id": "uuid",
    "vehicle_number": "V001",
    "start_time": "2025-01-15T10:00:00Z",
    "end_time": "2025-01-15T10:30:00Z",
    "duration_minutes": 30,
    "distance_km": 5.2,
    "pricing": {
      "total_cents": 850,
      "unlock_cents": 100,
      "time_cents": 750,
      "distance_cents": 0,
      "discount_cents": 0
    },
    "payment_status": "paid",
    "subaccount_id": "uuid"
  }
}

Assinatura de Webhook

Webhooks sao assinados usando HMAC-SHA256 para verificacao de seguranca.

Cabecalho de Assinatura:

X-Levy-Signature: t=1705312200,v1=abc123...

Verificacao (exemplo Node.js):

const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const parts = signature.split(',')
  const timestamp = parts.find(p => p.startsWith('t=')).substring(2)
  const expectedSig = parts.find(p => p.startsWith('v1=')).substring(3)

  // Verificar se timestamp e recente (dentro de 5 minutos)
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp)
  if (age > 300) return false

  // Calcular assinatura
  const signedPayload = `${timestamp}.${JSON.stringify(payload)}`
  const computedSig = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  return computedSig === expectedSig
}

Logica de Retry

Entregas de webhook com falha sao automaticamente reenviadas:

Apos 5 tentativas com falha, a entrega e marcada como falhou.

Gerenciamento de Chaves de API

Regenerando Chaves

Se uma chave for comprometida:

1. Va para Configuracoes → Integracoes
2. Encontre a chave de API
3. Clique em Regenerar
4. Atualize seus sistemas com a nova chave
5. A chave antiga e imediatamente invalidada

Desabilitando Chaves

Desabilite temporariamente uma chave sem excluir:

1. Encontre a chave de API
2. Desative Ativo
3. Todas as requisicoes com esta chave retornarao 401

Visualizando Uso

Monitore a atividade da chave de API:

• Ultimo Uso - Quando a chave foi usada pela ultima vez
• Requisicoes Hoje - Contagem de requisicoes de hoje
• Requisicoes Esta Semana/Mes - Uso historico

Melhores Praticas

Seguranca

1. Armazene chaves com seguranca - Use variaveis de ambiente, nao codigo
2. Use HTTPS - Todas as chamadas de API devem usar HTTPS
3. Verifique webhooks - Sempre valide assinaturas de webhook
4. Rotacione chaves - Regenere chaves periodicamente
5. Permissoes minimas - Conceda apenas permissoes necessarias

Desempenho

1. Use paginacao - Solicite paginas menores para listas grandes
2. Cache respostas - Armazene em cache dados somente leitura apropriadamente
3. Trate limites de taxa - Implemente backoff exponencial
4. Use webhooks - Prefira webhooks a polling

Tratamento de Erros

1. Verifique codigos de resposta - Trate erros 4xx e 5xx
2. Use IDs de requisicao - Registre request_id para depuracao
3. Reenvia erros transitorios - Reenvia erros 5xx com backoff
4. Monitore falhas - Alerte sobre falhas repetidas de webhook

Solucao de Problemas

Falhas de Autenticacao

Problemas de Webhook

Problemas de Limite de Taxa

Exemplos de SDK

Node.js

const axios = require('axios')

const api = axios.create({
  baseURL: 'https://app.levyelectric.com/api/partner/v1',
  headers: {
    'X-Partner-Api-Key': process.env.LEVY_API_KEY,
    'Content-Type': 'application/json'
  }
})

// Listar veiculos disponiveis
const { data } = await api.get('/vehicles', {
  params: { status: 'available' }
})

console.log(data.data) // Array de veiculos

Python

import requests
import os

API_KEY = os.environ['LEVY_API_KEY']
BASE_URL = 'https://app.levyelectric.com/api/partner/v1'

headers = {
    'X-Partner-Api-Key': API_KEY,
    'Content-Type': 'application/json'
}

# Obter um veiculo especifico
response = requests.get(
    f'{BASE_URL}/vehicles/uuid-aqui',
    headers=headers
)

vehicle = response.json()['data']
print(f"Veiculo {vehicle['vehicle_number']}: {vehicle['status']}")