Guia rápido
Da credencial à primeira integração. Criar a chave, abrir um ticket, configurar webhooks e manter a conversa.
Um passo a passo mínimo para integrar seu sistema ao fluxo de tickets do HSDesk.
Ainda não há ambiente de homologação
No momento o HSDesk tem apenas ambiente de produção (https://api.hsdesk.com.br). Os testes
iniciais da sua integração rodam direto na produção da sua organização. Sem problema: os
tickets criados durante os testes podem ser excluídos depois pelo painel.
Gere uma HSDesk Key
No painel (Configurações → API Pública e Webhooks → Credenciais) clique em
Nova credencial, dê um nome e copie a chave (hsk_live_…): ela aparece só uma
vez. Veja Credenciais no painel.
Abra um ticket
Crie o primeiro ticket informando o solicitante. Use external_id para tornar a
chamada idempotente.
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.",
"external_id": "TCK-9001",
"solicitante": { "nome": "Maria Cliente", "external_id": "C-9921" }
}'Guarde o id do ticket retornado. Veja Endpoints → Tickets.
Configure um webhook
Cadastre um endpoint HTTPS e assine os eventos que importam (ex.:
ticket.resposta_publica, ticket.resolvido). Guarde o segredo (whsec_…) para
verificar a assinatura.
Mantenha a conversa
Responda como cliente com POST /api/v1/tickets/{id}/respostas e receba as respostas
do atendente pelo webhook ticket.resposta_publica. Suas próprias mensagens não
voltam como webhook (sem eco).
Checklist de produção
Referência completa
Os esquemas de cada endpoint e um playground para testar estão na Referência da API.