## Visão geral

A Conversa Labs publica uma **referência completa da API** no formato **OpenAPI 3.1**, gerada
automaticamente a partir das rotas reais do produto. Ela cobre **todos os módulos** — conversas,
contatos, CRM, catálogo, pagamentos, agenda, tarefas, follow-ups, vendas e gamificação, WhatsApp e
muito mais — e fica sempre em sincronia com a API a cada build.

Há duas formas de visualizar a mesma referência:

- **ReDoc (leitura)** — uma documentação navegável, organizada por grupos e tags, ideal para
  entender o contrato de cada endpoint: <https://app.conversalabs.com.br/swagger>
- **Swagger-UI (interativa)** — a mesma referência com o botão **"Try it out"** para fazer chamadas
  reais à API direto do navegador: <https://app.conversalabs.com.br/swagger/ui.html>
- **Definição OpenAPI (JSON)** — o arquivo bruto para importar no Postman, Insomnia ou gerar SDKs:
  <https://app.conversalabs.com.br/swagger/swagger.json>

## Pré-requisitos

- Um **token de acesso** válido (gerado no seu perfil/conta). Veja o artigo de API REST e tokens.
- Um navegador moderno. Para testar chamadas, prefira um token de um ambiente de testes.

## Passo a passo

1. Abra a referência em <https://app.conversalabs.com.br/swagger> (ReDoc) e navegue pelos grupos de
   módulos na barra lateral.
2. Localize o endpoint desejado (por método e caminho) e leia parâmetros, corpo e respostas.
3. Para **testar**, abra a referência interativa em
   <https://app.conversalabs.com.br/swagger/ui.html>.
4. Clique em **Authorize** e informe o seu token no cabeçalho **`api_access_token`**.
5. Escolha um endpoint, clique em **Try it out**, preencha os parâmetros e clique em **Execute**.
6. Confira a resposta (status, corpo) e use o exemplo de requisição (cURL) gerado na sua integração.

## Configurações & opções

- **Geração automática**: a referência é montada a partir da introspecção das rotas reais da
  aplicação, então novos endpoints aparecem automaticamente.
- **Autenticação**: todos os endpoints autenticados usam o cabeçalho **`api_access_token`**.
- **Disponibilidade**: em instalações self-hosted, a documentação é **habilitada pelo operador** por
  meio de uma variável de ambiente (`ENABLE_API_DOCS`). Na Conversa Labs hospedada, ela já fica
  disponível nos endereços acima.

## Casos de uso

- Descobrir rapidamente quais endpoints existem para um módulo (CRM, Pagamentos, Catálogo, etc.).
- Testar uma chamada com o seu token antes de escrevê-la no código.
- Importar a definição OpenAPI no Postman/Insomnia ou gerar um SDK cliente.

## Dicas, limites e boas práticas

- Trate o token como segredo — não o compartilhe nem o exponha no front-end.
- Para testes, use um token com escopo mínimo e, de preferência, de um ambiente de testes.
- Respeite os limites de taxa e trate erros 429/5xx com backoff.

## Solução de problemas

- **A página não abre (404)**: a documentação pode estar desabilitada no ambiente — o operador a
  habilita com `ENABLE_API_DOCS`.
- **401/403 ao testar**: o token é inválido ou não tem permissão; gere um novo e confira o escopo.
- **Endpoint não aparece**: ele pode exigir um módulo/recurso não habilitado na sua conta.

## Veja também

- [SDK, API REST e MCP de Dashboard Apps](/hc/ajuda/articles/api-developers-dashboard-apps-sdk-rest-mcp-pt-br)
- [API REST, tokens e webhooks](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-pt-br)
- [Visão geral de API & Desenvolvedores](/hc/ajuda/articles/api-developers-overview-pt-br)
- [Eventos por módulo](/hc/ajuda/articles/api-developers-eventos-por-modulo-pt-br)