Visão geral da API de Atividades Rápidas
Capacite os viajantes a reservar atividades e experiências com a API Rapid Activities.
Prévia de acesso antecipado
Esta documentação faz parte de uma iniciativa de acesso antecipado exclusiva para parceiros selecionados. Os programas piloto serão lançados no segundo trimestre de 2026, com disponibilidade geral em 2027.
Se você tiver interesse em se tornar um parceiro piloto ou beta, entre em contato com seu gerente de contas.
A API Rapid Activities foi projetada para ajudar você a apresentar atividades aos viajantes por meio de um fluxo de compra e reserva fácil de integrar. Isso proporciona aos viajantes uma experiência mais completa, ao mesmo tempo que permite desbloquear novas fontes de receita.
Conceitos-chave
- Atividade: Um evento que pode ser reservado (o que você mostra e vende).
- Grupo de atividades: Um conjunto de atividades semelhantes.
- Experiência: Um invólucro conceitual/de marketing que pode conter várias atividades.
- Ingressos: Tipos de ingresso para uma atividade (adulto/criança/bebê, etc.).
- Itinerário: Uma reserva (reserva de atividade) com uma atividade e um ou mais ingressos.
- Categorias: High-level agrupamentos que classificam experiências e atividades em temas (por exemplo, passeios pela cidade, museus ou atividades ao ar livre).
- Atributos: Indicadores descritivos que capturam características específicas de uma experiência ou atividade (por exemplo, acessível para cadeirantes, adequado para famílias, visita guiada ou sem fila).
Fluxo de integração de ponta a ponta
O agendamento de atividades com esta API segue este fluxo geral.
Etapa 1: Descubra o estoque
Entenda o que você pode vender em um destino e crie um catálogo estruturado de atividades por destino, pronto para ser comercializado.
- Mapeie as regiões da API de Geografia para o estoque subjacente (experiências, atividades e grupos de atividades) usando os endpoints de mapeamento de região. Observação: a API de Atividades suportará apenas o parâmetro
region_IDnesta iteração. - Obtenha conteúdo detalhado das atividades (títulos, descrições, imagens, locais e categorias) em vários idiomas.
- Obtenha avaliações e comentários de hóspedes sobre as atividades para ajudar os viajantes a comparar opções e construir confiança na experiência.
- Preencha os resultados da pesquisa, as páginas de detalhes da atividade e os filtros (por exemplo, atividades para famílias ou passeios a pé).
Passo 2: Verifique a disponibilidade e os preços.
Saiba quando as atividades estão disponíveis e a que preço. Utilize datas/horários reserváveis, opções de ingressos e faixas de preço para otimizar a experiência de compra.
- Para atividades e datas específicas, solicite disponibilidade e preços por tipo de ingresso.
- Exibir calendários (datas disponíveis/indisponíveis), horários disponíveis e preços iniciais na experiência do comprador.
- Suportar múltiplas atividades em uma única chamada.
Etapa 3: Verificação de preço do Pre-booking
Confirme o preço final da reserva e obtenha uma lista dos campos obrigatórios antes de efetuar o pagamento. Receba uma oferta confirmada e um código de reserva, de acordo com o estoque e as políticas mais recentes.
- Valide uma seleção específica (atividade, data, hora e ingressos) em tempo real.
- Receba o preço final, impostos/taxas e disponibilidade (incluindo alterações de preço ou esgotamento do estoque).
- Obtenha detalhes sobre os campos obrigatórios da reserva (como dados do passageiro ou tipo pick-up) e um token seguro para a reserva.
Passo 4: Criar reserva
Transforme uma seleção confirmada em uma reserva. Receba um itinerário confirmado (reserva) que você poderá visualizar e gerenciar em seus próprios sistemas.
- Envie o token de reserva do fluxo de compras como um parâmetro de consulta, o
payment_tokenda API de Pagamentos no corpo da solicitação, juntamente com os detalhes do viajante (viajante principal e adicionais). - Inclua sua própria referência de afiliado para que você possa conciliar e pesquisar reservas posteriormente.
- Receba um ID de itinerário e links para recuperar os detalhes da reserva.
Etapa 5: Gerenciar reservas
Apoiar os fluxos de trabalho pós-reserva para clientes e agentes. Acesse um conjunto completo de ferramentas pós-reserva para visualizar, cancelar e fornecer vouchers para reservas existentes.
- Recupere os detalhes da reserva pelo ID do itinerário ou pela sua referência de afiliado.
- Cancele as reservas quando permitido e informe o cliente sobre a situação resultante.
- Recupere os comprovantes de compra para que os clientes os apresentem na atividade.
Testando respostas de erro
Para enviar uma solicitação de teste para um determinado método da API de Atividades Rápidas, inclua um cabeçalho HTTP adicional chamado testem sua solicitação de Compras ou Reservas e use o valor apropriado das tabelas abaixo. A não apresentação de um cabeçalho de teste ou o envio de um cabeçalho de teste inválido fará com que a solicitação seja processada em tempo real.
Nota: O uso de um cabeçalho de teste resultará em uma mensagem de resposta estática, portanto, as taxas e o conteúdo retornados podem não ser relevantes para as atividades que estão sendo testadas.
APIs de compras e conteúdo
| Valor do cabeçalho de teste | Código de HTTP e resposta | Status |
|---|---|---|
| padrão | 200 OK (resposta padrão de sucesso) | Success |
invalid_input | 400 solicitação inválida (entrada inválida) | Erro |
bad_link | 400 solicitação inválida (link inválido) | Erro |
internal_server_error | Erro 500 interno do servidor (erro desconhecido) | Erro |
service_unavailable | Serviço 503 não disponível | Erro |
API de reserva
| Valor do cabeçalho de teste | Código de HTTP e resposta | Status |
|---|---|---|
| padrão | 200 OK (resposta padrão de sucesso) | Success |
invalid_input | 400 solicitação inválida (entrada inválida) | Erro |
bad_link | 400 solicitação inválida (link inválido) | Erro |
price_mismatch | Conflito 409 (descompasso de preços) | Erro |
sold_out | Conflito 409 (esgotado) | Erro |
internal_server_error | Erro 500 interno do servidor (erro desconhecido) | Erro |
service_unavailable | Serviço 503 não disponível | Erro |
Resumo dos endpoints por caso de uso
| Caso de uso | Método e caminho | Parâmetros de consulta obrigatórios / comentários |
|---|---|---|
| Experiências regionais | GET /regions/{region_id}/experiences | language |
| Grupos de atividades regionais | GET /regions/{region_id}/activity-groups | language |
| Atividades regionais | GET /regions/{region_id}/activities | language |
| Conteúdo da experiência | GET /experiences/content | experience_id[], language |
| Conteúdo do grupo de atividades | GET /experiences/activity-groups/content | language, activity_group_id[] |
| Conteúdo da atividade | GET /experiences/activities/content | activity_id[], language |
| Horário de funcionamento da atividade | GET /experiences/activities/{activity_id}/operating-hours | start_date,end_date (≤ 90 dias),language |
| Categorias de experiência | GET /experiences/categories | language, pagination_size |
| Atributos de experiência | GET /experiences/attributes | language, pagination_size |
| Categorias de atividades | GET /experiences/activities/categories | language, pagination_size |
| Atributos da atividade | GET /experiences/activities/attributes | language, pagination_size |
| Avaliações dos hóspedes | GET /experiences/activities/{activity_id}/guest-reviews | limit, sort |
| Disponibilidade e preço | GET /experiences/activities/availability | activity_id[],start_date,end_date (≤14),currency,language |
| Disponibilidade no calendário | GET /experiences/activities/calendars/availability | activity_id[],start_date,end_date |
| Verificação de preço | GET /experiences/activities/{activity_id}/price-check | token (da chamada da API de Compras), tickets |
| Criar reserva | POST /itineraries/activity | Consulta: token (da chamada da API de Compras), Corpo: CreateItineraryRequest,affiliate_reference_id,payment_token,primary_traveler |
| Recuperar por ID do itinerário | GET /itineraries/{itinerary_id}/activity | — |
| Recuperar por referência de afiliado | GET /itineraries/activity | affiliate_reference_id |
| Cancelar reserva | DELETE /itineraries/{itinerary_id}/activity | 204(Reserva cancelada com sucesso)202 (estado desconhecido) |
| Recuperar voucher | GET /itineraries/{itinerary_id}/activity/voucher | Link para recuperar o voucher da atividade reservada |
Observação: Parâmetros que são seguidos por[] Indica que pode ter múltiplos valores em uma matriz comma-separated.
Detalhes da API
Explore as configurações do endpoint activity-related nesta página e, em seguida, use um software de teste como o Postman para entender como os exemplos e as configurações de esquema se comparam à saída real. Quando esta API passar da fase piloto, seus endpoints também serão incluídos em nosso API Explorer.