zendesk-api-update-ticket

{
  "title": "Como atualizar tickets usando a API do Zendesk em 2026",
  "slug": "zendesk-api-update-ticket",
  "locale": "pt",
  "date": "2026-03-02",
  "updated": "2026-03-02",
  "template": "default",
  "excerpt": "Um guia completo para atualizar tickets do Zendesk programaticamente usando a API REST, com exemplos em Python e cURL para autenticação, campos personalizados e operações em massa.",
  "categories": [
    "Zendesk",
    "Guides"
  ],
  "tags": [
    "Zendesk API",
    "ticket management",
    "REST API",
    "Python",
    "automation",
    "customer support"
  ],
  "readTime": 10,
  "author": 16,
  "reviewer": 14,
  "seo": {
    "title": "Como atualizar tickets usando a API do Zendesk em 2026",
    "description": "Um guia completo para atualizar tickets do Zendesk programaticamente usando a API REST, com exemplos em Python e cURL para autenticação, campos personalizados e operações em massa.",
    "image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-ac8285e6-432d-426a-8b58-1df767b97ea9"
  },
  "coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-ac8285e6-432d-426a-8b58-1df767b97ea9",
  "coverImageAlt": "Imagem do banner para Como atualizar tickets usando a API do Zendesk em 2026",
  "coverImageWidth": 1920,
  "coverImageHeight": 1080,
  "faqs": {
    "heading": "Perguntas Frequentes",
    "type": "blog",
    "answerType": "html",
    "faqs": [
      {
        "question": "Qual método de autenticação o endpoint de atualização de tickets da API do Zendesk requer?",
        "answer": "A API do Zendesk usa autenticação baseada em token. Você fornece seu endereço de e-mail combinado com /token como o nome de usuário e seu token de API como a senha. O formato é {email}/token:{api_token} no cabeçalho de autorização (Authorization)."
      },
      {
        "question": "Posso atualizar vários tickets do Zendesk de uma vez usando a API?",
        "answer": "Sim. Use o endpoint de atualização em massa PUT /api/v2/tickets/update_many.json com uma lista separada por vírgulas de IDs de tickets ou uma consulta de pesquisa. Você pode atualizar até 100 tickets por solicitação, e as atualizações em massa contam como uma única solicitação em relação ao seu limite de taxa."
      },
      {
        "question": "Como encontro o ID de um campo personalizado ao usar a API do Zendesk para atualizar tickets?",
        "answer": "Você pode encontrar os IDs de campos personalizados no Admin Center em Objetos e regras > Tickets > Campos personalizados. O ID aparece no URL quando você clica para editar um campo. Alternativamente, use o endpoint da API GET /api/v2/ticket_fields.json para listar todos os campos com seus IDs."
      },
      {
        "question": "Qual é o limite de taxa para atualizações de tickets da API do Zendesk?",
        "answer": "Os limites de taxa variam de acordo com o plano: os planos Team têm 200 solicitações por minuto, os planos Growth e Professional têm 400 e os planos Enterprise têm 700. As operações de atualização em massa contam como uma única solicitação, independentemente de quantos tickets elas afetem. Se você exceder o limite, receberá um erro 429 e deverá esperar antes de tentar novamente."
      },
      {
        "question": "Por que estou recebendo um erro 422 ao tentar atualizar um ticket através da API do Zendesk?",
        "answer": "Um erro 422 indica uma falha de validação. As causas comuns incluem o envio do tipo de dados errado para um campo, o fornecimento de um valor inválido para um campo personalizado suspenso ou a omissão de campos obrigatórios. Verifique o corpo da resposta para obter detalhes específicos do erro sobre qual campo falhou na validação."
      },
      {
        "question": "Existe uma alternativa sem código para usar a API do Zendesk para atualizações automatizadas de tickets?",
        "answer": "Sim. Ferramentas como o eesel AI fornecem gerenciamento automatizado de tickets sem exigir scripts de API. O eesel AI se conecta diretamente ao Zendesk, aprende com seus tickets e documentação existentes e lida com atualizações como marcação, roteamento e alterações de status com base em instruções em linguagem natural, em vez de código."
      }
    ],
    "supportLink": null
  }
}
---

Gerenciar tickets de suporte programaticamente é essencial para equipes que buscam automatizar fluxos de trabalho, integrar-se com outros sistemas ou criar ferramentas personalizadas. A [API de Tickets do Zendesk](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/) oferece controle total sobre as atualizações de tickets, desde simples alterações de status até operações em massa complexas envolvendo campos personalizados.

Este guia orienta você em tudo o que você precisa saber para começar a atualizar tickets via API, com exemplos de código funcional que você pode adaptar para seus próprios projetos.

