zendesk-guide-api-content-management
eesel Team
Last edited 26 fevereiro 2026
{
"title": "Gerenciamento de conteúdo da API Zendesk Guide: Um guia completo para desenvolvedores",
"slug": "zendesk-guide-api-content-management",
"locale": "pt",
"date": "2026-02-25",
"updated": "2026-02-25",
"template": "default",
"excerpt": "Um guia prático para desenvolvedores sobre como gerenciar o conteúdo do Zendesk Guide programaticamente, com padrões de autenticação, endpoints de API e exemplos de código funcional.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk API",
"Guide API",
"Content Management",
"Developer Guide",
"Help Center API"
],
"readTime": 8,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Gerenciamento de conteúdo da API Zendesk Guide: Um guia completo para desenvolvedores",
"description": "Um guia prático para desenvolvedores sobre como gerenciar o conteúdo do Zendesk Guide programaticamente, com padrões de autenticação, endpoints de API e exemplos de código funcional.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-db52e74f-4912-436b-828b-fea149a53332"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-db52e74f-4912-436b-828b-fea149a53332",
"coverImageAlt": "Imagem do banner para gerenciamento de conteúdo da API Zendesk Guide: Um guia completo para desenvolvedores",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas Frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Qual método de autenticação o gerenciamento de conteúdo da API Zendesk Guide requer?",
"answer": "Você pode usar a autenticação de token de API (recomendada para uso em conta única) ou OAuth (necessário para aplicativos multi-cliente). Os tokens de API são gerados no Admin Center e usados com autenticação básica no formato email/token:token."
},
{
"question": "Quais são os limites de taxa para operações de gerenciamento de conteúdo da API Zendesk Guide?",
"answer": "A maioria dos endpoints permite 700 solicitações por minuto. Se você exceder isso, receberá um código de status 429. Implemente a lógica de repetição com backoff exponencial para integrações de produção."
},
{
"question": "Posso usar o gerenciamento de conteúdo da API Zendesk Guide em qualquer nível de plano?",
"answer": "O acesso básico à API Guide está disponível nos planos Suite Team e superiores. No entanto, alguns recursos como Conteúdo Dinâmico exigem planos Professional ou superiores. Verifique seu caso de uso específico em relação aos recursos do plano do Zendesk."
},
{
"question": "Como lidar com uploads de arquivos com o gerenciamento de conteúdo da API Zendesk Guide?",
"answer": "Os uploads de arquivos usam um processo de 3 etapas: (1) solicitar um URL de upload com metadados de arquivo, (2) PUT o arquivo para o URL assinado, (3) criar o objeto de mídia com o ID do ativo. O tamanho máximo do arquivo é de 20 MB."
},
{
"question": "Qual é a diferença entre usar o gerenciamento de conteúdo da API Zendesk Guide e uma plataforma de integração como eesel AI?",
"answer": "A API Guide requer desenvolvimento personalizado e é melhor para fluxos de trabalho exclusivos ou migrações em grande escala. Plataformas de integração como eesel AI fornecem alternativas sem código que conectam suas fontes de conhecimento existentes ao Zendesk sem escrever scripts."
},
{
"question": "O gerenciamento de conteúdo da API Zendesk Guide oferece suporte a operações em massa?",
"answer": "Sim. A API Content Tags oferece suporte a operações em lote por meio do endpoint de trabalhos para ações de exclusão e mesclagem. Para outros endpoints, implemente a paginação e percorra os registros programaticamente."
}
],
"supportLink": null
}
}
---
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](https://www.eesel.ai).
## O que você vai precisar
Antes de mergulhar, certifique-se de que você tem:
- Uma [conta Zendesk](https://www.zendesk.com) 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](https://support.zendesk.com/hc/en-us/articles/4408827565338) 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:**
```bash
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.
Compartilhe esta postagem
Article by
