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.

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:

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.

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.