![Fluxo de trabalho de atualização de ticket mostrando o fluxo de autenticação, a estrutura de dados da solicitação e o tratamento da resposta da API](https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/22939e08-e553-4fce-bb21-dfe35213e532)

## O que você precisa para começar

Antes de fazer sua primeira chamada de API, certifique-se de ter o seguinte em vigor:

- **Uma conta do Zendesk Support** com acesso de administrador ou agente. Você precisará de permissões para gerar tokens de API e visualizar dados de tickets.
- **Autenticação de token de API habilitada**. O acesso ao token deve ser ativado no seu Admin Center em Aplicativos e integrações > APIs > Tokens de API.
- **Familiaridade básica com APIs REST**. Você deve entender os métodos HTTP (GET, PUT, POST) e os formatos de dados JSON.
- **Suas ferramentas preferidas**. Este guia inclui exemplos em cURL e Python usando a biblioteca Requests, mas você pode usar Postman, JavaScript ou qualquer cliente HTTP.

![Página de tokens de API do Admin Center exibindo tokens de API ativos](https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_api_token_list2.png)

Se você está apenas começando com a API do Zendesk, talvez queira revisar o [guia de início rápido da API](https://developer.zendesk.com/documentation/ticketing/getting-started/zendesk-api-quick-start/) primeiro. Ele cobre o básico de fazer solicitações e lidar com respostas.

## Configurando a autenticação da API

O Zendesk usa autenticação baseada em token para acesso à API. Veja como configurar.

### Gerando um token de API

1. Faça login na sua conta do Zendesk como administrador
2. Vá para Admin Center > Aplicativos e integrações > APIs > Tokens de API
3. Clique no ícone de mais para adicionar um novo token
4. Dê a ele um nome descritivo como "Script de Atualização de Ticket"
5. Copie o token imediatamente. O Zendesk só o mostra uma vez.

![Interface do Admin Center do Zendesk para gerenciar tokens de API e configurações de autenticação](https://support.zendesk.com/hc/article_attachments/4408821771418/api_tokens_page.png)

### Formato de autenticação

O Zendesk espera credenciais neste formato:

{endereço_de_email}/token:{api_token}

Por exemplo, se seu e-mail for `admin@empresa.com` e seu token for `abc123xyz`, sua string de autenticação seria:

admin@empresa.com/token:abc123xyz

### Armazenando credenciais com segurança

Nunca codifique seu token de API em scripts. Em vez disso, use variáveis de ambiente:

```bash
export ZENDESK_SUBDOMAIN="suaempresa"
export ZENDESK_EMAIL="admin@empresa.com"
export ZENDESK_TOKEN="seu_token_api_aqui"

Em seguida, acesse-os em Python:

import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

auth = (f"{email}/token", token)

Testando sua autenticação

Faça uma solicitação GET simples para verificar se tudo funciona:

curl "https://suaempresa.zendesk.com/api/v2/tickets.json?per_page=1" \
  -u "admin@empresa.com/token:seu_token_api"

Se você receber uma resposta JSON com dados de ticket, você está autenticado e pronto para prosseguir. Se você receber um erro 401, verifique seu token e endereço de e-mail.

Atualizando um único ticket

O endpoint para atualizar tickets é direto:

PUT /api/v2/tickets/{ticket_id}.json

Atualização básica com cURL

Veja como atualizar o status de um ticket e adicionar um comentário:

curl "https://suaempresa.zendesk.com/api/v2/tickets/12345.json" \
  -X PUT \
  -u "admin@empresa.com/token:seu_token_api" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": {
      "status": "solved",
      "comment": {
        "body": "Este problema foi resolvido. A correção já está no ar.",
        "public": true
      }
    }
  }'

Implementação em Python

Usando a biblioteca Requests, a mesma operação se parece com isso:

import requests
import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

url = f"https://{subdomain}.zendesk.com/api/v2/tickets/12345.json"
auth = (f"{email}/token", token)

data = {
    "ticket": {
        "status": "solved",
        "priority": "normal",
        "assignee_id": 987654321,
        "comment": {
            "body": "Este problema foi resolvido. A correção já está no ar.",
            "public": True
        }
    }
}

response = requests.put(url, json=data, auth=auth)

if response.status_code == 200:
    print("Ticket atualizado com sucesso")
    updated_ticket = response.json()['ticket']
    print(f"Novo status: {updated_ticket['status']}")
else:
    print(f"Erro: {response.status_code}")
    print(response.text)

Campos comuns que você pode atualizar

Campo	Tipo	Descrição
status	string	new, open, pending, hold, solved, closed
priority	string	urgent, high, normal, low
assignee_id	integer	ID do agente a ser atribuído
group_id	integer	ID do grupo a ser atribuído
tags	array	Lista de strings de tags
subject	string	Linha de assunto do ticket

Ao atualizar o campo comment, definir "public": true torna-o uma resposta pública visível para o solicitante. Omitir isso ou defini-lo como false cria uma nota interna.

Trabalhando com campos personalizados

Campos personalizados são comuns em configurações do Zendesk para rastrear dados específicos, como categorias de produtos, níveis de clientes ou tipos de problemas. Atualizá-los via API requer conhecer o ID do campo.

Encontrando IDs de campos personalizados

Você pode encontrar IDs de campos personalizados de duas maneiras:

1. Admin Center: Vá para Objetos e regras > Tickets > Campos personalizados. O ID aparece no URL quando você edita um campo.
2. API: Liste todos os campos personalizados com GET /api/v2/ticket_fields.json

Atualizando campos personalizados

Campos personalizados usam um formato específico na API. Você fornece uma matriz de objetos com propriedades id e value:

{
  "ticket": {
    "custom_fields": [
      {"id": 25356371, "value": "enterprise"},
      {"id": 25356372, "value": 42},
      {"id": 25356373, "value": "billing_issue"}
    ]
  }
}

Aqui está um exemplo completo em Python:

import requests
import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

url = f"https://{subdomain}.zendesk.com/api/v2/tickets/12345.json"
auth = (f"{email}/token", token)

data = {
    "ticket": {
        "custom_fields": [
            {"id": 360012345678, "value": "premium"},      # Dropdown
            {"id": 360012345679, "value": "2026-03-15"},  # Date
            {"id": 360012345680, "value": 1500.00},        # Decimal
            {"id": 360012345681, "value": True}            # Checkbox
        ],
        "comment": {
            "body": "Nível do cliente e data de renovação atualizados.",
            "public": False
        }
    }
}

response = requests.put(url, json=data, auth=auth)

if response.status_code == 200:
    print("Campos personalizados atualizados com sucesso")
else:
    print(f"Erro {response.status_code}: {response.text}")

Armadilhas comuns com campos personalizados

• Tipo de dados errado: Enviar uma string quando o campo espera um número retornará um erro 422
• Valores de opção inválidos: Campos suspensos aceitam apenas valores predefinidos. Verifique a configuração do campo se as atualizações falharem.
• Permissões de campo: Alguns campos personalizados são somente leitura ou editáveis apenas por determinadas funções

Atualizando vários tickets em massa

Quando você precisa atualizar dezenas ou centenas de tickets, chamadas de API individuais são ineficientes. O Zendesk fornece endpoints de atualização em massa para este cenário.

O endpoint de atualização em massa

PUT /api/v2/tickets/update_many.json?ids=1,2,3,4,5

Você pode especificar tickets por ID ou usar uma consulta de pesquisa:

PUT /api/v2/tickets/update_many.json?query=status:open+priority:high

Quando usar atualizações em massa

Atualizações em massa fazem sentido quando você precisa:

• Reatribuir todos os tickets de um agente que está saindo
• Fechar tickets resolvidos com mais de 30 dias
• Atualizar um valor de campo personalizado em uma categoria de tickets
• Adicionar tags a tickets que correspondam a critérios específicos

Considerações sobre limite de taxa

O Zendesk impõe limites de taxa que variam de acordo com o plano: os planos Team têm 200 solicitações por minuto, os planos Growth e Professional têm 400 e os planos Enterprise têm 700. As atualizações em massa contam como uma única solicitação, independentemente de quantos tickets elas afetem, tornando-as muito mais eficientes do que chamadas individuais.

Melhores práticas para atualizações em grande escala

1. Teste em um pequeno lote primeiro. Execute sua atualização em 5 a 10 tickets para verificar a lógica antes de processar centenas.
2. Use consultas de pesquisa com cuidado. Uma consulta mal construída pode corresponder a milhares de tickets não intencionalmente.
3. Lide com a paginação. Se sua pesquisa retornar muitos resultados, processe-os em lotes.
4. Registre suas alterações. Mantenha um registro de quais tickets foram atualizados e quando.

Aqui está um exemplo que atualiza todos os tickets abertos atribuídos a um agente específico:

import requests
import os
import time

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

auth = (f"{email}/token", token)
base_url = f"https://{subdomain}.zendesk.com/api/v2"

search_url = f"{base_url}/search.json?query=assignee:987654321+status:open"
response = requests.get(search_url, auth=auth)
results = response.json()

ticket_ids = [str(ticket['id']) for ticket in results['results']]

for i in range(0, len(ticket_ids), 100):
    batch = ticket_ids[i:i+100]
    ids_param = ','.join(batch)

    update_url = f"{base_url}/tickets/update_many.json?ids={ids_param}"
    data = {
        "ticket": {
            "assignee_id": 123456789,  # Novo cessionário
            "comment": {
                "body": "Reatribuído ao novo membro da equipe.",
                "public": False
            }
        }
    }

    response = requests.put(update_url, json=data, auth=auth)

    if response.status_code == 200:
        print(f"Lote atualizado {i//100 + 1}: {len(batch)} tickets")
    else:
        print(f"Erro no lote {i//100 + 1}: {response.text}")

    # Seja gentil com a API
    time.sleep(1)

Tratamento de erros e solução de problemas

Mesmo com um planejamento cuidadoso, as chamadas de API às vezes falham. Saber como interpretar as respostas de erro economizará tempo de depuração.

Códigos de erro HTTP comuns

Código	Significado	O que verificar
401	Não autorizado	Seu token ou e-mail está incorreto
404	Não encontrado	O ID do ticket não existe
422	Entidade não processável	Valor de campo inválido ou dados obrigatórios ausentes
429	Muitas solicitações	Você atingiu o limite de taxa

Tratando erros de validação

Um erro 422 geralmente significa que seus dados não correspondem ao que o Zendesk espera. O corpo da resposta contém detalhes:

{
  "error": "RecordInvalid",
  "description": "Record validation errors",
  "details": {
    "custom_fields": [
      {
        "description": "Field value cannot be blank",
        "error": "BlankValue"
      }
    ]
  }
}

Dicas de depuração

1. Habilite o registro detalhado no seu cliente HTTP para ver os detalhes completos da solicitação e resposta
2. Verifique os logs da API do Zendesk no Admin Center para solicitações com falha
3. Valide seu JSON antes de enviar. Uma vírgula à direita ou uma aspa ausente causarão erros.
4. Teste no Postman ou com cURL antes de escrever o código para isolar problemas de sintaxe

Quando entrar em contato com o suporte do Zendesk

A maioria dos problemas de API pode ser resolvida verificando a documentação e verificando o formato da sua solicitação. Entre em contato com o suporte do Zendesk se você encontrar:

• Erros 500 consistentes (problemas do lado do servidor)
• Limite de taxa inesperado, apesar de estar abaixo dos limites documentados
• Comportamento que contradiz a documentação oficial da API

Simplificando as atualizações de tickets com o eesel AI

Construir e manter integrações de API leva tempo e recursos de engenharia. Para equipes que precisam de gerenciamento automatizado de tickets sem escrever código, o eesel AI oferece uma abordagem diferente.

Por que as equipes escolhem a automação em vez de scripts manuais

Scripts de API personalizados funcionam bem para tarefas específicas e únicas. Mas eles se tornam um fardo quando você precisa:

• Atualizar continuamente os tickets com base nas condições variáveis
• Manter as integrações à medida que seu fluxo de trabalho evolui
• Treinar os membros da equipe para usar e modificar o código
• Escalar a automação em vários tipos de tickets e canais

Como o eesel AI se conecta ao Zendesk

Em vez de escrever chamadas de API, você convida o eesel AI para sua equipe como um agente de IA. Ele aprende com seus tickets anteriores, artigos da central de ajuda e macros e, em seguida, lida com atualizações de rotina automaticamente.

Veja como isso se parece na prática:

• Marcação automática: o eesel lê os tickets recebidos e aplica tags relevantes com base no conteúdo
• Roteamento inteligente: os tickets são atribuídos à equipe ou agente certo sem triagem manual
• Atualizações de status: o eesel pode alterar o status do ticket quando condições específicas são atendidas
• Tratamento de escalonamento: problemas complexos são automaticamente escalados para agentes humanos com contexto

Casos de uso para gerenciamento automatizado de tickets

As equipes usam a integração do Zendesk do eesel AI para cenários que, de outra forma, exigiriam scripts de API complexos:

• Roteamento de tickets de clientes VIP para agentes seniores imediatamente
• Fechamento automático de spam ou mensagens de "obrigado"
• Atualização de campos personalizados com base na análise do conteúdo do ticket
• Mesclagem de tickets duplicados do mesmo cliente

Começando com o eesel AI

Se sua equipe está gastando mais tempo mantendo scripts de API do que se beneficiando da automação, o preço do eesel AI oferece uma alternativa sem código. Os planos começam em US$ 239 por mês quando cobrados anualmente, com um teste gratuito de 7 dias para testar como ele se encaixa no seu fluxo de trabalho.

A diferença está na abordagem. Em vez de escrever código para atualizar os tickets, você descreve o que deseja em inglês simples. O eesel aprende seu negócio, começa com orientação e sobe de nível para trabalhar de forma autônoma à medida que se prova.