{
"title": "API de solicitação de aplicativos Zendesk: Um guia completo para desenvolvedores para 2026",
"slug": "zendesk-app-request-api",
"locale": "pt",
"date": "2026-03-02",
"updated": "2026-03-02",
"template": "default",
"excerpt": "Um guia abrangente para fazer solicitações de API de aplicativos Zendesk, incluindo o método ZAF request(), opções de autenticação e exemplos de código práticos.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk API",
"ZAF",
"app development",
"API requests",
"customer support"
],
"readTime": 10,
"author": 16,
"reviewer": 14,
"seo": {
"title": "API de solicitação de aplicativos Zendesk: Um guia completo para desenvolvedores para 2026",
"description": "Um guia abrangente para fazer solicitações de API de aplicativos Zendesk, incluindo o método ZAF request(), opções de autenticação e exemplos de código práticos.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-4483d692-7065-4621-b1b0-bb0853f480f2"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-4483d692-7065-4621-b1b0-bb0853f480f2",
"coverImageAlt": "Imagem do banner para API de solicitação de aplicativos Zendesk: Um guia completo para desenvolvedores para 2026",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas Frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Para que serve a API de solicitação de aplicativos Zendesk?",
"answer": "A API de solicitação de aplicativos Zendesk se refere a duas coisas: o método request() do Cliente ZAF para fazer chamadas HTTP de dentro dos aplicativos Zendesk e o endpoint da API de Solicitações para que os usuários finais criem e visualizem tickets. Ambos permitem a interação programática com os dados do Zendesk."
},
{
"question": "Como autentico as chamadas da API de solicitação de aplicativos Zendesk?",
"answer": "A autenticação depende do seu caso de uso. Para chamadas de dentro de um aplicativo Zendesk, o cliente ZAF usa cookies do navegador automaticamente. Para chamadas de API externas, use a autenticação básica com seu formato email/token:api_token, codificado em base64 com um prefixo 'Basic '."
},
{
"question": "Posso usar a API de solicitação de aplicativos Zendesk para enviar arquivos?",
"answer": "O método request() do ZAF não oferece suporte ao envio de arquivos binários. Para anexos de arquivos, você precisa usar uma solução alternativa, como codificar arquivos como base64, usar um serviço de upload separado ou implementar o tratamento do lado do servidor."
},
{
"question": "Quais são os limites de taxa para a API de solicitação de aplicativos Zendesk?",
"answer": "O Zendesk aplica dois limites de taxa: um limite de taxa de aplicativos (normalmente 100 solicitações por minuto por aplicativo) e um limite de taxa de conta (700 solicitações por minuto para a maioria dos endpoints). Exceder qualquer um retorna um status 429 com um cabeçalho Retry-After."
},
{
"question": "Como oculto as chaves de API no meu aplicativo Zendesk?",
"answer": "Use configurações seguras em seu manifest.json. Marque os parâmetros como 'secure': true, referencie-os com {{setting.param_name}} em seu código e configure-os durante a instalação do aplicativo. Os valores reais são armazenados no lado do servidor e nunca expostos no navegador."
},
{
"question": "Qual é a diferença entre a API de Solicitações e a API de Tickets no Zendesk?",
"answer": "A API de Solicitações foi projetada para usuários finais e mostra apenas comentários públicos e campos acessíveis. A API de Tickets é para agentes e administradores com acesso total. Use a API de Solicitações para recursos voltados para o cliente e a API de Tickets para ferramentas internas."
},
{
"question": "Posso fazer chamadas de API diretas sem usar o proxy ZAF?",
"answer": "Sim, definindo cors: true em suas opções de solicitação. No entanto, a API de destino deve oferecer suporte a cabeçalhos CORS. A maioria dos aplicativos de produção usa o proxy para confiabilidade, pois funciona com qualquer API."
}
],
"supportLink": null
}
}
---
Se você estiver criando um aplicativo Zendesk, eventualmente precisará fazer solicitações de API. Talvez você esteja extraindo dados de um serviço externo, criando tickets programaticamente ou integrando-se a outra plataforma. A API de solicitação de aplicativos Zendesk oferece várias maneiras de fazer isso, mas a documentação está espalhada por várias páginas e as opções de autenticação podem ser confusas.
Este guia consolida tudo o que você precisa saber sobre como fazer solicitações de API de aplicativos Zendesk. Abordaremos o método `request()` do Cliente ZAF, o endpoint da API de Solicitações, estratégias de autenticação e armadilhas comuns em que os desenvolvedores se deparam. Se você estiver procurando uma maneira mais simples de automatizar os fluxos de trabalho do Zendesk sem escrever código personalizado, também abordaremos como o [eesel AI se integra ao Zendesk](https://www.eesel.ai/integration/zendesk-ai) para lidar com o gerenciamento de tickets por meio de agentes de IA.
## O que é a API de solicitação de aplicativos Zendesk?
Quando os desenvolvedores pesquisam por "API de solicitação de aplicativos Zendesk", geralmente estão procurando uma de duas coisas:
1. **O método `request()` do Cliente ZAF** - Uma função JavaScript que permite que seu aplicativo Zendesk faça solicitações HTTP para APIs externas ou para a própria API do Zendesk
2. **O endpoint da API de Solicitações** - Uma API REST que permite que os usuários finais criem e visualizem tickets de sua perspectiva
O método `request()` do ZAF é o que você usa ao criar aplicativos que são executados dentro do Zendesk. Ele lida com a autenticação, evita restrições de domínio cruzado e gerencia a complexidade de fazer chamadas de API seguras de um ambiente de navegador. A API de Solicitações é o que você chama quando deseja permitir que os clientes enviem tickets sem dar a eles acesso total de agente.
Vamos detalhar como cada um funciona e quando usá-los.
## Entendendo o método `request()` do Cliente ZAF
O [Zendesk Apps Framework (ZAF)](https://developer.zendesk.com/api-reference/apps/introduction/) fornece um cliente JavaScript que é executado dentro do seu aplicativo. O método `client.request()` é sua porta de entrada para fazer solicitações HTTP de dentro do ambiente Zendesk.
Aqui está o porquê de ele existir: os navegadores bloqueiam solicitações de origem cruzada por motivos de segurança. Se seu aplicativo tentar chamar uma API externa diretamente, você receberá erros CORS. O ZAF resolve isso roteando suas solicitações por meio de um servidor proxy Zendesk. O proxy faz a solicitação real e retorna a resposta para seu aplicativo.
O método `request()` retorna uma Promise JavaScript, então você lida com as respostas com `.then()` ou `async/await`:
```javascript
const client = ZAFClient.init();
client.request({
url: 'https://api.example.com/data',
type: 'GET',
headers: {
'Authorization': 'Bearer {{setting.api_token}}'
}
}).then(data => {
console.log('Response:', data);
}).catch(error => {
console.error('Error:', error);
});
Principais capacidades do método request():
- Roteamento do servidor proxy - Evita CORS fazendo solicitações no lado do servidor
- Configurações seguras - Oculta as chaves de API das ferramentas de desenvolvimento do navegador usando espaços reservados no manifest.json
- Gerenciamento de token OAuth - Lida com fluxos OAuth de terceiros sem expor tokens
- Codificação JWT - Assina solicitações com JSON Web Tokens para maior segurança
Uma limitação a ser observada: o método request() não oferece suporte ao envio de arquivos binários. Se você precisar anexar arquivos, precisará usar uma abordagem diferente (mais sobre isso mais tarde).
Métodos de autenticação para solicitações de aplicativos Zendesk
A autenticação é onde a maioria dos desenvolvedores fica presa. O Zendesk oferece vários métodos de autenticação e a escolha do método certo depende do que você está tentando fazer.
Autenticação básica com tokens de API
A abordagem mais simples para chamar a própria API do Zendesk. Formate suas credenciais como {email}/token:{api_token}, codifique-as em base64 e inclua-as no cabeçalho Authorization com o prefixo "Basic ":
const credentials = btoa('agent@company.com/token:abc123xyz');
const authHeader = `Basic ${credentials}`;
Erro comum: esquecer o prefixo "Basic ". O cabeçalho deve começar com "Basic " seguido por um espaço e, em seguida, a string codificada em base64. Muitos desenvolvedores codificam as credenciais corretamente, mas omitem o prefixo, resultando em erros 401 Não Autorizado.
Configurações seguras
Se você estiver chamando uma API de terceiros, não deseja expor as chaves de API em seu JavaScript, onde qualquer pessoa pode vê-las no console do navegador. As configurações seguras resolvem isso armazenando dados confidenciais no lado do servidor.
No seu manifest.json:
{
"parameters": [
{
"name": "api_token",
"type": "text",
"secure": true
}
],
"domainWhitelist": ["api.example.com"]
}
Referencie a configuração em seu código com chaves duplas:
headers: {
'Authorization': 'Bearer {{setting.api_token}}'
}
O valor real do token é armazenado nos servidores do Zendesk e injetado no momento da solicitação. Os usuários o configuram durante a instalação do aplicativo e ele nunca é exposto no navegador.
OAuth 2.0
Para integrações com serviços como Salesforce, Slack ou Google, o OAuth é o padrão. O ZAF oferece suporte ao fluxo de código de autorização:
- Seu aplicativo redireciona o usuário para o provedor OAuth
- O usuário autoriza o acesso
- O provedor redireciona de volta com um código de autorização
- Seu aplicativo troca o código por um token de acesso
- O ZAF armazena o token com segurança e o atualiza automaticamente
A configuração exige registrar seu aplicativo no provedor OAuth e configurar os URLs de redirecionamento. Uma vez configurado, o gerenciamento de token é tratado automaticamente.
Tokens JWT
Para solicitações assinadas, o ZAF oferece suporte à codificação JWT com o algoritmo HS256. Você fornece uma chave secreta e o ZAF gera tokens com declarações como tempo de expiração. Isso é útil quando você precisa verificar se as solicitações vieram do seu aplicativo Zendesk e não foram adulteradas.
Autenticação de cookie do navegador
Ao chamar a API do Zendesk de dentro do seu aplicativo, você pode ignorar a autenticação explícita completamente. O cliente ZAF usa automaticamente o cookie de sessão do Zendesk do navegador para autenticar as solicitações. Isso só funciona para endpoints da API do Zendesk, não para APIs externas.
Qual método de autenticação você deve usar?
| Cenário | Método Recomendado |
|---|---|
| Chamando a API do Zendesk do seu aplicativo | Cookies do navegador (automático) |
| Chamando a API do Zendesk de código externo | Autenticação básica com token de API |
| Chamando APIs de terceiros | Configurações seguras ou OAuth |
| Precisa de solicitações assinadas/verificadas | JWT |
Para obter mais detalhes sobre como trabalhar com as APIs do Zendesk, consulte nosso guia sobre a API de tickets do Zendesk.
Fazendo solicitações para APIs de terceiros
Por padrão, o ZAF roteia as solicitações por meio de seu servidor proxy. Isso é controlado pela opção cors:
// Comportamento padrão - usa proxy (cors: false)
client.request({
url: 'https://api.example.com/data',
type: 'GET'
});
// Solicitação direta - requer suporte CORS na API
client.request({
url: 'https://api.example.com/data',
type: 'GET',
cors: true
});
A abordagem de proxy funciona com qualquer API, mas adiciona latência. As solicitações diretas são mais rápidas, mas exigem que a API ofereça suporte a cabeçalhos CORS. A maioria dos aplicativos de produção usa o proxy para confiabilidade.
Aqui está um exemplo completo e funcional que busca dados de uma API externa usando configurações seguras:
const client = ZAFClient.init();
async function fetchCustomerData(customerId) {
try {
const response = await client.request({
url: `https://api.example.com/customers/${customerId}`,
type: 'GET',
headers: {
'Authorization': 'Bearer {{setting.api_key}}',
'Content-Type': 'application/json'
}
});
return response;
} catch (error) {
console.error('Failed to fetch customer:', error);
throw error;
}
}
O tratamento de erros é importante. A Promise é rejeitada se a solicitação falhar, portanto, sempre envolva as chamadas em try/catch ou use .catch().
Trabalhando com a API de Solicitações do Zendesk
A API de Solicitações é separada do método request() do ZAF. É um endpoint de API REST que permite que os usuários finais (clientes) interajam com os tickets de sua perspectiva.
Principais diferenças da API de Tickets:
- Visualização do usuário final - Vê apenas comentários públicos e campos aos quais o usuário tem acesso
- Suporte anônimo - Pode ser chamado sem autenticação (com limite de taxa)
- Permissões simplificadas - Não há necessidade de credenciais de agente
Endpoints comuns:
| Endpoint | Método | Descrição |
|---|---|---|
/api/v2/requests | GET | Lista as solicitações para o usuário autenticado |
/api/v2/requests | POST | Cria uma nova solicitação (ticket) |
/api/v2/requests/{id} | GET | Obtém detalhes de uma solicitação específica |
/api/v2/requests/{id} | PUT | Atualiza uma solicitação existente |
Criando uma solicitação:
curl https://company.zendesk.com/api/v2/requests.json \
-d '{"request": {"subject": "Help needed", "comment": {"body": "I have a question"}}}' \
-H "Content-Type: application/json" \
-X POST
Para solicitações autenticadas, inclua o cabeçalho Authorization. Para solicitações anônimas (como um formulário de contato), omita a autenticação. As solicitações anônimas são limitadas a 5 por hora para contas de avaliação.
Se você estiver criando integrações que criam tickets, também poderá achar nosso guia sobre como criar tickets do Zendesk usando a API útil.
Erros comuns e solução de problemas
Mesmo com uma boa documentação, as coisas dão errado. Aqui estão os problemas mais comuns que os desenvolvedores encontram:
401 Não Autorizado
O cabeçalho de autenticação está mal formado. Verifique novamente:
- O prefixo "Basic " está presente (com um espaço depois dele)
- As credenciais são codificadas em base64 corretamente
- O formato do e-mail é
{email}/token:{api_token}(observe o sufixo "/token") - O token de API está ativo e não expirou
Erros CORS
Você está tentando fazer uma solicitação direta para uma API que não oferece suporte a CORS. Ative o proxy omitindo cors: true ou peça ao provedor da API para adicionar cabeçalhos CORS.
429 Limite de Taxa Excedido
O Zendesk tem vários limites de taxa. Os aplicativos têm seu próprio limite (geralmente 100 solicitações por minuto) e sua conta tem um limite separado (700 solicitações por minuto para a maioria dos endpoints). Se você atingir um 429, verifique o cabeçalho Retry-After e espere antes de tentar novamente. Consulte a documentação oficial de limites de taxa para obter detalhes completos.
422 Entidade Não Processável
Seu JSON está mal formado. Causas comuns:
- Aspas ausentes em torno dos nomes das propriedades
- Vírgulas à direita em objetos
- Aspas simples em vez de aspas duplas
- Sequências de escape inválidas
Problemas de envio de arquivos
O método request() do ZAF não oferece suporte a uploads binários. As soluções alternativas incluem:
- Usar um servidor separado para lidar com uploads
- Codificar arquivos como base64 e decodificar no lado do servidor
- Usar uma biblioteca como RestSharp para tratamento binário
Para obter mais exemplos de integração, consulte nosso guia sobre como conectar o Zendesk ao Slack usando aplicativos de terceiros.
Criando integrações de aplicativos Zendesk sem código
As integrações de API personalizadas levam tempo para serem criadas e mantidas. 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 os fluxos de trabalho de tickets em vez de criar um aplicativo personalizado, considere se você realmente precisa escrever código. Nosso agente de IA para Zendesk lida com a criação, roteamento e respostas de tickets sem nenhum trabalho de desenvolvimento.
Aqui está a diferença: com a abordagem da API, você está escrevendo scripts para mover tickets que os humanos ainda precisarão responder. Com um agente de IA, você está treinando um sistema para entender seus negócios e lidar com todo o ciclo de vida do ticket. 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 redigindo 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 chamadas de API, isso geralmente oferece resultados mais rápidos do que o desenvolvimento personalizado.
Compartilhe esta postagem
Article by
