Referência da API

Referência completa de todos os endpoints da API Reservei. A API é RESTful, utiliza JSON para requests/responses e autenticação via Bearer Token.

Base URL

https://app.reservei.co/api/v1

Autenticação

Todas as requisições requerem autenticação via header Authorization:

Authorization: Bearer mbx_live_sua_chave_aqui
Content-Type: application/json

Endpoints Disponíveis

✈️ Voos

Buscar ofertas de voos em tempo real com preços calculados automaticamente.

POST /api/v1/flights/search - Buscar ofertas

📋 Reservas

Criar, listar, confirmar e gerenciar reservas de voos.

GET /api/v1/bookings - Listar reservas
GET /api/v1/bookings/:id - Detalhes da reserva
POST /api/v1/bookings - Criar reserva
PUT /api/v1/bookings/:id/confirm - Confirmar pagamento
DELETE /api/v1/bookings/:id - Cancelar

💰 Wallet

Consultar saldo, transações e recarregar sua carteira virtual.

GET /api/v1/wallet/balance - Consultar saldo
GET /api/v1/wallet/transactions - Listar transações
POST /api/v1/wallet/recharge - Solicitar recarga
GET /api/v1/wallet/recharge/:id - Status da recarga

🔔 Webhooks

Configurar notificações em tempo real para eventos.

GET /api/v1/webhooks - Listar webhooks
POST /api/v1/webhooks - Criar webhook
PUT /api/v1/webhooks/:id - Atualizar webhook
DELETE /api/v1/webhooks/:id - Remover webhook

Formato das Respostas

Sucesso

{
  "success": true,
  "data": {
    // Dados da resposta
  }
}

Sucesso com Paginação

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Erro

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Campo 'origin' é obrigatório",
    "details": {
      "field": "origin",
      "type": "required"
    }
  }
}

Códigos HTTP

Código	Descrição	Quando Usar
`200`	OK	Requisição bem-sucedida
`201`	Created	Recurso criado com sucesso
`400`	Bad Request	Parâmetros inválidos
`401`	Unauthorized	Falha na autenticação
`403`	Forbidden	Sem permissão para o recurso
`404`	Not Found	Recurso não encontrado
`409`	Conflict	Conflito de estado (ex: já cancelado)
`422`	Unprocessable Entity	Validação de negócio falhou
`429`	Too Many Requests	Rate limit excedido
`500`	Internal Server Error	Erro interno

Códigos de Erro

Código	Descrição
`UNAUTHORIZED`	Autenticação falhou
`FORBIDDEN`	Sem permissão
`NOT_FOUND`	Recurso não encontrado
`VALIDATION_ERROR`	Erro de validação
`OFFER_EXPIRED`	Oferta expirou
`INSUFFICIENT_BALANCE`	Saldo insuficiente
`BOOKING_ALREADY_CANCELLED`	Reserva já cancelada
`RATE_LIMIT_EXCEEDED`	Limite de requisições excedido

Rate Limits

Endpoint	Limite	Janela
`/flights/search`	60 requisições	1 minuto
`/bookings` (criar)	30 requisições	1 minuto
Outros endpoints	120 requisições	1 minuto

Headers de Rate Limit

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705330800

Versionamento

A API usa versionamento na URL (/api/v1). Mudanças breaking serão lançadas em novas versões, garantindo compatibilidade com integrações existentes.

Paginação

Endpoints que retornam listas suportam paginação via query parameters:

Parâmetro	Padrão	Máximo	Descrição
`page`	1	-	Número da página
`limit`	20	100	Itens por página

GET /api/v1/bookings?page=2&limit=50

Filtros

Muitos endpoints suportam filtros via query parameters:

# Filtrar por status
GET /api/v1/bookings?status=confirmed

# Filtrar por data
GET /api/v1/wallet/transactions?start_date=2025-01-01&end_date=2025-01-31

# Combinar filtros
GET /api/v1/bookings?status=ticketed&created_after=2025-01-01

Ordenação

# Ordenar por data (mais recente primeiro)
GET /api/v1/bookings?order_by=created_at&order_dir=desc

Idempotência

Para operações de criação, você pode enviar um header Idempotency-Key para garantir que requisições duplicadas não criem recursos duplicados:

POST /api/v1/bookings
Idempotency-Key: unique-key-123

Requisições com a mesma Idempotency-Key nos últimos 24 horas retornarão a mesma resposta da primeira requisição.

Suporte a CORS

A API suporta CORS para requisições de browsers em domínios autorizados. Para adicionar seu domínio, entre em contato com o suporte.

SDKs Oficiais

Estamos desenvolvendo SDKs oficiais para facilitar a integração:

Linguagem	Status	Link
JavaScript/TypeScript	Em breve	-
Python	Em breve	-
PHP	Em breve	-

Referência da API

Referência da API

Base URL

Autenticação

Endpoints Disponíveis

✈️ Voos

📋 Reservas

💰 Wallet

🔔 Webhooks

Formato das Respostas

Sucesso

Sucesso com Paginação

Erro

Códigos HTTP

Códigos de Erro

Rate Limits

Headers de Rate Limit

Versionamento

Paginação

Filtros

Ordenação

Idempotência

Suporte a CORS

SDKs Oficiais

Próximos Passos

On this page