API de Solicitações do Zendesk: Um guia completo para usuários finais (2026)

Escrito por

Stevia Putri

Última edição March 2, 2026

Verificado por especialista

Imagem do banner para API de Solicitações do Zendesk: Um guia completo para usuários finais (2026)

Quando você está construindo um portal do cliente ou uma integração de autoatendimento, você precisa de uma maneira para que os usuários finais criem e visualizem tickets sem dar-lhes acesso total de administrador. A API de Solicitações do Zendesk foi projetada exatamente para esse propósito.

Comparação dos níveis de acesso à API para decisões de segurança do desenvolvedor

A API de Solicitações fornece a perspectiva de um usuário final sobre os tickets. Os usuários podem criar solicitações, visualizar seu histórico de tickets e adicionar comentários, tudo isso vendo apenas informações públicas. É a alternativa segura e de acesso limitado à API de Tickets completa.

Se você está procurando automatizar o suporte sem construir integrações de API personalizadas, ferramentas como o eesel AI podem lidar com todo o espectro de automação de suporte, desde o roteamento de tickets até respostas baseadas em IA. O eesel se integra diretamente ao Zendesk e aprende com seus tickets e documentação existentes. Mas se você precisar de acesso direto à API para integrações personalizadas, este guia irá orientá-lo por tudo o que você precisa saber.

O que você vai precisar

Antes de começar a fazer chamadas de API, certifique-se de que você tem:

Uma conta do Zendesk com as permissões apropriadas (acesso de administrador para configurar tokens de API)
Token de API ou credenciais OAuth (vamos cobrir como gerar estes)
Familiaridade básica com APIs REST (você deve entender as solicitações GET, POST e PUT)
Um ambiente de desenvolvimento (cURL, Python ou Node.js funcionarão bem)

Entendendo a API de Solicitações

O que é uma solicitação?

No Zendesk, uma solicitação é a perspectiva de um usuário final sobre um ticket. Enquanto os agentes veem o ticket completo com notas internas, campos personalizados e comentários privados, os usuários finais veem apenas comentários públicos e um conjunto limitado de campos.

Veja como o formato JSON se parece para uma solicitação:

{
  "id": 35436,
  "subject": "Help, my printer is on fire!",
  "description": "The fire is very colorful.",
  "status": "open",
  "priority": "normal",
  "type": "problem",
  "requester_id": 1462,
  "created_at": "2009-07-20T22:55:29Z",
  "updated_at": "2011-05-05T10:38:52Z"
}

As propriedades principais incluem:

subject (obrigatório) - A linha de assunto visível para o usuário final
description - Primeiro comentário somente leitura na solicitação
status - novo, aberto, pendente, em espera, resolvido ou fechado
priority - baixa, normal, alta ou urgente
type - pergunta, incidente, problema ou tarefa

Fonte: Referência da API de Solicitações do Zendesk

API de Solicitações vs API de Tickets: Qual você deve usar?

Esta é uma decisão crítica que afetará como sua integração se comporta. Aqui está o detalhamento:

Fator	API de Solicitações	API de Tickets
Quem pode usar	Usuários finais, administradores (como usuários finais)	Apenas agentes e administradores
Visibilidade	Apenas comentários públicos	Acesso total ao ticket
Agent Copilot	Funciona corretamente	Pode não ser acionado
Caso de uso	Portais do cliente, autoatendimento	Ferramentas internas, funções de administrador

A questão do Agent Copilot é importante. Quando você cria um ticket através da API de Tickets em nome de um usuário final, o Zendesk interpreta que ele foi criado por um agente. Isso significa que o Agent Copilot não será acionado porque está esperando por uma resposta do cliente que nunca chega. Usar a API de Solicitações garante que os tickets se comportem exatamente como aqueles criados por e-mail ou mensagens.

Fonte: Nota Interna - Solicitações de API e Agent Copilot

Métodos de autenticação

Autenticação do usuário final

Os usuários finais podem se autenticar usando suas próprias credenciais. Ao usar o endpoint de Solicitações, administradores e agentes são tratados como usuários finais, então eles veem a mesma visualização limitada.

Autenticação com Token de API:

curl https://your-subdomain.zendesk.com/api/v2/requests.json \
  -u user@example.com/token:your_api_token_here

Nota importante: Um usuário final não poderá visualizar suas solicitações se tiver adicionado uma identidade de e-mail após 17 de setembro de 2017 e não tiver verificado o endereço de e-mail. A API retorna uma resposta 403 neste caso.

