Gerenciamento de conteúdo da API Zendesk Guide: Um guia completo para desenvolvedores
Stevia Putri
Última edição February 25, 2026
Gerenciar o conteúdo da central de ajuda em escala se torna tedioso quando você está fazendo isso manualmente. Seja migrando artigos de outra plataforma, sincronizando ativos de sua equipe de marketing ou organizando conteúdo em várias marcas, a API Zendesk Guide oferece controle programático sobre sua base de conhecimento.
Este guia orienta você por tudo o que você precisa saber sobre o gerenciamento de conteúdo da API Zendesk Guide. Abordaremos autenticação, endpoints principais, padrões de implementação práticos e quando faz sentido usar a API versus alternativas como eesel AI.
O que você vai precisar
Antes de mergulhar, certifique-se de que você tem:
- Uma conta Zendesk com o Guide habilitado (plano Suite Team ou superior)
- Acesso de administrador para gerar tokens de API
- Familiaridade básica com APIs REST e JSON
- Seu cliente HTTP preferido (cURL, Postman ou uma linguagem de programação como Python)
Entendendo a autenticação da API Zendesk Guide
A API Zendesk Guide usa os mesmos padrões de autenticação que outras APIs Zendesk. Aqui está o que você precisa saber.
Autenticação de token de API (recomendado)
Os tokens de API são a maneira mais simples de autenticar. Você os gerará no Admin Center em Aplicativos e integrações > APIs > API Zendesk.
Detalhes importantes:
- Formate suas credenciais como
{email_address}/token:{api_token} - Codifique em Base64 a string inteira para o cabeçalho de Autorização
- Você pode ter até 256 tokens ativos (2048 para contas legadas)
- Os tokens podem se passar por qualquer usuário, incluindo administradores, portanto, mantenha-os seguros
Exemplo de solicitação cURL:
curl https://{subdomain}.zendesk.com/api/v2/guide/medias \
-v -u {email_address}/token:{api_token}
OAuth para aplicativos multi-cliente
Se você estiver criando uma integração que será distribuída para vários clientes Zendesk, você precisará usar o OAuth em vez de tokens de API. Os tokens de API regulares não funcionarão para aplicativos que precisam ser autenticados em diferentes instâncias do Zendesk.
Limites de taxa e SSL
A maioria dos endpoints permite 700 solicitações por minuto. Se você atingir o limite, você receberá um código de status 429. Todas as solicitações devem usar HTTPS com TLS 1.2 ou superior.
Endpoints principais de gerenciamento de conteúdo
A API Guide oferece vários endpoints para gerenciar diferentes tipos de conteúdo. Vamos detalhar os mais úteis.
API Guide Medias
A API Guide Medias lida com uploads de arquivos e gerenciamento de mídia para sua central de ajuda Zendesk. Isso é essencial quando você deseja adicionar programaticamente imagens ou anexos aos artigos.
O processo de upload de 3 etapas:
- Solicitar um URL de upload POST para
/api/v2/guide/medias/upload_urlcom tipo de conteúdo e tamanho do arquivo - Fazer upload do arquivo PUT o arquivo para o URL assinado retornado na etapa 1
- Criar o objeto de mídia POST para
/api/v2/guide/mediascom o ID de upload do ativo
Os arquivos podem ter até 20 MB. A API usa identificadores baseados em ULID, que são classificáveis ao contrário dos UUIDs tradicionais.
Exemplo em Python:
import requests
import base64
auth = base64.b64encode(f"{email}/token:{token}".encode()).decode()
headers = {"Authorization": f"Basic {auth}", "Content-Type": "application/json"}
upload_data = {"content_type": "image/png", "file_size": 12345}
response = requests.post(
f"https://{subdomain}.zendesk.com/api/v2/guide/medias/upload_url",
json=upload_data,
headers=headers
)
upload_url = response.json()["upload_url"]["url"]
asset_id = response.json()["upload_url"]["asset_upload_id"]
media_data = {"asset_upload_id": asset_id, "filename": "screenshot.png"}
media = requests.post(
f"https://{subdomain}.zendesk.com/api/v2/guide/medias",
json=media_data,
headers=headers
)
API Content Tags
As tags de conteúdo ajudam você a organizar artigos e posts. A API Content Tags permite que você crie, atualize e gerencie tags programaticamente.
Principais capacidades:
- Criar e gerenciar tags com solicitações POST/PUT/DELETE
- Operações em lote via
/api/v2/guide/content_tags/jobs(excluir ou mesclar tags) - Filtrar tags por prefixo de nome
- Classificar por ID ou nome em ordem crescente ou decrescente
As operações em lote são úteis para tarefas de limpeza, como mesclar tags duplicadas ou remover tags desatualizadas em toda a sua base de conhecimento.
API Dynamic Content
Se você oferece suporte a vários idiomas, a API Dynamic Content é essencial. Ela gerencia variantes de conteúdo localizadas usando espaços reservados como {{dc.password_reset_instructions}}.
Como funciona:
- Cada item de conteúdo dinâmico tem um local padrão e várias variantes
- As variantes contêm o texto traduzido real
- O Zendesk serve automaticamente a variante correta com base no local do usuário
- Retorna ao padrão se nenhuma variante correspondente existir
Observação: o conteúdo dinâmico requer um plano Professional ou superior.
API External Content Sources
A API External Content Sources permite a pesquisa federada, permitindo que você extraia resultados de sistemas externos para sua pesquisa na central de ajuda.
Casos de uso:
- Indexar conteúdo de um sistema de gerenciamento de aprendizado
- Incluir postagens de fóruns nos resultados da pesquisa
- Tornar os problemas do Jira pesquisáveis na central de ajuda
Isso requer permissões de gerente da Central de Ajuda e funciona com o rastreador do Zendesk para indexar conteúdo externo.
Implementação prática: Automatizando uploads de mídia
Vamos dar uma olhada em um cenário do mundo real. Sua equipe de marketing cria capturas de tela no Figma e as salva no Google Drive. Você deseja que elas sejam adicionadas automaticamente à sua galeria de mídia do Zendesk para que os redatores possam usá-las em artigos.
Aqui está uma implementação completa em Python:
import requests
import base64
import time
class ZendeskMediaUploader:
def __init__(self, subdomain, email, token):
self.subdomain = subdomain
self.base_url = f"https://{subdomain}.zendesk.com/api/v2"
self.auth = base64.b64encode(f"{email}/token:{token}".encode()).decode()
self.headers = {
"Authorization": f"Basic {self.auth}",
"Content-Type": "application/json"
}
def upload_file(self, file_path, content_type):
"""Upload a file to Zendesk media gallery."""
file_size = os.path.getsize(file_path)
filename = os.path.basename(file_path)
# Step 1: Get upload URL
upload_data = {"content_type": content_type, "file_size": file_size}
resp = requests.post(
f"{self.base_url}/guide/medias/upload_url",
json=upload_data,
headers=self.headers
)
resp.raise_for_status()
upload_info = resp.json()["upload_url"]
# Step 2: Upload file to signed URL
with open(file_path, "rb") as f:
put_headers = {
"Content-Disposition": upload_info["headers"]["Content-Disposition"],
"Content-Type": content_type,
"X-Amz-Server-Side-Encryption": "AES256"
}
put_resp = requests.put(upload_info["url"], data=f, headers=put_headers)
put_resp.raise_for_status()
# Step 3: Create media object
media_data = {
"asset_upload_id": upload_info["asset_upload_id"],
"filename": filename
}
media_resp = requests.post(
f"{self.base_url}/guide/medias",
json=media_data,
headers=self.headers
)
media_resp.raise_for_status()
return media_resp.json()["media"]
Dicas de tratamento de erros:
- 401 Não autorizado: Verifique seu token e formato de e-mail (deve incluir
/token) - 403 Proibido: Verifique se você tem permissões de gerente do Guide
- 409 Conflito: Tente novamente a solicitação (erro transitório)
- 429 Limite de taxa atingido: Implemente backoff exponencial
Quando usar a API Zendesk Guide vs. alternativas
A API nem sempre é a escolha certa. Veja como você decidirá.
Use a API quando:
- Você precisa migrar grandes quantidades de conteúdo de outra plataforma
- Você está construindo uma integração personalizada com suas ferramentas existentes
- Você deseja automatizar tarefas repetitivas (como marcação em massa)
- Você tem recursos de desenvolvedor disponíveis para manutenção contínua
Considere os recursos nativos do Zendesk quando:
- Você só precisa de uploads manuais ocasionais
- Sua equipe se sente confortável trabalhando na interface do Zendesk
- A pesquisa federada atende às suas necessidades de conteúdo externo sem código
Considere plataformas de integração quando:
- Você precisa de automação simples sem código personalizado
- Seu caso de uso se encaixa em gatilhos e ações padrão
- Você quer algo funcionando rapidamente sem tempo de desenvolvimento
Considere eesel AI quando:
Você pode querer dar uma olhada no eesel AI se seu objetivo é tornar sua base de conhecimento do Zendesk mais inteligente sem construir integrações personalizadas. Em vez de escrever scripts para sincronizar conteúdo, o eesel se conecta diretamente ao Zendesk, Confluence, Google Docs e outras fontes.
Aqui está a diferença: a API Guide permite que você mova o conteúdo para o Zendesk programaticamente. O eesel AI indexa seu conteúdo onde ele está e o torna acessível à sua equipe de suporte por meio de um Agente de IA que funciona dentro do Zendesk. Você não migra nada. Você não escreve código. Você conecta suas fontes e a IA aprende com elas.
Para equipes sem desenvolvedores dedicados, este pode ser um caminho mais rápido para o conhecimento unificado. Nossos preços começam em US$ 299/mês para o plano Team, que inclui até 3 bots e 1.000 interações de IA.
Melhores práticas e solução de problemas
Segurança
- Armazene tokens de API em variáveis de ambiente, nunca em seu código
- Gire os tokens regularmente (o Zendesk permite que você tenha até 256, para que você possa criar novos antes de excluir os antigos)
- Use tokens separados para diferentes integrações para que você possa revogar um sem afetar os outros
Paginação
Os endpoints de lista retornam resultados paginados. Use a paginação baseada em cursor para grandes conjuntos de dados (é mais confiável do que a paginação de deslocamento para alterar dados):
params = {"page[size]": 100}
while True:
resp = requests.get(url, params=params, headers=headers)
data = resp.json()
# Process records
for record in data["records"]:
process(record)
# Check for more pages
if not data["meta"]["has_more"]:
break
params["page[after]"] = data["meta"]["after_cursor"]
Testando
- Teste em um ambiente sandbox antes de executar na produção
- Use a coleção Postman do Zendesk para explorar os endpoints
- Registre as respostas da API durante o desenvolvimento para entender as condições de erro
Armadilhas comuns
- Esquecer o sufixo
/tokenno endereço de e-mail - Não codificar as credenciais em Base64
- Atingir limites de taxa durante operações em massa
- Não lidar com conflitos 409 com lógica de repetição
Comece a gerenciar o conteúdo do Zendesk de forma mais eficiente
A API Zendesk Guide oferece ferramentas poderosas para gerenciamento de conteúdo em escala. Seja automatizando uploads de mídia, organizando conteúdo com tags ou criando suporte a vários idiomas, a API fornece os primitivos de que você precisa.
Mas construir integrações personalizadas não é o único caminho. Se você deseja unificar suas fontes de conhecimento sem escrever código, o eesel AI oferece uma alternativa. Nosso Agente de IA se conecta ao Zendesk e aprende com sua documentação existente onde quer que ela esteja, sem necessidade de migração.
A escolha certa depende dos recursos técnicos e das necessidades específicas de sua equipe. Se você tem desenvolvedores e requisitos exclusivos, a API Guide é uma base sólida. Se você deseja começar a usar rapidamente o suporte com tecnologia de IA, explore o que o eesel AI pode fazer pela sua configuração do Zendesk.
Perguntas Frequentes
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.
