Como publicar automaticamente no WordPress pela API REST

Publicar no WordPress por API parece simples até a primeira integração real. O caminho feliz tem quatro passos; o que faz a integração ser confiável são as armadilhas que aparecem depois — e que falham em silêncio, que é o pior tipo de falha.

O caminho básico

1. Credencial. No WordPress do destino: Usuários → Perfil → Senhas de aplicação. Gere uma senha por integração. Autenticação é Basic, com usuario:senha-de-aplicacao em base64 no cabeçalho Authorization.

2. Descobrir onde a REST responde. O padrão é https://site.com/wp-json/. Mas em instalação com permalink simples esse caminho não existe e a API responde em https://site.com/?rest_route=/.

3. Enviar a capa antes do post. POST /wp/v2/media com o binário da imagem e Content-Disposition: attachment; filename="capa.webp". A resposta traz um id.

4. Criar o post. POST /wp/v2/posts com título, conteúdo, status, categorias e featured_media apontando para o id do passo anterior.

As três armadilhas

Redirect transforma sucesso em fracasso silencioso

Se o site redireciona — http para https, ou domínio sem www para com www — e o seu cliente HTTP segue redirect automaticamente, acontece o seguinte: num 301, o método POST vira GET e o cabeçalho Authorization é descartado por segurança.

O WordPress recebe um GET sem autenticação em /wp-json/wp/v2/posts, e responde 200 com a lista de posts existentes. Se o seu código checa apenas o status HTTP, ele conclui que deu certo. O painel fica verde, a matéria é marcada como entregue, e o WordPress do cliente permanece vazio.

Como evitar: resolva a URL canônica uma vez, seguindo os redirects manualmente. Depois disso, escreva com maxRedirects: 0 — depois de canonicalizar, redirect em escrita é erro, não algo a seguir. E confirme sucesso pela presença de um id de post na resposta, nunca pelo status.

401 que não é culpa da senha

Hospedagem que roda PHP como CGI ou FastCGI frequentemente descarta o cabeçalho Authorization antes de entregar ao PHP. A credencial está correta e o WordPress nunca a recebe.

Sintoma típico: funciona no seu computador, falha no servidor do cliente. Solução do lado dele, no .htaccess:

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

Plugin de segurança bloqueando a REST API produz o mesmo sintoma e exige liberar a rota na configuração do plugin.

Reenvio duplicando matéria

Toda integração vai reenviar em algum momento — retry após falha de rede, correção de texto, reprocessamento. Sem controle de identidade, cada reenvio vira um post novo.

Como evitar: guarde o id do post retornado pelo WordPress e associe à sua matéria. No reenvio, se já existe id, faça POST /wp/v2/posts/{id} para atualizar em vez de criar. Assim reprocessar é seguro, e retry deixa de ser risco.

Rascunho ou publicado?

O campo status aceita draft, pending e publish. A escolha não é técnica, é editorial — e vale conversar antes de decidir por padrão.

Publicação automática direta significa conteúdo indo ao ar sem revisão humana, no nome do portal. Erro de curadoria vira erro público. A recomendação para quem está começando é entregar como draft e acompanhar alguns dias antes de mudar: o custo de revisar é baixo, e o de publicar errado, não.

O que separa protótipo de integração confiável

O caminho feliz cabe em vinte linhas. O que dá trabalho é o resto:

• Resolver a URL real, tratando redirect e permalink simples
• Confirmar sucesso pelo id do post, não pelo status HTTP
• Guardar o id para que reenvio atualize em vez de duplicar
• Traduzir erro HTTP em recado acionável — "credenciais recusadas, confira a senha de aplicação" resolve; "erro 401" não
• Retry com backoff, porque falha de rede é normal e não deve custar a matéria

Nenhum desses itens aparece na primeira versão. Todos aparecem no primeiro cliente real.