zendesk-guide-knowledge-base-api

{
  "title": "API da base de conhecimento do Zendesk Guide: O guia completo para desenvolvedores para 2026",
  "slug": "zendesk-guide-knowledge-base-api",
  "locale": "pt",
  "date": "2026-02-25",
  "updated": "2026-02-25",
  "template": "default",
  "excerpt": "Um guia técnico abrangente para a API do Centro de Ajuda do Zendesk com exemplos de código funcional, padrões de autenticação e práticas recomendadas de integração para desenvolvedores.",
  "categories": [
    "Zendesk",
    "Guides"
  ],
  "tags": [
    "Zendesk API",
    "Knowledge Base",
    "Help Center API",
    "Developer Guide",
    "Customer Support"
  ],
  "readTime": 10,
  "author": 16,
  "reviewer": 14,
  "seo": {
    "title": "API da base de conhecimento do Zendesk Guide: O guia completo para desenvolvedores para 2026",
    "description": "Um guia técnico abrangente para a API do Centro de Ajuda do Zendesk com exemplos de código funcional, padrões de autenticação e práticas recomendadas de integração para desenvolvedores.",
    "image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-3923a02a-382e-4c4c-a4bb-d10f99180563"
  },
  "coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-3923a02a-382e-4c4c-a4bb-d10f99180563",
  "coverImageAlt": "Imagem do banner para API da base de conhecimento do Zendesk Guide: O guia completo para desenvolvedores para 2026",
  "coverImageWidth": 1920,
  "coverImageHeight": 1080,
  "faqs": {
    "heading": "Perguntas Frequentes",
    "type": "blog",
    "answerType": "html",
    "faqs": [
      {
        "question": "Qual método de autenticação devo usar para a API da base de conhecimento do Zendesk Guide?",
        "answer": "Para scripts do lado do servidor e integrações de backend, use a autenticação por token de API. É mais simples de implementar e gerenciar. Para aplicativos do lado do cliente ou quando você precisa agir em nome de usuários individuais, use o OAuth 2.0. O OAuth oferece suporte a CORS, tornando-o adequado para aplicativos baseados em navegador."
      },
      {
        "question": "Como lidar com a paginação ao buscar todos os artigos por meio da API da base de conhecimento do Zendesk Guide?",
        "answer": "Use a paginação baseada em cursor adicionando `?page[size]=100` à sua solicitação. Siga o URL `links.next` na resposta até que `meta.has_more` seja falso. Este método é mais rápido do que a paginação por deslocamento e não tem limite de 10.000 registros."
      },
      {
        "question": "Quais são os limites de taxa para a API da base de conhecimento do Zendesk Guide?",
        "answer": "Os limites de taxa variam de acordo com o plano: o Suite Team recebe 200 solicitações/minuto, o Growth e o Professional recebem 400/minuto, o Enterprise recebe 700/minuto e o Enterprise Plus recebe 2.500/minuto. Se você atingir o limite, a API retorna um status 429 com um cabeçalho `Retry-After`."
      },
      {
        "question": "Posso usar a API da base de conhecimento do Zendesk Guide para sincronizar conteúdo com sistemas de IA externos?",
        "answer": "Sim. Você pode extrair artigos por meio da API, converter o conteúdo HTML para o formato de sua preferência (Markdown, texto simples) e alimentá-lo em bancos de dados vetoriais ou sistemas RAG. Alternativamente, plataformas de integração como o eesel AI podem lidar com essa sincronização automaticamente."
      },
      {
        "question": "Qual é a diferença entre a API do Centro de Ajuda do Zendesk e a API da base de conhecimento do Zendesk Guide?",
        "answer": "Elas são a mesma coisa. 'API do Centro de Ajuda' é o nome oficial na documentação do Zendesk, enquanto 'API da base de conhecimento do Guide' é um nome alternativo comum que enfatiza sua conexão com o produto Zendesk Guide. Ambas se referem à API REST em `/api/v2/help_center/`."
      }
    ],
    "supportLink": null
  }
}
---

