API7c · IntegraçãoVoltar ao painel ↗

API7c — guia rápido de integração

A API busca voos na Passhub, aplica a comissão da sua chave e recebe Ordens de Emissão e Pagamento (OP). A emissão é manual, pela equipe. Ela não reserva assentos nem processa pagamentos.

1. Acesso

No painel, o administrador cria uma integração por cliente + sistema, define a comissão e entrega sua chave. O sistema cliente faz as chamadas pelo próprio servidor:

Content-Type: application/json
X-Api-Key: SUA_CHAVE_API7C

Base local: http://127.0.0.1:3000. Em produção, substitua pelo domínio HTTPS da API. Não use aqui as credenciais da Passhub e não exponha a chave no navegador do passageiro. Use timeout acima de 250 segundos: a busca costuma levar aproximadamente 40 segundos.

2. Buscar voos — POST /v1/searches

Somente ida

{
  "type": "flight",
  "iataFrom": "GRU",
  "iataTo": "CWB",
  "adults": 1,
  "dates": [{ "departure": "2026-12-08" }],
  "initialWaitSeconds": 40
}

Escolha uma oferta e guarde offers[n].quoteId.

Ida e volta

{
  "type": "flight",
  "iataFrom": "GRU",
  "iataTo": "CWB",
  "adults": 1,
  "dates": [{ "departure": "2026-12-08", "return": "2026-12-15" }],
  "initialWaitSeconds": 40
}

Cada ida traz returns[] com as opções de volta. Escolha a ida e a volta desejadas e guarde offers[n].returns[m].quoteId. A ida não recebe quoteId próprio nesse modo, para exigir a seleção explícita da volta.

O total da volta é o preço da viagem completa, ida + volta. Não some os dois valores e não divida por dois. Cada volta pode ter um preço diferente. A API mantém os dois identificadores da combinação escolhida, mesmo quando forem iguais.

Múltiplos destinos (multicidade)

{
  "type": "flight_multicity",
  "routes": [
    { "iataFrom": "GRU", "iataTo": "SSA", "date": "2026-12-08" },
    { "iataFrom": "SSA", "iataTo": "REC", "date": "2026-12-12" },
    { "iataFrom": "REC", "iataTo": "GRU", "date": "2026-12-16" }
  ],
  "adults": 1,
  "pageSize": 8,
  "maxOffersPerGroup": 3,
  "initialWaitSeconds": 40
}

Envie de 2 a 4 trechos, com datas em ordem cronológica. Não é obrigatório que o destino de um trecho seja a origem do próximo: viagens com trecho terrestre entre aeroportos são permitidas. Cada oferta representa a viagem inteira. Escolha offers[n].quoteId; legs[] detalha os trechos e conexões. A API encaminha offerIds inteiro na tarifação; o número de identificadores não precisa coincidir com o número de trechos.

Passageiros, paginação e filtros

adults: obrigatório, de 1 a 9.
children: opcional, quantidade de crianças com assento. Adultos + crianças: até 9.
babies: opcional, bebês de colo; no máximo um por adulto.
page: página a consultar, começando em 1.
pageSize: de 1 a 100 nesta API.
filters: aceita { "stopCounts": [0] } para voos diretos.
maxOffersPerGroup: apenas multicidade, de 1 a 50 nesta API. O fornecedor usa 3 por padrão. A paginação multicidade é por grupo do primeiro trecho.

Os limites de passageiros e tamanho de página acima são validações locais; a disponibilidade e os limites adicionais do fornecedor continuam sujeitos à Passhub.

Consulte supplierMeta.page, totalItems e totalPages para navegar. supplierMeta.global contém faixas de preço do fornecedor, antes da comissão. Se partial: true, repita a mesma busca após alguns segundos para obter mais resultados. Os três modos usam os mesmos endpoints seguintes.

3. Entender o preço

Exemplo abreviado de oferta/cotação (o identificador é ilustrativo):

{
  "quoteId": "11111111-1111-4111-8111-111111111111",
  "tripType": "ONE_WAY",
  "priceScope": "TOTAL_TRIP",
  "currency": "BRL",
  "originalFare": 350,
  "commissionPercentage": -3,
  "commissionAmount": -10.5,
  "farePrice": 339.5,
  "tax": 50,
  "totalPrice": 389.5
}

A comissão incide apenas na tarifa. A taxa é repassada integralmente. O valor cobre a oferta completa; não multiplique novamente por trechos. Use o preço total devolvido pelo fornecedor para a composição de passageiros consultada.

