Como criar tickets Zendesk usando a API: Um guia JSON completo

Se você estiver criando integrações com o Zendesk, é provável que precise criar tickets programaticamente. Seja conectando um formulário da web personalizado, sincronizando dados de outro sistema ou automatizando fluxos de trabalho de suporte, a API de Tickets do Zendesk é a maneira padrão de inserir dados no Zendesk.

Este guia explica tudo o que você precisa saber sobre a criação de tickets via API, desde a autenticação até payloads JSON avançados.

O que você precisa para começar

Antes de começar a fazer chamadas de API, certifique-se de ter esses conceitos básicos cobertos:

• Uma conta de Suporte Zendesk com acesso de administrador ou agente. Se você não tiver uma, pode obter uma conta de avaliação gratuita para desenvolvimento
• Acesso ao token de API habilitado no seu Admin Center em Apps e integrações > APIs > Tokens de API
• Familiaridade básica com solicitações HTTP e estruturas de dados JSON
• Uma ferramenta para fazer chamadas de API: cURL, Python com a biblioteca requests ou um ambiente JavaScript

Se você é novo no trabalho com APIs REST, a documentação do Zendesk tem um guia de início rápido útil que usa o console JavaScript do seu navegador para testar solicitações sem nenhuma configuração.

Entendendo o endpoint da API de Tickets do Zendesk

O endpoint JSON de criação de tickets da API Zendesk segue um padrão consistente em todas as instâncias do Zendesk:

POST https://{subdomínio}.zendesk.com/api/v2/tickets.json

Aqui está o que você precisa saber sobre o endpoint:

• Método HTTP: POST para criar novos tickets
• Cabeçalho Content-Type: Deve ser definido como application/json
• Autenticação: Autenticação básica usando seu e-mail e token de API
• Limites de taxa: 700 solicitações por minuto para a maioria dos endpoints

A API retorna um status 201 Created em caso de sucesso, juntamente com o objeto de ticket completo, incluindo o ID do ticket recém-atribuído. Se algo der errado, você receberá um status 4xx ou 5xx com uma mensagem de erro explicando o problema.

Configurando a autenticação da API

A autenticação é onde a maioria dos desenvolvedores encontra seu primeiro obstáculo. O Zendesk usa autenticação básica com uma reviravolta: em vez de sua senha, você usa um token de API.

Gerando um token de API

1. Faça login no Zendesk como administrador
2. Vá para Admin Center > Apps e integrações > APIs > Tokens de API
3. Clique no ícone de mais para adicionar um token
4. Dê a ele um nome descritivo (como "Script de Criação de Ticket")
5. Copie o token imediatamente (você não o verá novamente)

Formato de autenticação

As credenciais seguem este formato:

Nome de usuário: {seu_email}/token
Senha: {seu_token_api}

Por exemplo, se seu e-mail for admin@empresa.com e seu token for abc123xyz, você usaria:

Nome de usuário: admin@empresa.com/token
Senha: abc123xyz

Melhores práticas de segurança

Nunca coloque suas credenciais de API diretamente em seus scripts. Em vez disso, use variáveis de ambiente:

import os

ZENDESK_SUBDOMINIO = os.getenv('ZENDESK_SUBDOMINIO')
ZENDESK_API_TOKEN = os.getenv('ZENDESK_API_TOKEN')
ZENDESK_USER_EMAIL = os.getenv('ZENDESK_USER_EMAIL')

Isso mantém suas credenciais fora do controle de versão e torna seu código mais portátil entre ambientes.

Estrutura JSON básica de criação de ticket

No mínimo, um ticket Zendesk precisa de duas coisas: um assunto e um comentário. Aqui está o payload JSON válido mais simples:

{
  "ticket": {
    "subject": "Minha impressora está pegando fogo!",
    "comment": {
      "body": "A fumaça é muito colorida."
    }
  }
}

O objeto ticket envolve tudo. Dentro, você define:

• subject: O título do ticket (obrigatório)
• comment: Um objeto contendo pelo menos um body (obrigatório)

Por padrão, os comentários são públicos. Se você quiser criar uma nota interna, adicione "public": false ao objeto de comentário.

