> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectadesk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissões do token

> O token é autorizado por módulo e por método. Conheça os 17 módulos da API do Connecta DESK e como definir o escopo mínimo de cada integração.

A permissão de um token é uma matriz de **módulo × método**. Cada rota da API pertence a um
módulo, e o método é o verbo HTTP da requisição. Para uma chamada funcionar, o token precisa ter
aquele método liberado naquele módulo.

```json theme={null}
{
  "contacts": ["GET", "POST"],
  "tickets": ["GET"]
}
```

Esse token pode ler e criar contatos e ler atendimentos, e nada mais. `PUT /contacts/{id}`
responde 403, assim como qualquer chamada a produtos, campanhas ou CRM.

<Info>
  A permissão é a última verificação feita. Antes dela, a API confere se o token é válido, se a
  empresa está ativa, se o plano inclui a API e se o limite de requisições não foi atingido. Por
  isso, um 403 de escopo sempre significa que o token era válido e a chamada chegou ao endpoint
  certo.
</Info>

## Os módulos

<Columns cols={2}>
  <Card title="contacts" icon="user" horizontal>
    Contatos, campos extras e origem de marketing.
  </Card>

  <Card title="tickets" icon="message-square" horizontal>
    Abertura, transferência, encerramento e qualificação.
  </Card>

  <Card title="messages" icon="send" horizontal>
    Envio assíncrono e leitura de mensagens.
  </Card>

  <Card title="channels" icon="smartphone" horizontal>
    Canais e templates. Somente leitura.
  </Card>

  <Card title="webchat" icon="messages-square" horizontal>
    Sessões e mensagens de visitantes do webchat.
  </Card>

  <Card title="tags" icon="tags" horizontal>
    Tags e vínculo com atendimentos.
  </Card>

  <Card title="queues" icon="list-video" horizontal>
    Filas de atendimento e seus atendentes.
  </Card>

  <Card title="wrapups" icon="award" horizontal>
    Tipos de qualificação.
  </Card>

  <Card title="users" icon="user-cog" horizontal>
    Atendentes, administradores e convites.
  </Card>

  <Card title="profiles" icon="shield-check" horizontal>
    Perfis de permissões. Somente leitura.
  </Card>

  <Card title="schedules" icon="calendar" horizontal>
    Mensagens programadas.
  </Card>

  <Card title="quick-messages" icon="zap" horizontal>
    Respostas rápidas.
  </Card>

  <Card title="campaigns" icon="megaphone" horizontal>
    Disparos em massa e sua execução.
  </Card>

  <Card title="crm" icon="kanban" horizontal>
    Painéis, etapas, cards e indicadores.
  </Card>

  <Card title="products" icon="package" horizontal>
    Catálogo, categorias e desempenho.
  </Card>

  <Card title="custom-fields" icon="list-plus" horizontal>
    Campos personalizados e variáveis globais.
  </Card>

  <Card title="reports" icon="chart-column" horizontal>
    Relatórios e dashboards.
  </Card>
</Columns>

Os métodos são `GET`, `POST`, `PUT` e `DELETE`. Nenhuma rota da v1 usa `PATCH`, por isso ele não
aparece na lista.

O módulo `profiles` aceita apenas `GET`. Ele existe para você descobrir o `profileId` usado ao
convidar ou editar um usuário; perfis são criados e editados no painel.

O módulo `webchat` aceita `GET` e `POST`: com ele, o seu sistema abre a sessão de um visitante,
envia as mensagens dele e lê as respostas. O webchat é configurado no painel.

## Escolhendo o escopo

Dê ao token apenas as permissões que a integração precisa para funcionar. Alguns exemplos comuns:

<AccordionGroup>
  <Accordion title="Painel ou BI externo" icon="chart-column">
    ```json theme={null}
    { "reports": ["GET"], "tickets": ["GET"], "contacts": ["GET"] }
    ```

    Somente leitura. Mesmo que vaze, um token assim não consegue alterar nenhum dado, então é uma
    boa opção para ferramentas de terceiros.
  </Accordion>

  <Accordion title="Notificações transacionais" icon="send">
    ```json theme={null}
    { "messages": ["POST"], "channels": ["GET"] }
    ```

    Basta para enviar mensagens e descobrir o `channelId` do canal de saída. Não é preciso incluir
    `contacts` nem `tickets`, porque o envio já cria o contato e o atendimento quando necessário.
  </Accordion>

  <Accordion title="Sincronização de cadastro" icon="refresh-cw">
    ```json theme={null}
    { "contacts": ["GET", "POST", "PUT"], "custom-fields": ["GET"], "tags": ["GET"] }
    ```

    Esse escopo não inclui `DELETE`. Se a sincronização tiver um erro e apagar contatos, o
    prejuízo é difícil de desfazer. Se a integração precisar excluir contatos, use um segundo
    token, em uma rotina separada.
  </Accordion>

  <Accordion title="Automação de painel" icon="kanban">
    ```json theme={null}
    { "crm": ["GET", "POST", "PUT"], "contacts": ["GET"], "products": ["GET"] }
    ```

    Move cards e registra anotações. Lê contatos e o catálogo sem poder alterá-los.
  </Accordion>
</AccordionGroup>

<Warning>
  Permissão de escrita em `users` dá poder de administrador. Com `users: ["POST"]`, o token convida
  pessoas para a empresa. Com `users: ["PUT"]`, ele altera o perfil de quem já faz parte dela e
  pode até promover alguém a administrador. Conceda essas duas permissões apenas a integrações de
  RH ou de provisionamento que realmente precisem delas.
</Warning>

## Quando falta permissão

```json theme={null}
{
  "error": {
    "code": "ERR_API_FORBIDDEN_SCOPE",
    "message": "O token não tem permissão de POST no módulo \"contacts\"."
  }
}
```

A mensagem informa o método e o módulo que faltaram. Para corrigir, abra o token no painel e marque
essa combinação.

<Tip>
  A lista de módulos acima é a mesma que aparece no painel ao criar um token. Se o painel mostrar
  um módulo que não está aqui, considere o painel como a referência correta.
</Tip>

## O que o token nunca faz

Independentemente das permissões marcadas:

* **Não gerencia tokens.** Criar, editar, rotacionar e revogar tokens exige uma sessão de
  administrador no painel.
* **Não troca de empresa.** A empresa é sempre a do próprio token. Um `companyId` enviado no corpo
  é ignorado.
* **Não enxerga o super admin.** O vínculo de suporte da plataforma não aparece em `GET /users` e
  não pode ser alterado pela API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.