Fonte: Referência da API de Solicitações do Zendesk

Fazendo solicitações em nome de usuários finais (personificação de administrador)

Às vezes, você precisará que um administrador crie tickets para usuários finais. Isso requer OAuth com um escopo de personificação.

Passo 1: Crie um cliente OAuth no Admin Center (Aplicativos e integrações > APIs > Clientes OAuth)

Passo 2: Solicite um token de acesso com o escopo "impersonate" (personificar):

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
  -H "Content-Type: application/json" \
  -d '{
    "token": {
      "client_id": "your_client_id",
      "scopes": ["impersonate", "write"]
    }
  }' \
  -X POST -v -u {email_address}/token:{api_token}

Passo 3: Inclua o cabeçalho X-On-Behalf-Of em suas solicitações:

curl https://z3napi.zendesk.com/api/v2/requests.json \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: customer@example.com" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "request": {
      "subject": "Help request",
      "comment": {"body": "I need assistance with my order"}
    }
  }'

Importante: O usuário final personificado deve ter um perfil de usuário existente. Caso contrário, a solicitação falhará com um erro invalid_token.

Fonte: Fazendo solicitações de API em nome de usuários finais

Solicitações anônimas

Se o seu administrador do Zendesk habilitou isso, você pode criar solicitações sem nenhuma autenticação. Isso é útil para formulários de contato públicos.

Requisitos:

As solicitações anônimas devem ser habilitadas no Admin Center
Inclua um objeto requester com pelo menos um nome

{
  "request": {
    "requester": {"name": "Anonymous customer"},
    "subject": "Help!",
    "comment": {"body": "My printer is on fire!"}
  }
}

Limites de taxa: As solicitações anônimas são limitadas a 5 por hora para contas de avaliação.

Fonte: Criando e gerenciando solicitações

Endpoints principais da API

Listar solicitações

Recupere todas as solicitações para o usuário autenticado:

GET /api/v2/requests

Parâmetros:

page - Paginação (suporta baseado em offset ou cursor)
per_page - Número de registros por página
sort_by - "updated_at" ou "created_at"
sort_order - "asc" ou "desc"

Criar uma solicitação

Crie um novo ticket da perspectiva de um usuário final:

POST /api/v2/requests

Campos obrigatórios:

subject - O assunto do ticket
comment - Objeto com body contendo a descrição

Campos opcionais:

requester - Para solicitações anônimas (objeto com nome, e-mail)
collaborators - Array de IDs de usuário ou e-mails para CC
custom_fields - Array de valores de campos personalizados
tags - Array de tags para aplicar

Atualizar uma solicitação

Adicione comentários ou marque uma solicitação como resolvida:

PUT /api/v2/requests/{id}

Propriedades graváveis:

comment - Adicione um novo comentário
solved - Defina como true para marcar como resolvido (somente se can_be_solved_by_me for true)
additional_collaborators - Adicione CCs à solicitação

Listar comentários

Visualize o histórico da conversa:

GET /api/v2/requests/{request_id}/comments

Por padrão, os comentários são classificados por data de criação em ordem crescente.

Fonte: Referência da API de Solicitações do Zendesk

Exemplos de código

Criando uma solicitação com cURL

#!/bin/bash

SUBDOMAIN="your-subdomain"
EMAIL="admin@example.com"
TOKEN="your_api_token"

curl "https://${SUBDOMAIN}.zendesk.com/api/v2/requests.json" \
  -u "${EMAIL}/token:${TOKEN}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "request": {
      "subject": "Order status inquiry",
      "comment": {
        "body": "I placed an order last week and would like to check the status. My order number is #12345."
      },
      "collaborators": ["spouse@example.com"]
    }
  }'

Criando uma solicitação com Python

import requests
import json

subdomain = "your-subdomain"
email = "admin@example.com"
api_token = "your_api_token"

url = f"https://{subdomain}.zendesk.com/api/v2/requests.json"

payload = {
    "request": {
        "subject": "Technical support needed",
        "comment": {
            "body": "I'm having trouble logging into my account. Can you help?"
        }
    }
}

auth = (f"{email}/token", api_token)
headers = {"Content-Type": "application/json"}

try:
    response = requests.post(url, json=payload, auth=auth, headers=headers)
    response.raise_for_status()

    data = response.json()
    print(f"Request created successfully!")
    print(f"Ticket ID: {data['request']['id']}")
    print(f"Status: {data['request']['status']}")

