zendesk-guide-api-articles-list
eesel Team
Last edited 26 fevereiro 2026
{
"title": "Como listar artigos do Zendesk Guide usando a API: um guia completo",
"slug": "zendesk-guide-api-articles-list",
"locale": "pt",
"date": "2026-02-25",
"updated": "2026-02-25",
"template": "default",
"excerpt": "Um guia passo a passo para usar a API do Zendesk Guide para listar e gerenciar artigos da central de ajuda de forma programática.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk",
"API",
"Help Center",
"Developer",
"Integration"
],
"readTime": 10,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Como listar artigos do Zendesk Guide usando a API: um guia completo",
"description": "Um guia passo a passo para usar a API do Zendesk Guide para listar e gerenciar artigos da central de ajuda de forma programática.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-aa4d8e3a-8d22-4e7d-9218-439f1e1b0a33"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-aa4d8e3a-8d22-4e7d-9218-439f1e1b0a33",
"coverImageAlt": "Imagem do banner para Como listar artigos do Zendesk Guide usando a API: um guia completo",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas Frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Como obtenho uma lista completa de artigos da API do Zendesk Guide se tiver milhares de artigos?",
"answer": "Use a paginação do cursor com ?page[size]=100 e siga os links.next URL em cada resposta até que retorne nulo. Isso recupera todos os artigos sem o limite de 100 páginas da paginação de deslocamento."
},
{
"question": "Qual método de autenticação devo usar para a API do Zendesk Guide para listar artigos?",
"answer": "Use a autenticação básica com seu endereço de e-mail e um token de API. O formato é {email}/token:{api_token} codificado em Base64 para o cabeçalho de autorização."
},
{
"question": "Posso filtrar a lista de artigos da API do Zendesk Guide para excluir artigos de rascunho?",
"answer": "Sim. Cada objeto de artigo inclui um campo booleano de rascunho. Filtre seus resultados no código verificando se não article['draft'] para incluir apenas artigos publicados."
},
{
"question": "Como lido com os limites de taxa ao listar um grande número de artigos por meio da API do Zendesk?",
"answer": "Monitore os códigos de status 429 e implemente o backoff exponencial. Adicione atrasos entre as solicitações (por exemplo, 500ms) e tente novamente após a redefinição da janela de limite de taxa."
},
{
"question": "Existe uma maneira de obter apenas artigos que foram alterados desde uma data específica usando a API do Zendesk Guide?",
"answer": "Sim. Use o endpoint incremental /api/v2/help_center/incremental/articles com um parâmetro start_time contendo um timestamp da época Unix."
}
],
"supportLink": null
}
}
---
Se você está procurando acessar programaticamente o conteúdo da sua central de ajuda do Zendesk, seja para construir um índice de pesquisa personalizado, criar backups ou sincronizar artigos com outra plataforma, a API do Zendesk Guide é a sua ferramenta ideal. Mas, como muitas APIs REST, começar pode parecer complicado. Há autenticação para descobrir, paginação para lidar e uma variedade de endpoints para escolher.
Este guia orienta você em tudo o que você precisa saber para listar e recuperar artigos do Zendesk Guide usando a API. Abordaremos a autenticação, como fazer suas primeiras solicitações, como lidar com a paginação para grandes bibliotecas de conteúdo e exemplos de código do mundo real que você pode adaptar às suas necessidades.
## O que você precisa para começar
Antes de mergulhar nas chamadas da API, certifique-se de ter estes pré-requisitos em vigor:
- **Uma conta Zendesk com acesso de administrador ou agente** - você precisará das permissões apropriadas para gerar tokens de API e acessar o conteúdo da central de ajuda
- **Um token de API** - gerado a partir do seu Admin Center do Zendesk (abordaremos isso na etapa 1)
- **Familiaridade básica com APIs REST** - compreensão dos métodos HTTP (GET, POST), formato JSON e cabeçalhos de solicitação
- **Uma ferramenta para fazer solicitações de API** - isso pode ser cURL, Postman ou um ambiente de programação como Python ou Node.js
- **Conhecimento dos limites de taxa do seu plano** - O Zendesk impõe diferentes limites de solicitação com base no seu nível de assinatura
Falando em limites de taxa, aqui está o que você está trabalhando dependendo do seu plano:
| Plano | Solicitações por minuto |
|------|---------------------|
| Essential | 10 RPM |
| Team | 200 RPM |
| Professional | 400 RPM |
| Enterprise | 700 RPM |
| High Volume Add-on | 2.500 RPM |
Se você exceder esses limites, receberá um erro 429. A API segue os limites de solicitações por minuto da API de suporte, e as solicitações em uma API não contam para o limite de taxa da outra.
## Compreendendo a estrutura da API do Zendesk Guide
A [API da Central de Ajuda do Zendesk](https://developer.zendesk.com/api-reference/help_center/help-center-api/introduction/) é uma API REST que permite interagir com o conteúdo da sua base de conhecimento de forma programática. Antes de fazer solicitações, é útil entender como o conteúdo é organizado.
O Zendesk Guide segue uma estrutura hierárquica:
- **Categorias** são os contêineres de nível superior para organizar o conteúdo
- **Seções** vivem dentro de categorias e agrupam artigos relacionados
- **Artigos** são as peças de conteúdo reais (tópicos de ajuda, FAQs, guias)
Quando você lista artigos por meio da API, você pode recuperar todos os artigos em sua central de ajuda ou filtrar por categorias ou seções específicas. A API retorna respostas JSON contendo metadados do artigo, como título, conteúdo do corpo, informações do autor, status de rascunho e muito mais.
A autenticação usa Basic Auth com seu endereço de e-mail e um token de API. O formato é `{email_address}/token:{api_token}`, que é codificado em Base64 para o cabeçalho de autorização.
Uma nota importante: as respostas são sempre filtradas de acordo com as permissões do usuário que faz a solicitação. Portanto, se você estiver autenticando como um usuário final em vez de um agente ou administrador, você só verá os artigos que o usuário tem permissão para visualizar.
## Passo 1: configurar a autenticação da API
Para começar a usar a API, você precisa de um token de API. Veja como gerar um:
1. Faça login na sua conta Zendesk como administrador
2. Navegue até **Admin Center** → **Canais** → **API**
3. Clique na aba **Configurações**
4. Habilite o **Acesso ao Token** se ainda não estiver
5. Clique no botão **+** para adicionar um novo token
6. Dê ao seu token um nome descritivo (como "Script de Exportação de Artigos")
7. Copie o token imediatamente - O Zendesk só o mostra uma vez
Depois de ter seu token, você pode testar a autenticação com uma solicitação cURL simples:
```bash
curl https://{your_subdomain}.zendesk.com/api/v2/help_center/articles \
-v -u {your_email}/token:{your_api_token}
Substitua {your_subdomain} pelo seu subdomínio Zendesk, {your_email} pelo seu e-mail da conta e {your_api_token} pelo token que você acabou de gerar.
Se a autenticação for bem-sucedida, você verá um código de status 200 e uma resposta JSON com seus artigos. Se você receber um erro 401, verifique se seu token está ativo e se sua combinação de e-mail/token está correta.
Problemas comuns de autenticação:
- 401 Não autorizado - O token está inativo ou o formato de e-mail/token está errado
- 403 Proibido - O usuário não tem permissão para acessar o recurso
- 404 Não encontrado - O URL do endpoint está incorreto
Passo 2: listar todos os artigos com chamada básica da API
Agora que você está autenticado, vamos recuperar os artigos. O endpoint primário para listar artigos é:
GET /api/v2/help_center/articles
Aqui está um exemplo completo em Python usando a biblioteca requests:
import requests
from requests.auth import HTTPBasicAuth
subdomain = 'your_subdomain'
email = 'your_email@example.com'
api_token = 'your_api_token'
url = f'https://{subdomain}.zendesk.com/api/v2/help_center/articles'
response = requests.get(
url,
auth=HTTPBasicAuth(f'{email}/token', api_token),
headers={'Content-Type': 'application/json'}
)
data = response.json()
articles = data['articles']
for article in articles:
if not article['draft']: # Skip drafts
print(f"{article['id']}: {article['title']}")
A resposta inclui um array articles onde cada objeto de artigo contém campos como:
| Campo | Descrição |
|---|---|
id | Identificador único do artigo |
title | Título do artigo |
body | Conteúdo HTML do artigo |
section_id | ID da seção que contém este artigo |
draft | Booleano indicando se o artigo é um rascunho |
created_at | Timestamp ISO 8601 da criação |
updated_at | Timestamp ISO 8601 da última atualização |
author_id | ID do usuário que criou o artigo |
Por padrão, este endpoint retorna 30 artigos por página. Se você tiver mais artigos, você precisará lidar com a paginação (abordado na etapa 3).
Passo 3: lidar com a paginação para grandes listas de artigos
A paginação é onde muitos desenvolvedores ficam presos. A API do Zendesk Guide suporta dois métodos de paginação: paginação do cursor (recomendado) e paginação de deslocamento.
A paginação do cursor é a abordagem moderna e funciona seguindo os links "next" na resposta da API. É mais eficiente para grandes conjuntos de dados e não tem as restrições de limite de página da paginação de deslocamento.
Para usar a paginação do cursor, adicione ?page[size]=100 à sua solicitação (100 é o máximo). Aqui está uma implementação completa em Python que recupera TODOS os artigos em todas as páginas:
import requests
from requests.auth import HTTPBasicAuth
def get_all_articles(subdomain, email, api_token):
articles = []
url = f'https://{subdomain}.zendesk.com/api/v2/help_center/articles?page[size]=100'
while url:
response = requests.get(
url,
auth=HTTPBasicAuth(f'{email}/token', api_token),
headers={'Content-Type': 'application/json'}
)
if response.status_code != 200:
print(f"Error: {response.status_code}")
break
data = response.json()
articles.extend(data['articles'])
# Get the next page URL from the links object
url = data.get('links', {}).get('next')
print(f"Retrieved {len(articles)} articles so far...")
return articles
all_articles = get_all_articles('your_subdomain', 'your_email', 'your_token')
print(f"Total articles: {len(all_articles)}")
A chave é verificar data['links']['next']. Quando você chegar à página final, este valor será null e seu loop terminará.
A paginação de deslocamento é o método mais antigo e é limitado a 100 páginas no máximo. Ele usa os parâmetros per_page e page. O Zendesk recomenda a paginação do cursor para novas implementações.
Ao paginar por meio de grandes conjuntos de dados, esteja atento aos limites de taxa. Se você tiver milhares de artigos, considere adicionar um pequeno atraso entre as solicitações:
import time
time.sleep(0.5) # 500ms delay
Passo 4: filtrar e classificar artigos
A API oferece várias maneiras de filtrar e classificar suas listagens de artigos.
Filtrando por rótulos: Se você usar rótulos de artigo (disponíveis nos planos Professional e Enterprise), você pode filtrar por eles:
GET /api/v2/help_center/articles?label_names=photos,camera
Isso retorna apenas artigos que têm TODOS os rótulos especificados. A correspondência de rótulos diferencia maiúsculas de minúsculas.
Classificando:
Use os parâmetros sort_by e sort_order para controlar a ordem:
| Opção de classificação | Descrição |
|---|---|
position | Ordem manual da página Organizar Conteúdo (padrão) |
title | Alfabético por título |
created_at | Tempo de criação |
updated_at | Tempo da última atualização |
edited_at | Última vez que o título ou o corpo foi editado |
Exemplo: /api/v2/help_center/articles?sort_by=updated_at&sort_order=desc
Exportações incrementais:
Para sincronizar artigos com sistemas externos, use o endpoint incremental com um parâmetro start_time:
GET /api/v2/help_center/incremental/articles?start_time=1704067200
O start_time é um timestamp da época Unix. Isso retorna apenas artigos criados ou atualizados desde esse horário.
Listando por categoria ou seção: Para obter artigos de uma categoria específica:
GET /api/v2/help_center/categories/{category_id}/articles
Ou de uma seção específica:
GET /api/v2/help_center/sections/{section_id}/articles
Carregamento lateral de dados relacionados: Para reduzir as chamadas da API, você pode carregar lateralmente recursos relacionados:
GET /api/v2/help_center/articles?include=users,sections,categories
Isso inclui os objetos completos de usuário, seção e categoria na resposta, para que você não precise fazer chamadas de API separadas para essas informações.
Casos de uso comuns e exemplos de código
Aqui estão algumas implementações práticas para cenários comuns:
Exportar todos os artigos para indexação de pesquisa: Este script exporta todos os artigos publicados para um arquivo JSON, filtrando rascunhos e incluindo apenas campos essenciais:
import json
import requests
from requests.auth import HTTPBasicAuth
def export_articles_for_search(subdomain, email, api_token, output_file):
articles = []
url = f'https://{subdomain}.zendesk.com/api/v2/help_center/articles?page[size]=100'
while url:
response = requests.get(url, auth=HTTPBasicAuth(f'{email}/token', api_token))
data = response.json()
for article in data['articles']:
if not article['draft']:
articles.append({
'id': article['id'],
'title': article['title'],
'body': article['body'],
'url': article['html_url'],
'updated_at': article['updated_at']
})
url = data.get('links', {}).get('next')
with open(output_file, 'w') as f:
json.dump(articles, f, indent=2)
print(f"Exported {len(articles)} articles to {output_file}")
Melhores práticas de tratamento de erros: Sempre lide com possíveis erros em suas chamadas de API:
response = requests.get(url, auth=auth)
if response.status_code == 429:
# Rate limit hit wait and retry
time.sleep(60)
response = requests.get(url, auth=auth)
elif response.status_code == 401:
print("Authentication failed check your API token")
sys.exit(1)
elif response.status_code != 200:
print(f"API error: {response.status_code}")
print(response.text)
Gerenciando o conteúdo do Zendesk Guide com eesel AI
Embora a API do Zendesk Guide lhe dê acesso programático ao conteúdo da sua central de ajuda, gerenciar e aproveitar esse conteúdo de forma eficaz é onde o eesel AI entra em cena.
Em vez de construir scripts personalizados para sincronizar artigos, nosso agente de IA se conecta diretamente ao seu Zendesk Guide e aprende com o conteúdo da sua central de ajuda automaticamente. Isso significa:
- Configuração sem código - conecte sua conta Zendesk e o eesel AI importa seus artigos automaticamente
- Sempre atualizado - quando você atualiza artigos no Zendesk, o eesel AI aprende as mudanças
- Suporte a vários idiomas - funciona com artigos em qualquer um dos mais de 80 idiomas que o Zendesk suporta
- Respostas inteligentes - nossa IA responde às perguntas dos clientes usando o conteúdo da sua central de ajuda como fonte da verdade
Para equipes que procuram construir suporte alimentado por IA sem a sobrecarga de engenharia, o eesel AI lida com a complexidade de sincronizar, indexar e recuperar o conteúdo do artigo certo no momento certo. Você pode começar com o AI Copilot para rascunhar respostas para seus agentes, então subir de nível para a automação completa do AI Agent à medida que você ganha confiança.
Comece a construir com a API do Zendesk Guide hoje
Agora você tem tudo o que precisa para começar a trabalhar com a API do Zendesk Guide. Aqui está um resumo rápido:
- Gere um token de API a partir do seu Admin Center do Zendesk
- Faça solicitações autenticadas usando Basic Auth com seu e-mail e token
- Lide com a paginação usando a paginação do cursor para grandes bibliotecas de artigos
- Filtre e classifique usando parâmetros de consulta para obter exatamente os dados de que você precisa
Para recursos mais avançados, como criar ou atualizar artigos, gerenciar traduções ou trabalhar com anexos de artigos, consulte a documentação oficial da API do Zendesk.
E se você está procurando fazer mais com o conteúdo da sua central de ajuda - como alimentar respostas de IA, construir pesquisa personalizada ou criar fluxos de trabalho automatizados - considere como o eesel AI pode ajudá-lo a chegar lá mais rápido sem escrever código de integração personalizado.
Compartilhe esta postagem
Article by
