Primeira chamada

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

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.

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.

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.

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.

Guarde a chave fora do código

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.

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.

curl --request GET \
  --url "$CONNECTA_URL/contacts?perPage=2" \
  --header "Authorization: Bearer $CONNECTA_TOKEN"

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);

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())

$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);

Leia a resposta

{
  "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.

Se a resposta não foi 200

401 ERR_API_UNAUTHORIZED

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.

403 ERR_API_FORBIDDEN_SCOPE

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.

403 ERR_API_NOT_ENABLED

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.

404 em tudo

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.

Próximos passos

Enviar uma mensagem

O fluxo assíncrono completo, do 202 até a confirmação do envio.

Erros

O envelope de erro e o que cada código significa.

Idempotência

Como repetir uma chamada sem duplicar o efeito.

Referência

Todos os endpoints, com playground para testar no navegador.

Comece aqui

Fundamentos

Guias

Antes de começar

Se a resposta não foi 200

Próximos passos

Enviar uma mensagem

Erros

Idempotência

Referência

​Antes de começar

​Se a resposta não foi 200

​Próximos passos

Enviar uma mensagem

Erros

Idempotência

Referência

Antes de começar

Se a resposta não foi 200

Próximos passos