except requests.exceptions.HTTPError as err:
    print(f"HTTP Error: {err}")
    print(f"Response: {response.text}")
except Exception as err:
    print(f"Error: {err}")

Criando uma solicitação com Node.js

const axios = require('axios');

const config = {
  subdomain: 'your-subdomain',
  email: 'admin@example.com',
  apiToken: 'your_api_token'
};

async function createRequest() {
  const url = `https://${config.subdomain}.zendesk.com/api/v2/requests.json`;

  const payload = {
    request: {
      subject: 'Billing question',
      comment: {
        body: 'I was charged twice for my subscription this month. Please help resolve this.'
      }
    }
  };

  try {
    const response = await axios.post(url, payload, {
      auth: {
        username: `${config.email}/token`,
        password: config.apiToken
      },
      headers: {
        'Content-Type': 'application/json'
      }
    });

    console.log('Request created successfully!');
    console.log(`Ticket ID: ${response.data.request.id}`);
    console.log(`Status: ${response.data.request.status}`);

  } catch (error) {
    console.error('Error creating request:', error.response?.data || error.message);
  }
}

createRequest();

Erros comuns e solução de problemas

403 Proibido (Forbidden)

Este é o erro mais comum ao trabalhar com a API de Solicitações. Causas comuns:

E-mail não verificado: O usuário final adicionou um e-mail após 17 de setembro de 2017, sem verificá-lo
Permissões insuficientes: Tentando acessar endpoints não permitidos para usuários finais
Escopo de personificação ausente: Tentando fazer solicitações em nome de usuários sem o escopo OAuth adequado

Solução: Verifique o endereço de e-mail do usuário no administrador do Zendesk ou certifique-se de que está usando o método de autenticação correto para seu caso de uso.

401 Não autorizado (Unauthorized)

Token de API ou credenciais OAuth inválidas
O token expirou (os tokens OAuth têm vida útil limitada)
A conta do usuário está suspensa ou excluída

Solução: Verifique novamente suas credenciais e regenere os tokens, se necessário.

429 Limite de taxa excedido (Rate Limit Exceeded)

API padrão: 700 solicitações por minuto
Solicitações anônimas: 5 por hora (contas de avaliação)

Solução: Implemente o backoff exponencial em seu código. Quando você recebe um 429, espere antes de tentar novamente:

import time

def make_request_with_retry(url, payload, auth, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, auth=auth)
            response.raise_for_status()
            return response
        except requests.exceptions.HTTPError as err:
            if response.status_code == 429:
                wait_time = (2 ** attempt)  # Exponential backoff
                print(f"Rate limited. Waiting {wait_time} seconds...")
                time.sleep(wait_time)
            else:
                raise
    raise Exception("Max retries exceeded")

Agent Copilot não está sendo acionado

Se você estiver usando o Agent Copilot do Zendesk e ele não estiver sugerindo respostas para tickets criados via API, você provavelmente está usando a API de Tickets em vez da API de Solicitações.

Solução: Mude para a API de Solicitações (POST /api/v2/requests.json) em vez da API de Tickets (POST /api/v2/tickets.json).

Fonte: Nota Interna - Solicitações de API e Agent Copilot

Melhores práticas

Use a API de Solicitações para integrações voltadas para o usuário final

Se você estiver construindo um portal do cliente, widget de autoatendimento ou qualquer interface onde os usuários finais criem tickets, sempre use a API de Solicitações. Isso garante:

Comportamento adequado do Agent Copilot
Cálculos corretos do tempo da primeira resposta
Ciclo de vida consistente do ticket com tickets criados por e-mail

Lide com os limites de taxa com elegância

Sempre implemente a lógica de repetição com backoff exponencial. A API do Zendesk é compartilhada entre todos os clientes, e o polling agressivo pode fazer com que sua integração tenha sua taxa limitada ou seja bloqueada.

Valide o status de verificação de e-mail

Antes de permitir que os usuários visualizem suas solicitações, verifique se o e-mail deles está confirmado. Você pode verificar isso através da API de Usuários e solicitar que eles verifiquem, se necessário.

Armazene as credenciais com segurança

Não codifique tokens de API em seu código frontend nem os envie para o controle de versão. Use variáveis de ambiente ou sistemas de gerenciamento de segredos seguros.

Considere alternativas sem código

