API de Viagens

O serviço de Viagens oferece funcionalidades completas para buscar, consultar detalhes e gerenciar reservas de assentos em viagens de ônibus entre diferentes cidades.

Buscar Viagens

Encontre viagens disponíveis entre origem e destino com filtros avançados

Detalhes & Assentos

Consulte informações detalhadas e gerencie reservas de assentos

Endpoints Principais

🔍 Busca de Viagens

Endpoint

GET /partners/api/v5/trips

Parâmetros Essenciais

from / to: Slugs de origem e destino (obtidos via Places API)
departureDate: Data de partida no formato YYYY-MM-DD
returnDate: Data de retorno (opcional, para viagens ida e volta)

Filtros Opcionais

serviceClass: Classe do serviço (Convencional, Executivo, Leito, etc.)
travelCompanyName: Nome da empresa de viagem para filtrar resultados

📋 Detalhes da Viagem

Endpoint

GET /partners/api/v4/trips/{id}

Parâmetros

id: UUID único da viagem
clientId: ID do cliente solicitante
fields: Campos específicos para retornar na resposta (opcional)

Retorna: Informações completas incluindo mapa de assentos, preços e disponibilidade.

🗺️ Itinerário da Viagem

Endpoint

GET /partners/api/v4/trips/itinerary/{id}

Parâmetros

id: Hash base64 do itinerário

Retorna: Detalhes completos das paradas, conexões e trajeto da viagem.

💺 Gerenciamento de Assentos

Bloquear Assentos

POST /partners/api/v4/trips/{id}/seats

Desbloquear Assentos

DELETE /partners/api/v4/trips/{id}/seats

Bloqueio: Reserva temporária de assentos por tempo limitado
Desbloqueio: Libera assentos para disponibilização a outros usuários

Estrutura de Dados

Campo	Tipo	Descrição	Exemplo
`type`	string	Tipo da viagem: `direct`, `connection`, `one_stop`	`connection`
`price`	number	Preço da passagem	`239.90`
`discountedPrice`	number	Preço com desconto aplicado	`229.90`
`duration`	object	Duração total da viagem	`4h 30m`
`availableSeats`	number	Quantidade de assentos disponíveis	`5`
`departure` / `arrival`	object	Horários de partida e chegada	`16:20:00`
`travelCompany`	object	Informações da empresa de transporte	`Viação ABC`
`serviceClass`	object	Classe do serviço oferecido	`Executivo`

Tipos de Viagem

🚌 Direta (Direct)

Viagem sem paradas intermediárias, direto entre origem e destino. Mais rápida, sem troca de ônibus e maior conforto.

🔄 Conexão (Connection)

Viagem com uma ou mais conexões e possível troca de ônibus. Duração maior, pode ter troca de veículo, geralmente mais econômica.

🛑 Uma Parada (One Stop)

Viagem com uma única parada técnica, sem troca de ônibus. Velocidade intermediária, mesmo veículo, apenas parada técnica.

Fluxo de Integração

🏙️ Buscar Localidades: Use a Places API para obter slugs de origem e destino
🔍 Pesquisar Viagens: Execute GET /v5/trips com os parâmetros de busca
📋 Selecionar Viagem: Escolha uma viagem e obtenha seu UUID
ℹ️ Consultar Detalhes: Use GET /v4/trips/{uuid} para informações completas
🗺️ Ver Itinerário: Consulte GET /v4/trips/itinerary/{hash} se necessário
💺 Bloquear Assentos: Execute POST /v4/trips/{id}/seats para reserva temporária
✅ Finalizar Compra: Processe o pagamento através do sistema externo

Regras Importantes

⚠️ Restrições de Busca

Slugs obrigatórios: Sempre utilize slugs válidos obtidos da Places API
Antecedência mínima: Geralmente 24 horas antes da partida
Limite de resultados: API possui paginação automática
Filtros disponíveis: Classe, empresa, horário e gratuidades

💺 Gestão de Assentos

Tempo de bloqueio: Assentos ficam reservados temporariamente
Dados do passageiro: Opcionais no bloqueio, obrigatórios na reserva final
Descontos especiais: Aplicáveis para idosos, estudantes e outras categorias
Liberação automática: Sistema desbloqueeia assentos após tempo limite

💰 Preços e Pagamento

Preços dinâmicos: Variam conforme demanda, data e disponibilidade
Descontos automáticos: Sistema aplica descontos elegíveis automaticamente
Parcelamento: Disponível conforme política de cada empresa
Moeda: Todos os valores em Real Brasileiro (BRL)

Principais Benefícios

🎯 Busca Inteligente

Filtros avançados por classe de serviço, empresa e horários preferenciais

📊 Dados Completos

Informações detalhadas de viagem, itinerário e disponibilidade em tempo real

💺 Gestão Flexível

Sistema completo de bloqueio e liberação de assentos com controle de tempo