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:
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