A comissão registrada na busca é mantida na confirmação e na OP. Mudar a configuração afeta novas buscas. Valores são calculados em centavos e ajustes de meio centavo arredondam para longe de zero. Campos adicionais do fornecedor podem aparecer: use um parser tolerante. Comparativos providers[] são omitidos para não misturar preços de fornecedor com preços de venda.

4. Confirmar a tarifa — POST /v1/offers/price

Envie o quoteId da oferta escolhida (em ida e volta, o da volta escolhida):

{ "quoteId": "11111111-1111-4111-8111-111111111111" }

A resposta contém um novo quoteId confirmado, preço atualizado, offerIds e repriced. Use o novo identificador na OP. Não mande preço ou percentual pelo cliente: a API recupera esses dados do servidor.

Se repriced: true, reapresente o preço atualizado ao passageiro antes de continuar. Identificadores são opacos; não os edite ou coloque na query string. Cotação vencida ou tarifa indisponível exige nova busca. A confirmação não garante o valor até a emissão manual.

5. Enviar a OP — POST /v1/webhooks/ops

{
  "externalId": "OP-SISTEMA-123",
  "quoteId": "22222222-2222-4222-8222-222222222222",
  "passengers": [{ "fullName": "Nome completo conforme documento" }],
  "paymentReference": "referencia-no-seu-sistema"
}

Use um externalId único por integração, mantenha-o nos reenvios e liste todos os passageiros da cotação, incluindo crianças e bebês. paymentReference é opcional e apenas referencial: não confirma pagamento. Não envie dados de cartão ou CVV. Os dados documentais necessários à emissão são obtidos pelo processo operacional da equipe.

Resposta inicial HTTP 201:

{ "id": "33333333-3333-4333-8333-333333333333", "status": "PENDING", "duplicate": false }

Repetir exatamente o mesmo pedido retorna HTTP 200, o mesmo id e duplicate: true. Reutilizar o externalId com conteúdo diferente retorna 409. Uma cotação não pode gerar duas OPs. OPs de cotações feitas fora desta API ainda não fazem parte do contrato.

A equipe usa o painel para assumir o atendimento, registrar a emissão com localizador/bilhetes ou cancelar o atendimento. Nenhuma dessas ações chama emissão, cobrança ou cancelamento na Passhub.

6. Exemplo com cURL

curl --max-time 260 http://127.0.0.1:3000/v1/searches \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: SUA_CHAVE_API7C' \
  -d '{"type":"flight","iataFrom":"GRU","iataTo":"CWB","adults":1,"dates":[{"departure":"2026-12-08","return":"2026-12-15"}]}'

Substitua chave, domínio e datas. Em seguida envie o quoteId da opção de volta para /v1/offers/price, e o novo quoteId para /v1/webhooks/ops.

7. Erros

{ "error": { "code": "FARE_UNAVAILABLE", "message": "Falha na integração Passhub", "retriable": false } }

401 INVALID_API_KEY: confira se a chave está correta e ativa.
404 NOT_FOUND: a cotação não existe ou pertence a outra integração.
409 IDEMPOTENCY_CONFLICT: o mesmo identificador de OP foi usado com dados diferentes.
409 QUOTE_ALREADY_USED: a cotação já está vinculada a uma OP.
410 OFFER_EXPIRED ou 422 FARE_UNAVAILABLE: faça uma nova busca.
422 VALIDATION_ERROR: corrija os campos em error.details.
422 PASSENGER_COUNT_MISMATCH: liste todos os passageiros da cotação.
429, 502, 503 ou 504: consulte retriable; se verdadeiro, aguarde e repita com intervalos crescentes. Não use loop imediato.

Trate pelo code, não pelo texto de message. Em reenvios de webhook, preserve externalId e conteúdo.

8. Acesso ao painel

Abra /panel, entre com e-mail e senha. Administradores cadastram integrações e usuários; operadores atendem OPs. Novos usuários trocam a senha temporária no primeiro acesso.

A sessão dura até 8 horas, em cookie HttpOnly. Para automação administrativa, faça POST /auth/login com { "email", "password" }, preserve o cookie e envie o csrfToken retornado no header X-CSRF-Token em alterações. GET /auth/session recupera a sessão e POST /auth/logout encerra. O antigo ADMIN_TOKEN foi substituído pelo login individual.