Tickets
Criar, listar e consultar tickets pela API v1. Criação idempotente por external_id.
Todos os endpoints abaixo exigem a HSDesk Key no header
Authorization. A organização é resolvida pela credencial.
Criar ticket
POST /api/v1/tickets
O solicitante vira (ou reaproveita) um contato da organização, deduplicado por
external_id, o ID do cliente no seu sistema. O contato é vinculado automaticamente ao
ticket.
| Campo | Obrigatório | Descrição |
|---|---|---|
assunto | sim | Título do ticket. |
descricao | sim | Corpo/descrição. |
prioridade | não | baixa · media · alta · urgente. |
external_id | não | ID do ticket no seu sistema; habilita idempotência. |
solicitante.nome | sim | Nome do solicitante. |
solicitante.email | não | E-mail do solicitante. |
solicitante.telefone | não | Telefone do solicitante. |
solicitante.external_id | não | ID do cliente no seu sistema (dedupe do contato). |
curl -X POST https://api.hsdesk.com.br/api/v1/tickets \
-H "Authorization: Bearer hsk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"assunto": "Erro no checkout",
"descricao": "O pagamento falha ao finalizar.",
"prioridade": "alta",
"external_id": "TCK-9001",
"solicitante": {
"nome": "Maria Cliente",
"email": "maria@cliente.com",
"telefone": "+55 11 98888-7777",
"external_id": "C-9921"
}
}'201 Created → o ticket criado (esquema TicketPublico).
Idempotência por external_id
Se você enviar um external_id que já existe na organização, a API não duplica:
devolve o ticket existente com 200 e a mensagem Ticket já existente para este external_id.. Isso torna seguro reenviar a mesma requisição (retry de rede,
reprocessamento de fila). Sem external_id, cada chamada cria um ticket novo.
Listar tickets
GET /api/v1/tickets
Query params: prioridade, numero, busca, por_pagina (máx. 100).
curl "https://api.hsdesk.com.br/api/v1/tickets?prioridade=alta" \
-H "Authorization: Bearer hsk_live_xxx"data é uma lista paginada: além de data.data (os itens), traz total,
por_pagina, pagina_atual e ultima_pagina.
Consultar ticket
GET /api/v1/tickets/{id}
Retorna o ticket e, em respostas, apenas as respostas públicas do thread.
Notas internas nunca são expostas
Comentários internos dos atendentes não aparecem na API pública: só respostas públicas (do atendente ou do cliente).
Referência interativa
Veja os esquemas completos de requisição/resposta e teste as chamadas na Referência da API.