Construir e manter integrações de API exige recursos de desenvolvimento significativos. Se seu objetivo é automatizar as respostas de suporte em vez de construir portais personalizados, considere ferramentas como o eesel AI que se integram diretamente ao Zendesk e fornecem automação baseada em IA sem escrever código. O eesel AI não requer configuração complexa, você simplesmente o convida para sua equipe e ele aprende seu negócio em minutos.

eesel AI instructions panel showing natural language configuration for setting up AI agent behavior and escalation rules.

Nós oferecemos:

Agente de IA que lida com o suporte de linha de frente de forma autônoma
Copiloto de IA que rascunha respostas para os agentes revisarem
Triagem de IA que marca, encaminha e prioriza tickets automaticamente
Integração com um clique com o Zendesk (nenhum desenvolvimento de API necessário)

Fonte: Produtos eesel AI

Comece a construir com a API de Solicitações do Zendesk

A API de Solicitações do Zendesk oferece uma maneira segura de permitir que os usuários finais interajam com seu sistema de suporte. Ao entender a diferença entre as APIs de Solicitações e Tickets, implementar a autenticação adequada e seguir as melhores práticas, você pode construir integrações de autoatendimento robustas.

Principais conclusões:

Use a API de Solicitações para integrações voltadas para o usuário final
Implemente OAuth com escopo de personificação quando os administradores precisarem agir em nome dos usuários
Lide com limites de taxa e erros com elegância
Teste completamente antes de implantar em produção

Para mais detalhes, confira a documentação oficial da API de Solicitações do Zendesk.

Se você está procurando automatizar o suporte sem a sobrecarga de desenvolvimento, explore como o eesel AI pode ajudar. Nossos agentes de IA se integram diretamente ao Zendesk, aprendem com sua documentação existente e tickets anteriores e podem lidar com até 81% do suporte de linha de frente de forma autônoma.

Perguntas Frequentes

Os usuários finais podem usar a API de Solicitações do Zendesk para visualizar todos os tickets no sistema?

Não. Os usuários finais só podem visualizar as solicitações que criaram ou nas quais estão em cópia (CC). Eles não podem ver os tickets de outros usuários ou comentários internos. Este é um recurso de segurança integrado à API.

Qual é a diferença entre a autenticação de usuário final da API de Solicitações do Zendesk e a autenticação de administrador?

Os usuários finais se autenticam com suas próprias credenciais e veem uma visualização limitada dos tickets. Os administradores podem usar os mesmos endpoints, mas são tratados como usuários finais (vendo apenas comentários públicos). Para acessar dados completos do ticket ou agir em nome dos usuários, os administradores precisam da API de Tickets com as permissões apropriadas.

Como lidar com os limites de taxa de usuário final da API de Solicitações do Zendesk em meu aplicativo?

Implemente o backoff exponencial quando receber um código de status 429. Comece com um pequeno atraso (1-2 segundos) e dobre-o a cada nova tentativa. Para aplicativos de alto volume, considere armazenar em cache as respostas e usar webhooks em vez de polling.

Posso usar os endpoints de usuário final da API de Solicitações do Zendesk para atualizar campos de ticket como prioridade ou responsável?

Não. Os usuários finais só podem adicionar comentários, marcar solicitações como resolvidas (em certas condições) e gerenciar colaboradores. Eles não podem modificar campos internos como prioridade, responsável ou campos personalizados que não são expostos aos usuários finais.

Por que o Agent Copilot não está funcionando com os tickets que crio por meio dos endpoints de usuário final da API de Solicitações do Zendesk?

Se o Agent Copilot não estiver sendo acionado, você provavelmente está usando a API de Tickets em vez da API de Solicitações. A API de Tickets cria tickets que parecem ser de agentes, o que impede que o Copilot seja acionado. Mude para POST /api/v2/requests.json para garantir o comportamento adequado.

Existe uma maneira de automatizar o suporte sem construir integrações de API personalizadas?

Sim. Ferramentas como o eesel AI se integram diretamente ao Zendesk e fornecem automação baseada em IA sem exigir desenvolvimento de API. Você pode implantar agentes de IA que aprendem com sua documentação existente e lidam com o suporte de linha de frente de forma autônoma.

Automate your Zendesk with AI agents

Teste grátis Agendar demo

Share this article

Article by

Stevia Putri

Stevia Putri is a marketing generalist at eesel AI, where she helps turn powerful AI tools into stories that resonate. She’s driven by curiosity, clarity, and the human side of technology.