For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Saltar para o conteúdo

API do Agente Yoplanning

A Yoplanning oferece uma API de Agente, que permite controlar a Yoplanning programaticamente — ou por meio de um assistente de IA — exatamente como se estivesse usando a interface web. A documentação técnica completa (todos os endpoints, todos os campos) está disponível no Swagger:

Referência completa da API do Yoplanning Agent

Este artigo não substitui esta referência técnica: ele explica o princípio geral, para que serve esta API e, sobretudo, as precauções a serem tomadas antes de conectá-la a qualquer coisa.

Metodologia

A API do Agente segue alguns princípios simples, mas é importante tê-los em mente antes de usá-la:

  • Esta é uma ponte direta para o código interno do Yoplanning — o mesmo código que a interface web utiliza. Escrever através da API tem exatamente o mesmo comportamento, validações e efeitos colaterais que uma ação manual dentro do Yoplanning. Não há lógica oculta: o que a interface permite, a API permite; o que a interface rejeita, a API também rejeita, com o mesmo erro.

  • Tudo tem escopo de equipe. Quase todos os endereços começam com o ID da sua equipe (/teams/{teamId}/…), e um token só dá acesso à equipe para a qual foi criado.

  • A regra de "ida e volta" para qualquer modificação é a seguinte: O objeto existente é recuperado, os campos desejados são modificados e, em seguida, o objeto inteiro é reenviado. Uma atualização não é uma correção parcial: qualquer campo ausente no envio é redefinido. Essa é uma fonte comum de erros se não for prevista.

  • Autenticação por token, específica para um usuário e uma equipe, transmitida em cada solicitação por meio do cabeçalho Authorization.

Para que serve?

A API do Agente permite criar, configurar, modificar ou excluir praticamente tudo o que o Yoplanning gerencia: clientes, produtos, sessões, pedidos, pagamentos, funcionários, códigos promocionais, motor de reservas, revendedores, etc. — com os mesmos direitos da pessoa a quem pertence o token.

Na prática, ele é usado para conectar o Yoplanning a um sistema externo (site, ferramenta interna, outro software empresarial) ou a um assistente de IA ao qual desejamos delegar tarefas de configuração ou gerenciamento em linguagem natural, em vez de fazer tudo manualmente na interface.

Riscos a serem considerados antes de conectar uma ferramenta a esta API

Esta não é uma API somente leitura: ela fornece acesso tão completo quanto uma conta de usuário do Yoplanning com login. Antes de conectá-la a uma ferramenta, script ou assistente de IA, tenha em mente os seguintes pontos:

**O token é um dado estritamente confidencial — assim como uma senha.** Qualquer pessoa ou programa que o possua pode agir em sua equipe exatamente como você pode: criar, modificar, excluir.

Nunca cole este código em um repositório de código (mesmo que privado), em uma mensagem não criptografada, em um e-mail, em uma captura de tela ou em uma ferramenta na qual você não confie totalmente. Se ele vazar, considere-o comprometido: gere um novo imediatamente a partir de suas preferências avançadas ou entre em contato com support@yoplanning.com se não tiver certeza de como proceder.

  • Os efeitos colaterais são reais. Um script pode enviar um e-mail de confirmação, registrar um pagamento, enviar um convite ou excluir dados de verdade — apenas uma vez, como a interface faria. Um script ou agente mal projetado pode, portanto, desencadear ações reais de seus clientes ou equipe, e não apenas modificar dados internamente.

  • Uma atualização substitui o objeto inteiro. Se a ferramenta que você conectar não reler o objeto antes de enviá-lo modificado, ela poderá excluir campos involuntariamente em vez de mantê-los como estão.

  • O token confere os direitos à pessoa que o criou. Se você conectar um assistente de IA a esta API, ele poderá fazer — e desfazer — tudo o que essa pessoa pode fazer nesta equipe. Defina claramente o que você deseja que ele faça, especialmente para qualquer ação irreversível (exclusão, envio de e-mails ou mensagens SMS, processamento de pagamentos) e priorize um token criado especificamente para essa finalidade em vez do seu token pessoal principal, se a ferramenta permitir.

Para ir mais longe

Para uma integração de IA mais leve e somente leitura, limitada pelas suas próprias permissões, consulte também o artigo Conectando-se ao Yoplanning via MCP. Para obter detalhes completos sobre os recursos e campos da API do Agente, a referência atual continua sendo o Swagger.

Última atualização