# O que a API v3 faz e como começar

A API pública do AtendeBot é uma API REST para conectar sua conta a sistemas externos: n8n, Make, um sistema próprio ou de um parceiro. A autenticação é por token Bearer, e cada token carrega os escopos que definem o que ele pode ler e escrever.

<p class="callout info">A <strong>v3</strong>, documentada aqui, é a versão atual da API. A <strong>v2</strong> (<code>/public/v2/docs</code>) continua no ar com o comportamento congelado; integrações novas devem nascer na v3, e quem vem da v2 encontra o de-para na seção <em>Migrando da v2</em> da referência.</p>

## Objetivo
Gerar um token com os escopos certos e fazer a primeira chamada à API pública v3.

## Pré-requisitos
- Perfil **Administrador**.
- Um token de API: veja [Gerar tokens de API para integrações](/books/canais-e-integracoes/page/gerar-tokens-de-api-para-integracoes).

## Tempo estimado
5 minutos.

## Caminho de acesso
**Ajustes → API e webhooks → Tokens** (para gerar o token) e a referência viva da v3, em `https://api.atende.bot/public/v3/docs`.

## Passo a passo
1. Gere um token em **Ajustes → API e webhooks → Tokens** e marque os escopos da integração. Cada recurso tem um escopo de leitura e um de escrita (ex.: `conversations:read`/`conversations:write`, `messages:write`, `cards:write`, `contacts:read`). `write` **não** libera `read`. O envio de e-mail tem permissão própria, **E-mails transacionais**, e token com **Acesso total** não a inclui: edite o token e marque **E-mails** (veja [Enviar um e-mail transacional pela API](/books/api-e-integracoes/page/enviar-um-e-mail-transacional-pela-api)).
2. Faça a primeira chamada, trocando `SEU_TOKEN` pelo token gerado:

   ```bash
   curl https://api.atende.bot/public/v3/conversations?page_size=5 \
     -H "Authorization: Bearer SEU_TOKEN"
   ```

3. A resposta traz o envelope padrão de listagem: `{ "data": [...], "meta": { "page": 1, "page_size": 5, "has_more": true, "total": null } }`. `total` só vem quando você pede `with_total=true`; `has_more` vem sempre.
4. Para o contrato completo de cada recurso, use a referência viva em `https://api.atende.bot/public/v3/docs`, gerada dos schemas das rotas, com try-it. Esta central cobre receitas prontas, não o dicionário de campos.

## Resultado esperado
Token **ATIVO** com os escopos certos; a chamada de teste devolve `200` com o envelope `{ data, meta }`.

## Erros comuns
- **Sintoma:** `401`. **Solução:** confira o header `Authorization: Bearer ...` e se o token não está **REVOGADO**.
- **Sintoma:** `403` de escopo insuficiente. **Solução:** adicione o escopo que falta ao token em **Ajustes → API e webhooks → Tokens** (em um token existente, use **Editar escopos** na linha do token e salve).
- **Sintoma:** preciso abrir chamado de suporte sobre uma chamada que falhou. **Solução:** todo erro vem com `error.details.request_id`; envie esse valor junto do chamado.

## Artigos relacionados
- [Gerar tokens de API para integrações](/books/canais-e-integracoes/page/gerar-tokens-de-api-para-integracoes)
- [Configurar webhooks para sistemas externos](/books/canais-e-integracoes/page/configurar-webhooks-para-sistemas-externos)
- [Distribuir um atendimento para um vendedor via n8n](/books/api-e-integracoes/page/distribuir-um-atendimento-para-um-vendedor-via-n8n)
- [Enviar um e-mail transacional pela API](/books/api-e-integracoes/page/enviar-um-e-mail-transacional-pela-api)