Formato de resposta

Quando sua solicitação for bem-sucedida, a API retornará o ticket criado:

{
  "ticket": {
    "id": 35436,
    "url": "https://empresa.zendesk.com/api/v2/tickets/35436.json",
    "subject": "Minha impressora está pegando fogo!",
    "status": "open",
    "created_at": "2026-03-01T22:55:29Z",
    ...
  }
}

O campo id é o que você usará para referenciar este ticket em futuras chamadas de API.

Exemplos de código para criar tickets

Vamos ver exemplos práticos em três linguagens comuns.

Exemplo cURL

curl https://suaempresa.zendesk.com/api/v2/tickets.json \
  -d '{"ticket": {"subject": "Ticket de teste", "comment": {"body": "Este é um teste"}}}' \
  -H "Content-Type: application/json" \
  -v -u seu@email.com/token:seu_token_api \
  -X POST

A flag -v mostra a saída detalhada, o que ajuda na depuração. Remova-a em produção.

Exemplo Python

import requests
import os
import json

subdomínio = os.getenv('ZENDESK_SUBDOMINIO')
email = os.getenv('ZENDESK_USER_EMAIL')
token = os.getenv('ZENDESK_API_TOKEN')

url = f'https://{subdomínio}.zendesk.com/api/v2/tickets.json'
auth = (f'{email}/token', token)
headers = {'Content-Type': 'application/json'}

data = {
    'ticket': {
        'subject': 'Problema com a impressora',
        'comment': {
            'body': 'A impressora não está respondendo.',
            'public': True
        }
    }
}

response = requests.post(url, json=data, auth=auth, headers=headers)

if response.status_code == 201:
    ticket = response.json()['ticket']
    print(f"Ticket criado #{ticket['id']}")
else:
    print(f"Erro: {response.status_code}")
    print(response.text)

Observe que requests.post() com o parâmetro json= serializa automaticamente o dicionário para JSON e define o cabeçalho Content-Type.

Exemplo JavaScript

Se você estiver trabalhando em um navegador com o Zendesk já carregado, pode usar jQuery:

const ticket = {
  ticket: {
    subject: 'Ajuda com o login',
    comment: {
      body: 'Não consigo acessar minha conta.'
    }
  }
};

$.ajax({
  url: '/api/v2/tickets.json',
  type: 'POST',
  contentType: 'application/json',
  data: JSON.stringify(ticket)
}).done(data => {
  console.log('Ticket criado:', data.ticket.id);
}).fail(err => {
  console.error('Erro:', err);
});

Para Node.js, use a API fetch nativa ou uma biblioteca como axios:

const response = await fetch('https://empresa.zendesk.com/api/v2/tickets.json', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from(`${email}/token:${token}`).toString('base64')
  },
  body: JSON.stringify(ticket)
});

const data = await response.json();

Propriedades avançadas do ticket

Depois de dominar o básico, você pode definir propriedades adicionais para criar tickets mais completos.

Campos personalizados

Se sua instância do Zendesk tiver campos de ticket personalizados, defina-os usando seus IDs de campo:

{
  "ticket": {
    "subject": "Consulta de pedido",
    "comment": {"body": "Pergunta sobre pedido recente"},
    "custom_fields": [
      {"id": 25356371, "value": "ORD-12345"},
      {"id": 25356634, "value": "2026-03-01"}
    ]
  }
}

Para campos suspensos, use o valor da tag (não o texto de exibição). Para campos de múltipla escolha, passe um array de valores de tag.

Definindo o solicitante

Você pode criar um ticket em nome de outra pessoa:

{
  "ticket": {
    "subject": "Solicitação de suporte",
    "comment": {"body": "Precisa de ajuda com o faturamento"},
    "requester": {
      "name": "John Smith",
      "email": "john@example.com",
      "locale_id": 8
    }
  }
}

Se o e-mail não existir no Zendesk, um novo perfil de usuário será criado automaticamente.

Colaboradores e seguidores

Adicione colaboradores (usuários que recebem atualizações) ou seguidores (agentes que rastreiam o ticket):

