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

# Referência da API

> Como usar a referência da API do Connecta DESK: URL base, playground, versionamento e o mapa dos 17 módulos.

Esta seção documenta os 150 endpoints da v1, gerados a partir da especificação OpenAPI da API.
Cada página mostra os parâmetros aceitos, o corpo da requisição, o formato da resposta e um
playground para testar a chamada no próprio navegador.

## URL base

```bash theme={null}
https://api.connectadesk.com/api/v1
```

Instalações on-premise usam o domínio do próprio ambiente, seguido de `/api/v1`.

<Note>
  Criar, editar, rotacionar e revogar tokens não faz parte da API. Por segurança, essas operações
  só podem ser feitas no painel.
</Note>

## Testando pelo playground

<Steps>
  <Step title="Abra qualquer endpoint">
    Comece por um `GET`, como `GET /contacts`. Leituras não alteram nenhum dado.
  </Step>

  <Step title="Informe o token">
    No campo **Authorization**, cole a sua chave `sk_live_…`. Ela fica guardada apenas no seu
    navegador.
  </Step>

  <Step title="Confira o servidor">
    O playground aponta para `https://api.connectadesk.com/api/v1`. Se a sua instalação for
    on-premise, troque pelo domínio do seu ambiente.
  </Step>
</Steps>

<Warning>
  O playground faz chamadas **reais**. Um `DELETE` executado aqui apaga o registro de verdade, sem
  pedir confirmação e sem como desfazer. Enquanto estiver explorando, use dados de homologação.
</Warning>

## O mapa dos módulos

Cada grupo do menu à esquerda corresponde a um módulo de permissão do token. Se um endpoint
responder `403 ERR_API_FORBIDDEN_SCOPE`, está faltando no seu token a permissão do módulo daquele
grupo.

<Columns cols={2}>
  <Card title="Conversas" icon="message-square">
    Contatos, Atendimentos, Mensagens, Canais e Webchat. É a base para quem integra o atendimento.
  </Card>

  <Card title="Organização" icon="list">
    Tags, Filas, Qualificações, Usuários e Perfis de permissões. Definem como os atendimentos são
    distribuídos e classificados, e o que cada pessoa pode fazer.
  </Card>

  <Card title="Iniciativas" icon="megaphone">
    Agendamentos, Respostas rápidas e Campanhas. Cobrem as mensagens que partem da empresa para o
    cliente.
  </Card>

  <Card title="Vendas" icon="kanban">
    CRM, Produtos e Campos personalizados. Sustentam os painéis de vendas e o catálogo.
  </Card>

  <Card title="Relatórios" icon="chart-column">
    Relatórios de conversas, de automações e os indicadores do painel. Mostram os números da
    operação.
  </Card>
</Columns>

## Convenções

Algumas regras valem para todos os endpoints:

<CardGroup cols={2}>
  <Card title="Envelope" icon="box" href="/essentials/requisicoes-e-respostas">
    Todo recurso vem em `data`, e todo erro vem em `error`.
  </Card>

  <Card title="Paginação" icon="list" href="/essentials/paginacao">
    `page` e `perPage`, com `hasMore` para saber se há mais páginas. Não há `total`.
  </Card>

  <Card title="Idempotência" icon="repeat" href="/essentials/idempotencia">
    `Idempotency-Key` em `POST` e `PUT`.
  </Card>

  <Card title="Limites" icon="gauge" href="/essentials/limites-de-uso">
    Limite de requisições por minuto, por empresa.
  </Card>
</CardGroup>

## Versionamento

A versão faz parte do caminho: `/api/v1`. Enquanto ela existir, as mudanças serão apenas
**aditivas**. Podem surgir campos e endpoints novos, mas os que já existem mantêm nome, tipo e
significado.

Por isso, a sua integração deve ignorar os campos que não conhece, em vez de falhar ao
encontrá-los. Mudanças que quebram a compatibilidade só chegam com uma nova versão no caminho.


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