> 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-agent-yoplanning.md).

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

{% embed url="<https://yoplanning.pro/api/agent/v1/swagger/>" %}
Referência completa da API do Yoplanning Agent
{% endembed %}

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](https://docs.yoplanning.support/pt/developpeur/se-connecter-a-yoplanning-via-mcp.md). Para obter detalhes completos sobre os recursos e campos da API do Agente, a referência atual continua sendo o [Swagger](https://yoplanning.pro/api/agent/v1/swagger/).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.yoplanning.support/pt/developpeur/api-agent-yoplanning.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
