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

# Primeira chamada

> Crie um token no painel do Connecta DESK e faça sua primeira requisição autenticada à API v1.

Ao final desta página você terá um token válido e uma resposta real da API. Você vai criar o token
no painel e chamar um endpoint de leitura.

## Antes de começar

<Info>
  Somente **administradores** da empresa podem criar tokens. Se o menu **Integrações** não aparece
  nas configurações, peça o token a quem administra a conta.
</Info>

A URL base é `https://api.connectadesk.com/api/v1`. Se a sua empresa usa uma instalação própria,
troque pelo domínio dela e mantenha o `/api/v1` no fim.

<Steps>
  <Step title="Crie o token no painel">
    Vá em **Configurações → Integrações → API** e clique em **Novo token**. Preencha os campos:

    * **Nome**: como você vai reconhecer o token na listagem. Use o nome do sistema que vai usar a
      API, e não algo como "token 1".
    * **Permissões**: marque só os módulos e métodos de que a integração precisa. Um relatório
      externo, por exemplo, só precisa de `GET`.
    * **Prazo**: defina uma data de expiração sempre que a integração for temporária.
    * **IPs autorizados**: se o sistema que vai chamar a API tem IP fixo, restrinja o acesso a
      ele. Em branco, a API aceita chamadas de qualquer origem.

    <Warning>
      A chave completa aparece **uma única vez**, no momento da criação. Depois disso o painel
      mostra só o prefixo (`sk_live_ab12cd34…`). Se você perder a chave, não há como recuperá-la.
      Nesse caso, rotacione o token.
    </Warning>
  </Step>

  <Step title="Guarde a chave fora do código">
    ```bash theme={null}
    export CONNECTA_TOKEN="sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
    export CONNECTA_URL="https://api.connectadesk.com/api/v1"
    ```

    A chave dá acesso aos dados de toda a empresa, dentro das permissões marcadas. Trate a chave
    como uma senha e nunca a coloque em repositório, log ou front-end.
  </Step>

  <Step title="Faça a chamada">
    Liste os contatos da empresa. Como é um `GET`, nada é alterado, e a chamada serve para
    confirmar que o token, o host e a permissão estão corretos.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
        --url "$CONNECTA_URL/contacts?perPage=2" \
        --header "Authorization: Bearer $CONNECTA_TOKEN"
      ```

      ```javascript Node.js theme={null}
      const res = await fetch(`${process.env.CONNECTA_URL}/contacts?perPage=2`, {
        headers: { Authorization: `Bearer ${process.env.CONNECTA_TOKEN}` }
      });

      const { data, meta } = await res.json();
      console.log(data, meta);
      ```

      ```python Python theme={null}
      import os, requests

      res = requests.get(
          f"{os.environ['CONNECTA_URL']}/contacts",
          params={"perPage": 2},
          headers={"Authorization": f"Bearer {os.environ['CONNECTA_TOKEN']}"},
      )

      print(res.json())
      ```

      ```php PHP theme={null}
      $ch = curl_init(getenv('CONNECTA_URL') . '/contacts?perPage=2');
      curl_setopt_array($ch, [
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONNECTA_TOKEN')],
      ]);

      echo curl_exec($ch);
      ```
    </CodeGroup>
  </Step>

  <Step title="Leia a resposta">
    ```json theme={null}
    {
      "data": [
        {
          "id": 1042,
          "name": "Marina Alves",
          "number": "5511999999999",
          "email": "marina@exemplo.com.br",
          "isGroup": false,
          "tags": [{ "id": 3, "name": "Cliente", "color": "#22C55E" }]
        },
        {
          "id": 1043,
          "name": "Rafael Nunes",
          "number": "5521988888888",
          "email": null,
          "isGroup": false,
          "tags": []
        }
      ],
      "meta": { "page": 1, "perPage": 2, "hasMore": true }
    }
    ```

    Os registros vêm sempre em `data`. Nas listas, `meta` informa a página atual e se existem
    mais registros. A resposta **não traz `total`**. Para percorrer tudo, avance `page` enquanto
    `hasMore` for `true`.
  </Step>
</Steps>

## Se a resposta não foi 200

<AccordionGroup>
  <Accordion title="401 ERR_API_UNAUTHORIZED" icon="lock">
    A API devolve o mesmo 401 para token ausente, malformado, inexistente, revogado, expirado ou
    usado a partir de um IP que não está entre os autorizados. Por segurança, a resposta não diz
    qual foi o motivo.

    Confira, nesta ordem: se o header está no formato `Authorization: Bearer sk_live_…`; se o
    token não está revogado nem vencido no painel; e, se você configurou IPs autorizados, se a
    chamada está saindo do IP esperado.
  </Accordion>

  <Accordion title="403 ERR_API_FORBIDDEN_SCOPE" icon="shield-x">
    O token é válido, mas não tem permissão para aquele método naquele módulo. A mensagem de erro
    informa qual combinação faltou. Edite as permissões do token no painel. Veja
    [Permissões](/essentials/permissoes).
  </Accordion>

  <Accordion title="403 ERR_API_NOT_ENABLED" icon="ban">
    O plano da empresa não inclui a API pública. Fale com o time comercial, porque não há nada a
    corrigir na integração.
  </Accordion>

  <Accordion title="404 em tudo" icon="link-2-off">
    Quase sempre a causa é a URL base sem o `/api/v1` ou o host errado. A API devolve o 404 no
    mesmo envelope de erro das outras respostas (`ERR_API_ROUTE_NOT_FOUND`). Se o corpo do 404
    veio em HTML, sua chamada não chegou à API.
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Enviar uma mensagem" icon="send" href="/guides/enviar-mensagens">
    O fluxo assíncrono completo, do `202` até a confirmação do envio.
  </Card>

  <Card title="Erros" icon="triangle-alert" href="/essentials/erros">
    O envelope de erro e o que cada código significa.
  </Card>

  <Card title="Idempotência" icon="repeat" href="/essentials/idempotencia">
    Como repetir uma chamada sem duplicar o efeito.
  </Card>

  <Card title="Referência" icon="code" href="/api-reference/introduction">
    Todos os endpoints, com playground para testar no navegador.
  </Card>
</CardGroup>


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