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

search🔍 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

info-circle📋 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.

route🗺️ 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.

chair💺 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`

Campo	Tipo	Descrição	Exemplo
`uuid`	string	Identificador único da viagem	`5f7b3b3b-4b3d-4b3d...`
`price`	object	Estrutura de preços (default, reference, original)	`48.75`
`map`	array	Mapa de assentos com disponibilidade	`[{label: "03", available: true}]`
`availableSeats`	number	Total de assentos disponíveis	`20`
`duration`	string	Duração total da viagem	`1h 30m`

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, troca de ônibus e, até mesmo, troca da viação. Duração maior, pode ter troca de veículo, geralmente mais econômica.

🛑 Uma Parada (One Stop)

Viagem com uma conexão e possível troca de ônibus. Velocidade intermediária, podendo ser feita pelo mesmo veículo, porém são considerados 2 trechos em sua composição.

Resumo prático

Connection: As viagens deste tipo são criadas por meio da ferramenta inteligente da ClickBus de viagens diretas ou com conexão. De forma dinâmica identifica se a rota pesquisada possui viagens com conexão oferecida por alguma viação, se não existir, montamos o roteiro de conexão e disponibilizamos a viagem.

One_Stop: As viagens deste tipo são viagens com conexão montadas pela viação. Onde a viação disponibiliza para a ClickBus o roteiro pronto, neste caso pode ou não haver troca de ônibus, mas sempre será composta por duas partes do trecho. Aqui a viação que é responsável em caso de atrasos durante os trechos.

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

exclamation-triangle⚠️ 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

chair💺 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

money-bill-wave💰 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

chart-bar

📊 Dados Completos

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

cogs

💺 Gestão Flexível

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