API de Voos

Autenticação

Como autenticar suas requisições na API de Voos

Autenticação

A API utiliza autenticação via Bearer Token. Todas as requisições devem incluir o header Authorization com sua chave de API.

Formato da API Key

As chaves de API seguem o padrão:

TipoPrefixoExemplo
Produçãombx_live_mbx_live_8f92k3d7a9b2c4e6f8g0h1i2j3...
Testembx_test_mbx_test_a1b2c3d4e5f6g7h8i9j0k1l2...

O tipo da chave é determinado automaticamente pelo prefixo. Use chaves mbx_test_ para desenvolvimento e mbx_live_ para produção.

Segurança

Suas chaves de API são secretas e dão acesso completo à sua conta. Nunca compartilhe ou exponha em código público, repositórios Git, ou aplicações front-end.

Obtendo suas Chaves

Gere uma nova chave

Clique em "Gerar Nova Chave". Você pode criar múltiplas chaves para diferentes ambientes (produção, staging, desenvolvimento).

Copie e armazene com segurança

A chave completa só é exibida uma vez. Copie e armazene em um local seguro como:

  • Variáveis de ambiente
  • Secrets manager (AWS, GCP, Azure)
  • HashiCorp Vault

Formato do Header

Inclua o header Authorization em todas as requisições:

Authorization: Bearer mbx_live_sua_chave_aqui
Content-Type: application/json

Exemplos de Autenticação

curl -X POST https://api.seudominio.com/api/v1/flights/search \
  -H "Authorization: Bearer mbx_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"type":"one_way","slices":[...]}'
// Usando fetch nativo
const apiKey = process.env.API_KEY;

const response = await fetch('https://api.seudominio.com/api/v1/flights/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'one_way',
    slices: [...]
  })
});

const data = await response.json();

// Criando um cliente reutilizável
class FlightAPIClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.seudominio.com/api/v1';
  }

  async request(endpoint, options = {}) {
    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'API Error');
    }
    
    return response.json();
  }
}

const client = new FlightAPIClient(process.env.API_KEY);
import os
import requests

api_key = os.environ.get('API_KEY')

# Requisição simples
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.seudominio.com/api/v1/flights/search',
    headers=headers,
    json={'type': 'one_way', 'slices': [...]}
)

data = response.json()

# Classe cliente reutilizável
class FlightAPIClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://api.seudominio.com/api/v1'
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        })
    
    def get(self, endpoint, params=None):
        response = self.session.get(f'{self.base_url}{endpoint}', params=params)
        response.raise_for_status()
        return response.json()
    
    def post(self, endpoint, data):
        response = self.session.post(f'{self.base_url}{endpoint}', json=data)
        response.raise_for_status()
        return response.json()

client = FlightAPIClient(os.environ['API_KEY'])
<?php

$apiKey = getenv('API_KEY');
$baseUrl = 'https://api.seudominio.com/api/v1';

// Usando cURL
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => $baseUrl . '/flights/search',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'type' => 'one_way',
        'slices' => [...]
    ])
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

// Classe cliente
class FlightAPIClient {
    private $apiKey;
    private $baseUrl = 'https://api.seudominio.com/api/v1';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    public function request($method, $endpoint, $data = null) {
        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => $this->baseUrl . $endpoint,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $this->apiKey,
                'Content-Type: application/json'
            ]
        ]);
        
        if ($data) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
}

$client = new FlightAPIClient(getenv('API_KEY'));

Gerenciamento de Chaves

Listando Chaves

No painel de API Keys você pode ver:

  • Prefixo da chave: Primeiros caracteres para identificação
  • Data de criação: Quando a chave foi gerada
  • Último uso: Última vez que a chave foi utilizada
  • Status: Ativa ou inativa
  • Uso: Quantidade de requisições realizadas

Revogando Chaves

Para revogar uma chave comprometida:

  1. Acesse Configurações → API Keys
  2. Localize a chave pelo prefixo
  3. Clique em "Revogar"
  4. Confirme a ação

A revogação é imediata e irreversível. Todas as requisições usando esta chave passarão a retornar 401 Unauthorized.

Rotação de Chaves

Recomendamos rotacionar suas chaves periodicamente (a cada 90 dias):

  1. Gere uma nova chave
  2. Atualize suas aplicações para usar a nova chave
  3. Monitore que tudo está funcionando
  4. Revogue a chave antiga

Vinculação com Time (Team)

Cada API key está vinculada a um time específico. Isso permite:

  • Controle de acesso: Cada time tem suas próprias chaves
  • Limites de quota: Requisições são contabilizadas por time
  • Billing separado: Custos são rastreados por time

Limites e Quotas

As quotas variam conforme o plano do seu time:

PlanoRequisições/MêsRate Limit
FREE5010 req/min
PRO5.00060 req/min
BUSINESS50.000120 req/min
ENTERPRISECustomizadoCustomizado

Quando atingir o limite mensal, suas requisições retornarão 429 Too Many Requests. Faça upgrade do plano para aumentar a quota.

Erros de Autenticação

CódigoErroDescriçãoSolução
401Missing or invalid Authorization headerHeader não presente ou malformadoVerifique se o header está no formato Bearer {key}
401Invalid API key formatChave não começa com mbx_live_ ou mbx_test_Verifique se está usando a chave correta
401Invalid API keyChave não encontrada no sistemaVerifique se a chave existe e não foi revogada
401API key is inactiveChave foi desativadaGere uma nova chave ou reative no painel
403ForbiddenSem permissão para o recursoVerifique as permissões do seu time
429Rate limit exceededMuitas requisiçõesAguarde e reduza a frequência de chamadas
429Quota exceededLimite mensal atingidoFaça upgrade do seu plano

Exemplo de Resposta de Erro

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Boas Práticas de Segurança

✅ Faça

  • Armazene chaves em variáveis de ambiente
  • Use secrets managers em produção (AWS Secrets Manager, etc.)
  • Rotacione chaves periodicamente (a cada 90 dias)
  • Use chaves de TESTE para desenvolvimento
  • Use chaves de PRODUÇÃO apenas em ambiente live
  • Monitore o uso das chaves
  • Implemente rate limiting no seu lado

❌ Não Faça

  • Commitar chaves em repositórios Git
  • Expor chaves em código front-end ou logs
  • Compartilhar chaves entre times ou desenvolvedores
  • Usar chaves de teste em produção
  • Ignorar alertas de uso suspeito
  • Deixar chaves antigas ativas sem uso

Testando a Autenticação

Verifique se sua chave está funcionando:

curl -X POST https://api.seudominio.com/api/ofertas/buscar \
  -H "Authorization: Bearer sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"internacional":true,"quantidade":5}'

Resposta de sucesso:

{
  "success": true,
  "data": [
    {
      "id": "123",
      "origem": {...},
      "destino": {...},
      "precoMinimo": 1299.00
    }
  ]
}

Resposta de erro:

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Suporte

Problemas com autenticação? Entre em contato:

On this page