{
  "ticket": {
    "subject": "Problema da equipe",
    "comment": {"body": "Isso afeta vários departamentos"},
    "collaborators": ["usuario1@exemplo.com", "usuario2@exemplo.com"],
    "followers": [
      {"user_email": "agente@empresa.com", "action": "put"}
    ]
  }
}

Anexos de arquivo

Para anexar arquivos, você primeiro precisa enviá-los separadamente para obter um token de upload e, em seguida, incluir esse token na criação do ticket:

{
  "ticket": {
    "subject": "Screenshot anexado",
    "comment": {
      "body": "Veja a mensagem de erro anexada",
      "uploads": ["vz7ll9ud8oofowy"]
    }
  }
}

Criação assíncrona

Para tickets com regras de negócios complexas que podem levar tempo para serem processadas, use a criação assíncrona:

POST /api/v2/tickets.json?async=true

Isso retorna um 202 Accepted imediatamente com um status de trabalho que você pode pesquisar para verificar a conclusão.

Chaves de idempotência

Para evitar tickets duplicados ao tentar novamente solicitações com falha, inclua uma chave de idempotência:

curl ... -H "Idempotency-Key: id-de-solicitação-único-123"

As chaves expiram após 2 horas. Reutilizar a mesma chave com parâmetros diferentes retorna um erro.

Erros comuns e solução de problemas

Aqui estão os erros que você provavelmente encontrará e como corrigi-los.

422 Entidade Não Processável

Isso geralmente significa que seu JSON está malformado. Causas comuns:

• Aspas ausentes em torno de nomes de propriedades ou valores de string
• Vírgulas à direita em objetos JSON
• Usando aspas simples em vez de aspas duplas
• Sequências de escape inválidas em strings

Se você estiver construindo strings JSON manualmente (especialmente em VBA ou linguagens mais antigas), fique atento a caracteres de aspas extras. O JSON deve ter esta aparência:

{"ticket": {"subject": "Teste", "comment": {"body": "Olá"}}}

Não assim:

"{"ticket": {"subject": "Teste"}}"

401 Não Autorizado

Suas credenciais de autenticação estão incorretas. Verifique:

• O endereço de e-mail está correto?
• Você incluiu /token após o e-mail?
• O token de API é válido e não expirou?
• O usuário tem permissão para criar tickets?

429 Limite de Taxa Excedido

Você atingiu o limite de taxa da API. O Zendesk permite 700 solicitações por minuto para a maioria dos endpoints. Se você precisar criar muitos tickets, adicione atrasos entre as solicitações ou use o endpoint de criação de tickets em massa.

400 Solicitação Inválida com erros de campo

Isso acontece quando os valores dos campos do ticket são inválidos:

• IDs de campo personalizados não existem
• Os valores suspensos não correspondem às opções disponíveis
• Os campos obrigatórios estão faltando
• Os formatos de data estão incorretos (use ISO 8601: 2026-03-01)

Automatizando a criação de tickets sem código

Construir e manter integrações de API leva tempo. Você precisa lidar com autenticação, lógica de repetição de erros, limitação de taxa e manutenção contínua à medida que as APIs mudam.

Se seu objetivo é automatizar a criação de tickets em vez de criar uma integração personalizada, considere se você realmente precisa escrever código. Ferramentas como o eesel AI podem lidar com a criação e as respostas de tickets sem nenhum trabalho de desenvolvimento.

Aqui está a diferença: com a abordagem da API, você está escrevendo scripts para criar tickets que os humanos responderão. Com um agente de IA, você está treinando um sistema para entender seu negócio e lidar com todo o ciclo de vida do ticket, desde a criação até a resolução. Você o conecta à sua conta Zendesk e ele aprende com seus tickets anteriores, artigos da central de ajuda e macros.

O modelo de lançamento progressivo significa que você começa com a IA elaborando respostas para revisão e, em seguida, expande para automação total à medida que ela se prova. Para equipes que buscam reduzir o volume de tickets em vez de apenas automatizar a criação, isso geralmente oferece resultados mais rápidos do que o desenvolvimento de API personalizado.