> For the complete documentation index, see [llms.txt](https://docs.yoplanning.support/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yoplanning.support/pt/developpeur/api-octo-yoplanning-workflow-de-vente-standard.md). # API OCTO Yoplanning - Fluxo de Trabalho de Vendas Padrão ### Apresentação A Yoplanning oferece uma implementação da API OCTO para permitir a revenda de atividades entre equipes. Esta documentação apresenta o fluxo de trabalho padrão para vendas, cancelamentos e notificações via webhook. Esta implementação está em conformidade com os padrões da OCTO Travel. [Certificação oficial da OCTO](https://certify.octo.travel/verify/d1a59704-1654-4385-874c-02a5b5939bad) Documentação oficial da OCTO: *** ### Pré-requisitos Antes de usar a API OCTO Yoplanning, as seguintes configurações devem estar em vigor no Yoplanning: * Uma equipe de revenda (`teamId`) * Uma equipe de fornecedores (`providerId`) * Um token de API do tipo `run user` criado na equipe de revenda. * O prestador de serviços deve: * tendo adicionado o revendedor à sua equipe * tendo configurado os produtos disponíveis para revenda. *** ### URL base ``` https://yoplanning.pro/api/octo/teams//providers// ``` #### Variáveis | Variável | Descrição | | -------------- | ---------------------------- | | `` | ID da equipe de revendedores | | `` | ID da equipe do fornecedor | *** ### Autenticação A autenticação funciona como a API v3.1 do Yoplanning. Você pode usar: #### Token de autorização do cabeçalho ```http Authorization: Token XXXX ``` #### Cabeçalho de autorização de portador ```http Authorization: Bearer XXXX ``` *** ### Funcionalidades utilizadas Todas as solicitações utilizam as seguintes funcionalidades: ```http Octo-Capabilities: pricing,content ``` Essas funcionalidades permitem que você recupere: * informações sobre preços * conteúdo de marketing de produto * dados descritivos sobre disponibilidade *** ### Fluxo de trabalho padrão suportado O fluxo de trabalho padrão suportado pelo Yoplanning é o seguinte: ``` /products ↓ /availability/calendar (optionnel) ↓ /availability ↓ /booking ↓ /confirm ``` Fluxo de trabalho de cancelamento: ``` /cancel ``` Fluxo de trabalho de notificação: ``` /notifications/subscriptions ``` *** ### 1. Recupere os produtos Ponto final: ```http GET /products ``` Este endpoint permite que você recupere os produtos disponíveis para venda. #### Usar O revendedor utiliza esta rota para: * Exibir o catálogo do fornecedor * recuperar as opções * recuperar as unidades tarifárias * exibir conteúdo de marketing *** ### 2. Exibir um calendário de disponibilidade (opcional) Ponto final: ```http POST /availability/calendar ``` Esta etapa é opcional. Permite exibir: * datas disponíveis * preços “a partir de” * um calendário de reservas #### Melhores práticas Utilize esta rota para: * Exibir um calendário mensal * Disponibilidade de pré-carga * melhorar o desempenho do front-end *** ### 3. Verificar disponibilidade Ponto final: ```http POST /availability ``` Esta etapa é obrigatória. Permite recuperar: * os horários disponíveis * os horários * as capacidades * os preços exatos * o `availabilityId` O `availabilityId` é necessário para criar uma reserva. #### Recomendação importante A melhor forma é transmitir as `unidades` (número de participantes). Isso permite: * para obter o melhor preço * para recuperar a boa disponibilidade * para calcular corretamente as capacidades *** ### 4. Reserve lugares Ponto final: ```http POST /booking ``` Esta rota cria uma reserva temporária. O pedido foi criado com o seguinte status: ``` ON_HOLD ``` O status `ON_HOLD` significa: * Os assentos estão bloqueados. * A reserva ainda não foi confirmada. * O pedido expira automaticamente após 30 minutos se não for confirmado. #### Importante Nesta fase: * A reserva já existe. * Os espaços são seguros. * O pagamento pode ser finalizado por parte do revendedor. *** ### 5. Confirme o pedido Ponto final: ```http POST /confirm ``` Esta etapa finaliza a reserva. Após a confirmação: * a ordem torna-se definitiva. * Os bilhetes podem ser gerados. * A reserva foi concluída. #### Importante A confirmação é simples: * Isso apenas confirma o pedido existente. * Não é possível modificar o conteúdo do pedido nesta fase. *** ### 6. Cancelar um pedido Ponto final: ```http POST /cancel ``` Esta opção permite cancelar uma reserva. #### Importante Certifique-se de respeitar a política de cancelamento do fornecedor caso a reserva já esteja confirmada. De acordo com as regras do fornecedor: * Podem ser aplicadas taxas. * O cancelamento pode ser proibido. * Podem existir condições específicas. O revendedor deve verificar as regras de cancelamento antes de oferecer a opção ao cliente final. *** ### Prorrogar a reserva (opcional) Ponto final: ```http POST /extend ``` Esta rota permite prolongar a duração do estado `ON_HOLD`. Exemplo : * Pagamento pendente * Validação do cliente em andamento * É necessário mais tempo. A reserva deve estar válida no momento da chamada. *** ### Notificações de webhook Ponto final: ```http POST /notifications/subscriptions ``` Este método permite que você se registre para receber webhooks do OCTO. Os webhooks permitem que você receba notificações sobre: * os produtos * disponibilidade * reservas #### Funcionamento Os dados completos do objeto não são enviados diretamente para o webhook. O webhook contém as informações necessárias para acessar os endpoints relevantes e recuperar as atualizações. #### Melhores práticas Após receber um webhook: * lembre-se do ponto final em questão * Recarregar os dados mais recentes * Não utilize o webhook como sua única fonte de dados. *** ### Gerenciar o vencimento de reservas Uma reserva não confirmada é automaticamente excluída após o vencimento. Por padrão: ``` 30 minutes ``` O revendedor deve, portanto: * Confirme os pedidos rapidamente * Gerencie os prazos de pagamento corretamente. * use `/extend` se necessário *** ### Melhores práticas #### Use sempre `/availability` Mesmo se você usar `/availability/calendar`, ainda precisará chamar: ```http /availability ``` antes de `/booking`. Esta rota fornece o `availabilityId` necessário para a reserva. #### Envie as unidades tarifárias. Transmita sempre as unidades (`unidades` / participantes). Isso melhora: * cálculo de tarifas * disponibilidade * as regras de capacidade #### Gerenciar as expirações na parte frontal Exibir um cronômetro visível quando o comando estiver em `ON_HOLD`. #### Recarregar dados após o webhook Os webhooks são usados ​​exclusivamente para notificações. Recarregue sempre os dados através dos endpoints da API relevantes. *** ### Documentação oficial do OCTO Informações completas sobre os endpoints e a arquitetura OCTO estão disponíveis aqui: --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.yoplanning.support/pt/developpeur/api-octo-yoplanning-workflow-de-vente-standard.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.