Se você estiver criando integrações com o Zendesk ou procurando gerenciar programaticamente o conteúdo da sua base de conhecimento, a [API do Centro de Ajuda do Zendesk](https://developer.zendesk.com/api-reference/help_center/help-center-api/introduction/) (frequentemente chamada de API da base de conhecimento do Zendesk Guide) é a sua porta de entrada. Se você precisa sincronizar artigos com um sistema de pesquisa externo, criar uma solução de backup ou alimentar conteúdo em uma base de conhecimento de IA, esta API REST fornece as ferramentas para realizar o trabalho.

Vamos detalhar como ela funciona e como usá-la de forma eficaz.

![Uma captura de tela da página inicial do Zendesk.](https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/screenshots/zendesk-landing-page.png)

## O que é a API da base de conhecimento do Zendesk Guide?

A [API do Centro de Ajuda do Zendesk](https://developer.zendesk.com/api-reference/help_center/help-center-api/introduction/) é uma API REST que permite gerenciar programaticamente o conteúdo da sua base de conhecimento do Zendesk Guide. Ela faz parte do ecossistema de API mais amplo do Zendesk e usa JSON para solicitações e respostas.

Aqui está o que você pode fazer com ela:

- **Ler conteúdo** - buscar artigos, seções e categorias para uso externo
- **Escrever conteúdo** - criar, atualizar e arquivar artigos programaticamente
- **Gerenciar traduções** - lidar com conteúdo multilíngue em escala
- **Pesquisar e filtrar** - encontrar conteúdo específico usando rótulos, datas e outros critérios

A API segue as convenções REST padrão. Seu URL base se parece com `https://{seu-subdomínio}.zendesk.com/api/v2/help_center/`, e todas as respostas são filtradas de acordo com as permissões do usuário que faz a solicitação. Isso significa que usuários anônimos só veem conteúdo público, enquanto agentes podem acessar artigos internos dependendo de suas permissões.

## Primeiros passos com a autenticação

Antes de fazer qualquer chamada à API, você precisa se autenticar. O Zendesk oferece dois métodos principais: tokens de API e OAuth 2.0.

### Autenticação por token de API (recomendado para scripts do lado do servidor)

Os tokens de API são a maneira mais simples de começar. Você os gera no seu Admin Center do Zendesk em **Aplicativos e integrações > APIs > API do Zendesk**.

| Atributo | Detalhe |
|-----------|--------|
| Limite de token | 256 por conta (até 2.048 para contas maiores) |
| Formato | `{endereço_de_email}/token:{api_token}` |
| Cabeçalho | `Authorization: Basic {credenciais_codificadas_em_base64}` |

Veja como fica na prática:

```bash
curl https://seu-domínio.zendesk.com/api/v2/help_center/articles.json \
  -u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

A flag -u no cURL lida automaticamente com a codificação Base64 para você. Se você estiver construindo o cabeçalho manualmente no código, combine seu e-mail e token com dois pontos, codifique o resultado em Base64 e adicione-o ao cabeçalho Authorization.

OAuth 2.0 (para aplicativos voltados para o usuário)

Se você estiver criando um aplicativo do lado do cliente ou precisar agir em nome de usuários individuais, o OAuth é a melhor escolha. Ele usa tokens Bearer:

curl https://seu-domínio.zendesk.com/api/v2/help_center/articles.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

A principal vantagem aqui é que o OAuth oferece suporte a CORS, tornando-o adequado para aplicativos baseados em navegador. Os tokens de API não oferecem suporte a CORS e são limitados ao uso do lado do servidor.

Nota de segurança: Todas as conexões devem usar TLS 1.2 ou superior. Armazene seus tokens com segurança e nunca os envie para o controle de versão.

Endpoints e operações principais da API

A API do Centro de Ajuda é organizada em torno de três tipos de conteúdo principais: categorias, seções e artigos. Pense nisso como uma hierarquia: as categorias contêm seções e as seções contêm artigos.

Trabalhando com artigos

O endpoint de artigos é onde você passará a maior parte do seu tempo. Aqui estão as principais operações:

Listar todos os artigos:

GET /api/v2/help_center/articles.json

Isso retorna uma lista paginada de artigos. Você pode filtrar os resultados usando parâmetros de consulta:

Parâmetro	Propósito	Exemplo
label_names	Filtrar por rótulos	?label_names=faq,billing
sort_by	Campo de classificação	?sort_by=updated_at
sort_order	Direção da classificação	?sort_order=desc
start_time	Exportação incremental	?start_time=1704067200

Obter um artigo específico:

GET /api/v2/help_center/articles/{article_id}.json

Criar um artigo:

POST /api/v2/help_center/sections/{section_id}/articles.json

Os campos obrigatórios incluem title (título), locale (localidade) e permission_group_id (ID do grupo de permissão). Você também pode definir campos opcionais como body (conteúdo HTML), author_id (ID do autor), label_names (nomes de rótulo) e status draft (rascunho).

Atualizar um artigo:

PUT /api/v2/help_center/articles/{article_id}.json

Arquivar um artigo:

DELETE /api/v2/help_center/articles/{article_id}.json

Endpoints da hierarquia de conteúdo

Endpoint	Propósito
GET /api/v2/help_center/categories.json	Listar todas as categorias
GET /api/v2/help_center/categories/{id}/sections.json	Listar seções em uma categoria
GET /api/v2/help_center/sections.json	Listar todas as seções
GET /api/v2/help_center/sections/{id}/articles.json	Listar artigos em uma seção

Carregamento lateral de dados relacionados

Um recurso útil é o carregamento lateral (sideloading), que permite incluir dados relacionados em uma única solicitação. Adicione ?include=users,sections,categories à sua solicitação de artigos, e a resposta incluirá objetos completos para autores, seções e categorias, em vez de apenas IDs.

Lidando com a paginação de forma eficiente

A paginação é onde muitos desenvolvedores encontram seu primeiro obstáculo. A API do Centro de Ajuda oferece suporte a dois métodos de paginação, e escolher o certo é importante.

Paginação baseada em cursor (recomendado)

A paginação por cursor é a abordagem moderna e tem um desempenho significativamente melhor com grandes conjuntos de dados. Para usá-la, adicione page[size] à sua solicitação:

GET /api/v2/help_center/articles.json?page[size]=100

A resposta inclui um objeto meta com um booleano has_more e um objeto links com URLs next e prev:

{
  "articles": [...],
  "meta": {
    "has_more": true
  },
  "links": {
    "next": "https://.../articles.json?page[size]=100&page[after]=xxx",
    "prev": null
  }
}

Continue seguindo o URL next até que has_more seja falso. Aqui está um exemplo em Python:

import requests
from base64 import b64encode

def fetch_all_articles(subdomain, email, token):
    base_url = f"https://{subdomain}.zendesk.com/api/v2/help_center/articles.json"
    credentials = b64encode(f"{email}/token:{token}".encode()).decode()
    headers = {"Authorization": f"Basic {credentials}"}

    articles = []
    url = f"{base_url}?page[size]=100"

    while url:
        response = requests.get(url, headers=headers)
        data = response.json()
        articles.extend(data["articles"])

        url = data["links"]["next"] if data["meta"]["has_more"] else None

    return articles

Paginação baseada em deslocamento (legado)

A paginação por deslocamento ainda funciona, mas tem limitações. A partir de agosto de 2023, você não pode recuperar mais de 10.000 registros (100 páginas) usando este método. Se você tentar, receberá um erro 400 Bad Request.

GET /api/v2/help_center/articles.json?per_page=100&page=2

A resposta inclui URLs next_page e previous_page. Pare quando next_page for nulo.

Conclusão: Use a paginação por cursor para novas integrações. É mais rápido, mais confiável e não tem limites rígidos.

Padrões de integração comuns

Agora que você entende o básico, vamos ver como os desenvolvedores normalmente usam esta API em produção.

Indexação de pesquisa externa

Um caso de uso comum é indexar seus artigos do Zendesk em um mecanismo de pesquisa externo como Elasticsearch ou Algolia. O padrão se parece com isto:

1. Buscar todos os artigos usando paginação por cursor
2. Transformar o corpo HTML em texto simples (remover tags)
3. Indexar o ID do artigo, título, texto do corpo e URL
4. Configurar uma sincronização periódica usando o parâmetro start_time para atualizações incrementais

A chave é preservar o URL original do artigo em seu índice para que os resultados da pesquisa possam vincular de volta ao Zendesk.

Backup e migração de conteúdo

Para fluxos de trabalho de backup, você pode querer exportar toda a sua base de conhecimento:

1. Iterar por todas as categorias
2. Para cada categoria, obter suas seções
3. Para cada seção, obter seus artigos
4. Salvar os objetos de artigo completos (incluindo o corpo HTML) no seu armazenamento de backup

Isso preserva sua hierarquia de conteúdo e torna a restauração direta.

Integração de sistema de IA e RAG

Um caso de uso crescente é alimentar o conteúdo do Zendesk em sistemas de Geração Aumentada por Recuperação (RAG) para suporte com tecnologia de IA. O fluxo de trabalho normalmente envolve:

1. Extrair artigos via API
2. Converter HTML para Markdown ou texto simples
3. Dividir o conteúdo em partes para armazenamento vetorial
4. Preservar o URL original para citações

É aqui que ferramentas como o eesel AI podem ajudar. Em vez de construir pipelines ETL personalizados, você pode conectar sua conta do Zendesk diretamente e ter um agente de IA que responde a perguntas usando o conteúdo da sua base de conhecimento, completo com citações de volta aos artigos originais.

Limites de taxa e práticas recomendadas

Entender os limites de taxa impede que sua integração atinja paredes em escala.

Limites de solicitação por plano

Plano	Limite da API de Suporte/Centro de Ajuda
Suite Team	200 solicitações/minuto
Suite Growth	400 solicitações/minuto
Suite Professional	400 solicitações/minuto
Suite Enterprise	700 solicitações/minuto
Suite Enterprise Plus	2.500 solicitações/minuto

Fonte: Documentação de Limites de Taxa do Zendesk

Lidando com erros de limite de taxa

Quando você excede o limite, a API retorna um código de status 429 com um cabeçalho Retry-After indicando quantos segundos esperar. Seu código deve:

1. Verificar respostas 429
2. Extrair o valor Retry-After
3. Esperar esses segundos antes de tentar novamente
4. Considerar implementar backoff exponencial para falhas repetidas

Aqui está um decorador de repetição simples em Python:

import time
import requests
from functools import wraps

def with_rate_limit_retry(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        max_retries = 3
        for attempt in range(max_retries):
            response = func(*args, **kwargs)
            if response.status_code != 429:
                return response

            retry_after = int(response.headers.get("Retry-After", 60))
            time.sleep(retry_after)

        raise Exception("Rate limit exceeded after retries")
    return wrapper

@with_rate_limit_retry
def api_call(url, headers):
    return requests.get(url, headers=headers)

Dicas de desempenho

• Use paginação por cursor - é mais rápido e não tem limite de 10.000 registros
• Habilite o carregamento lateral - busque dados relacionados em uma solicitação em vez de fazer várias chamadas
• Armazene em cache agressivamente - o conteúdo do artigo não muda com tanta frequência
• Use exportações incrementais - o parâmetro start_time permite que você busque apenas o conteúdo alterado

Abordagens alternativas a serem consideradas

Construir uma integração de API personalizada nem sempre é a escolha certa. Aqui está uma estrutura rápida para decidir:

Use a API diretamente quando:

• Você precisa de controle total sobre a transformação de dados
• Você tem recursos de engenharia dedicados
• Seu caso de uso é único ou complexo

Use os recursos nativos do Zendesk quando:

• Você só quer exibir conteúdo externo na pesquisa - use a pesquisa federada
• Você precisa de gerenciamento de conteúdo básico - use a interface do usuário integrada

Use uma plataforma de integração quando:

• Você quer respostas com tecnologia de IA sem construir pipelines RAG
• Você precisa de configuração rápida sem recursos de engenharia
• Você quer sincronização contínua sem sobrecarga de manutenção

É aqui que o eesel AI se encaixa. Em vez de escrever scripts personalizados para extrair, transformar e sincronizar seu conteúdo do Zendesk, você pode conectar sua conta em minutos e obter um colega de equipe de IA que responde a perguntas de clientes usando sua base de conhecimento. Ele lida com a integração da API, indexação de conteúdo e geração de respostas, permitindo que você se concentre em trabalhos de maior valor.

Construa integrações de conhecimento poderosas com o Zendesk

A API do Centro de Ajuda do Zendesk oferece os blocos de construção para criar fluxos de trabalho sofisticados de gerenciamento de conhecimento. Se você estiver construindo um índice de pesquisa personalizado, migrando conteúdo entre sistemas ou alimentando artigos em plataformas de IA, entender a autenticação, a paginação e os limites de taxa o prepara para o sucesso.

Comece pequeno: busque uma lista de artigos, experimente a paginação e, em seguida, construa integrações mais complexas. E se você perceber que está gastando mais tempo mantendo pipelines de dados do que resolvendo problemas de negócios, considere se uma plataforma de integração pode ser uma opção melhor.

Se você estiver procurando aprimorar sua configuração do Zendesk com recursos de IA, o eesel AI oferece uma integração direta que transforma sua base de conhecimento em um agente de suporte inteligente. Nenhum desenvolvimento de API personalizado é necessário.