Como Gerar um Sitemap de uma API Protegida Usando Headers HTTP

Por que a geração de sitemap de API protegida importa

Muitos sites não expõem sua API de conteúdo abertamente. Isso nem sempre significa que o conteúdo é privado. Às vezes, a API é protegida simplesmente porque o backend requer autenticação para toda requisição, mesmo quando os dados retornados representam páginas públicas.

Por exemplo, um e-commerce pode ter páginas públicas de produtos, mas os dados vêm de um endpoint como:

E esse endpoint pode exigir um header como Authorization: Bearer SEU_TOKEN ou x-api-key: SUA_CHAVE. Sem esse header, a API retorna um erro. Com o header, ela retorna os dados necessários para construir o sitemap.

É aí que um gerador de sitemap com suporte a headers HTTP se torna útil. Em vez de tornar o endpoint público, você pode autorizar a requisição da API e mapear os campos JSON para as URLs do sitemap.

Casos de uso comuns para sitemaps de API protegida

A geração de sitemaps via API protegida é útil quando a fonte das URLs existe atrás de um endpoint autenticado. Casos de uso comuns incluem:

A URL da página pública e a fonte de dados privada não são a mesma coisa. O seu sitemap deve incluir URLs públicas, mas sua requisição de API ainda pode precisar de autorização para descobrir essas URLs.

• APIs de CMS headless que exigem chaves de API
• APIs de catálogo de produtos protegidas por bearer tokens
• APIs REST privadas usadas por sites públicos
• APIs de staging que precisam de autorização
• Sistemas de documentação atrás de headers customizados
• Anúncios de marketplace armazenados em rotas protegidas
• Listagens de imóveis de feeds de dados autorizados
• APIs de vagas de emprego que exigem tokens
• Serviços de backend que requerem headers Accept, Authorization ou x-api-key

Como o SitemapFlow usa Headers HTTP

O SitemapFlow permite definir headers personalizados ao conectar um endpoint de API. Após a requisição ser autorizada, o SitemapFlow lê a resposta e usa o seu padrão de URL para gerar as entradas do sitemap.

Por exemplo, se a API protegida retorna uma lista de produtos com slugs, você pode definir o padrão da URL como /produtos/[response.slug].

O header é usado apenas para acessar os dados da API. O sitemap final conterá as URLs públicas da página.

Headers HTTP comumente usados em APIs

APIs diferentes requerem headers diferentes. Os mais comuns são:

O SitemapFlow permite definir a chave e o valor do header, para que o nome do campo possa corresponder exatamente ao requisito da API que você está conectando.

• Bearer token de Autorização: (Authorization: Bearer SEU_TOKEN) Comum para APIs privadas, endpoints de CMS e backends SaaS.
• Header de Chave de API: (x-api-key: SUA_CHAVE) Outros sistemas podem usar api-key, x-access-token ou x-auth-token.
• Header Accept: (Accept: application/json) Útil quando um endpoint suporta múltiplos formatos de resposta.
• Headers customizados: (x-tenant-id: loja-123 ou x-locale: pt-BR) Usados para roteamento interno, tenants, idiomas ou versões.

Exemplos de Sitemaps de APIs Protegidas

Aqui estão exemplos de como diferentes plataformas podem gerar sitemaps usando dados protegidos:

• API de E-commerce: Exige 'x-api-key'. Mapeia /[response.category.slug]/[response.slug] para URLs públicas de produtos sem expor o endpoint de admin.
• Headless CMS: Exige 'Authorization: Bearer CMS_READ_TOKEN'. Mapeia /[response.type]/[response.slug] para gerar URLs para posts de blog e documentação.
• CMS Multi-idioma: Usa headers e mapeia /[response.locale]/[response.type]/[response.slug] para construir corretamente URLs internacionais.

Caminhos relativos e URLs completas com APIs protegidas

O sistema de padrões de URL funciona da mesma forma para APIs protegidas. O SitemapFlow suporta caminhos relativos e URLs completas.

Use um caminho relativo (ex: /produtos/[response.slug]) quando as URLs do sitemap gerado devem usar o domínio atual. Use uma URL completa (ex: https://loja.exemplo.com/produtos/[response.slug]) quando a página pertencer a um domínio específico, subdomínio ou aplicação separada.

Ambos os formatos podem mapear campos da resposta da API protegida.

Quais dados uma API protegida deve retornar?

Uma API protegida usada para geração de sitemaps deve retornar apenas os registros que podem se tornar URLs públicas e indexáveis.

Campos úteis incluem id, slug, category, updatedAt, locale, canonicalUrl, image, title, description e status.

A API deve evitar retornar registros que não deveriam estar nos resultados de busca, como rascunhos, registros excluídos, páginas privadas, painéis internos, URLs de staging ou duplicadas.

Se possível, crie um endpoint específico para a geração do sitemap (ex: /sitemap/produtos). Esse endpoint pode retornar uma lista limpa de registros indexáveis em vez de expor todo o seu modelo de dados interno.

Considerações de segurança para sitemaps via API

Um fluxo de sitemap de API protegida deve ser tratado com cuidado. Use chaves de API e tokens com permissão para acessar apenas os dados necessários para o sitemap. Evite usar tokens de admin quando um token somente leitura (read-only) for suficiente.

O SitemapFlow não armazena seus endpoints de API, credenciais ou headers em nossos servidores. O processamento acontece durante sua sessão ativa no navegador. Boas práticas incluem:

• Usar chaves de API somente leitura quando possível
• Limitar o token a registros públicos e indexáveis
• Evitar a exposição de dados privados de usuários
• Rotacionar tokens caso sejam vazados
• Evitar inserir segredos de produção em dispositivos compartilhados
• Criar um endpoint dedicado para sitemaps, se possível

APIs protegidas e sites privados não são a mesma coisa

Uma API protegida nem sempre significa que as páginas do site são privadas. Uma página pública de produto de e-commerce pode ser gerada a partir de uma API no backend que exige um token. A página é pública, mas a API é protegida. Esse é um caso ideal.

Mas se a página final em si exige login, ela geralmente não deve estar em um sitemap XML público.

Exemplos de páginas que não devem ser incluídas: /dashboard, /conta, /faturamento, /admin. Antes de gerar um sitemap, verifique se as URLs finais são realmente públicas e indexáveis.

Lidando com paginação e erros de API

Muitas APIs protegidas retornam resultados paginados. Se o endpoint retornar apenas a primeira página, o sitemap pode ficar incompleto. Certifique-se de que seu fluxo consiga acessar todos os registros, seja via parâmetros de paginação ou criando um endpoint dedicado ao sitemap.

Se uma requisição falhar, o sitemap não poderá ser gerado. Erros comuns incluem 401 Unauthorized (token ausente/inválido) e 403 Forbidden (token não tem permissão). O SitemapFlow destaca essas respostas quebradas para que você possa corrigir a configuração antes de enviar.

Erros comuns com sitemaps de APIs protegidas

O maior erro é colocar a URL do próprio endpoint da API no sitemap. Seu sitemap deve conter URLs públicas do site, não URLs privadas da API.

Outro erro é usar um token que retorna dados demais. Se a resposta incluir rascunhos ou objetos internos, estes podem acidentalmente se tornar entradas no sitemap.

• Usar um token de API expirado
• Esquecer o prefixo Bearer
• Usar a chave de header incorreta
• Usar um token de admin em vez de um somente leitura
• Gerar URLs a partir de registros não publicados
• Incluir páginas bloqueadas por login