Integrações e API
Documentação da API pública do Contact Desk
Guia completo e seguro para integrar sistemas externos ao Contact Desk usando a API pública.
Resposta rápida
A API pública do Contact Desk permite que sistemas externos criem tickets, consultem registros autorizados, adicionem comentários e sincronizem cadastros operacionais sem expor credenciais no navegador. Toda integração deve usar HTTPS, token Bearer guardado no servidor e identificação do tenant por header quando necessário.
Passo a passo
- Gere um token de API com o menor escopo possível.
- Guarde o token somente no backend do sistema integrador.
- Envie as requisições para /api/v1 usando Authorization: Bearer.
- Inclua X-Tenant quando a integração precisar informar explicitamente o tenant.
- Monitore respostas, limites e logs de auditoria.
URL base e formato
Use a URL base pública do ambiente contratado e sempre envie Accept: application/json. Para escrita, envie também Content-Type: application/json. Em produção, a integração deve usar apenas HTTPS.
- Base recomendada: https://app.contactdesk.com.br/api/v1
- Formato de resposta: JSON
- Autenticação: Bearer token via header Authorization
- Tenant: header X-Tenant com o slug do tenant quando solicitado pelo administrador.
Autenticação
O token de API representa uma credencial técnica. Ele não deve ser colocado em JavaScript público, aplicativo mobile distribuído, planilhas compartilhadas, prints, URLs ou repositórios de código.
- Authorization: Bearer {TOKEN_DA_API}
- X-Tenant: {TENANT_SLUG}
- Tokens devem ter escopo mínimo e rotação periódica.
- Ao suspeitar de vazamento, revogue o token imediatamente e gere outro.
Criação de tickets
A criação de ticket exige fila e categoria válidas no tenant. Prioridade, impacto, SLA e solicitante podem ser informados conforme o fluxo liberado para o token.
- Campos comuns: title, description, queue_id, category_id, priority, impact, sla_id, requester_id.
- IDs de fila e categoria devem ser obtidos no Contact Desk ou por endpoints autorizados.
- O sistema valida tenant, permissões e existência dos recursos antes de criar o ticket.
Respostas e erros
A API utiliza códigos HTTP para indicar o resultado. O integrador deve tratar falhas sem repetir requisições indefinidamente.
- 200 ou 201: operação concluída.
- 401: token ausente ou inválido.
- 403: token sem permissão ou tenant não autorizado.
- 404: recurso não encontrado no tenant.
- 422: payload inválido ou campo obrigatório ausente.
- 429: limite de requisições excedido.
Endpoints documentados
| Método | Rota | Autenticação | Uso |
|---|---|---|---|
| GET | /api/v1/tenants/current |
Bearer token | Retorna o tenant atual da requisição autenticada. |
| GET | /api/v1/tickets |
Bearer token | Lista tickets permitidos para o token e tenant informado. |
| POST | /api/v1/tickets |
Bearer token | Cria um novo ticket com fila, categoria, título e descrição. |
| GET | /api/v1/tickets/{ticket} |
Bearer token | Consulta os dados de um ticket específico. |
| PUT/PATCH | /api/v1/tickets/{ticket} |
Bearer token | Atualiza campos permitidos de um ticket. |
| DELETE | /api/v1/tickets/{ticket} |
Bearer token | Remove ou cancela conforme regra e permissão do tenant. |
| POST | /api/v1/tickets/{ticket}/comments |
Bearer token | Adiciona comentário ao histórico do ticket. |
| GET | /api/v1/users |
Bearer token | Lista usuários autorizados para sincronização. |
| GET | /api/v1/queues |
Bearer token | Lista filas disponíveis no tenant. |
| GET | /api/v1/categories |
Bearer token | Lista categorias disponíveis no tenant. |
| GET | /api/v1/slas |
Bearer token | Lista políticas de SLA disponíveis no tenant. |
Exemplos seguros
curl -X POST "https://app.contactdesk.com.br/api/v1/tickets" \
-H "Authorization: Bearer {TOKEN_DA_API}" \
-H "X-Tenant: {TENANT_SLUG}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"title": "Solicitação recebida pelo sistema externo",
"description": "Descreva aqui o contexto da solicitação.",
"queue_id": 1,
"category_id": 2,
"priority": "normal"
}'const response = await fetch('https://app.contactdesk.com.br/api/v1/tickets', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CONTACT_DESK_API_TOKEN}`,
'X-Tenant': process.env.CONTACT_DESK_TENANT,
Accept: 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
title: 'Solicitação recebida pelo sistema externo',
description: 'Descreva aqui o contexto da solicitação.',
queue_id: 1,
category_id: 2,
priority: 'normal'
})
});
if (!response.ok) {
throw new Error(`Falha ao criar ticket: ${response.status}`);
}
const ticket = await response.json();Cuidados de segurança
- Nunca exponha o token da API em código front-end, DevTools, URL, localStorage ou aplicativo distribuído.
- Faça a integração por um backend próprio, que recebe a solicitação do cliente e chama a API do Contact Desk no servidor.
- Use tokens diferentes por sistema integrado, com escopo mínimo e possibilidade de revogação individual.
- Não grave Authorization, cookies, senhas ou payloads com dados sensíveis em logs abertos.
- Valide origem, volume e conteúdo das solicitações antes de repassar para o Contact Desk.
Boas práticas
- Revise permissões antes de liberar recursos para novos usuários.
- Teste mudanças em um fluxo controlado antes de aplicar em toda a operação.
- Use nomes claros para filas, categorias, automações e respostas prontas.
- Consulte logs e auditoria quando uma ação precisar de rastreabilidade.
Quando acionar o administrador?
Acione um administrador quando a configuração envolver credenciais, permissões, integrações, filas compartilhadas, políticas de SLA, automações globais ou dados sensíveis.