WooCommerce Store API: rotas, esquema e autenticação sem atalhos

ANÁLISE EDITORIAL

Uma rota de loja pode parecer apenas uma URL que recebe JSON. No WooCommerce, essa impressão fica perigosa quando o mesmo endpoint toca carrinho, sessão e dados de cliente. A Skill oficial WooCommerce Store API ajuda quem desenvolve extensões a separar o que é leitura pública, o que altera o carrinho e qual contrato o front-end realmente pode esperar. Ela não instala um plugin nem testa uma loja sozinha: é um conjunto de instruções para orientar um agente de programação, sempre com revisão humana do código produzido.

O que esta Skill faz e para quem serve

O foco é adicionar ou modificar rotas em /wc/store/v1/*, desenhar esquemas de resposta e lidar com autenticação, variações de produto, idempotência e desempenho. É útil para desenvolvedores de extensões WooCommerce e equipes que mantêm integrações voltadas ao comprador, sobretudo quando uma mudança em carrinho ou checkout precisa ser entendida por blocos e aplicações externas. Não é uma Skill de operação de loja, marketing ou administração de pedidos.

A documentação oficial da Store API distingue essa superfície pública da API REST administrativa. A primeira se destina a produtos, carrinho e checkout do cliente atual; ela não autoriza consultar pedidos de terceiros por ID nem alterar configurações da loja. Essa distinção é o primeiro filtro antes de aceitar um pedido de implementação vindo de um agente.

Por que a seleção é específica

O catálogo já tem materiais sobre WordPress e revisão de código em geral. Esta entrada é diferente: trata das convenções concretas da Store API do WooCommerce, como o uso de AbstractCartRoute em mutações do carrinho e a correspondência entre esquema e resposta. Não é uma continuação artificial da Skill WordPress nem um novo pacote do mesmo repositório publicado antes. O repositório oficial woocommerce/woocommerce registrava 10.547 estrelas em 11/10/2026, às 12h17 de São Paulo, segundo a API pública do GitHub. A contagem é mutável e não comprova que um endpoint gerado seja seguro.

Compatibilidade e pré-requisitos

O material é um SKILL.md com cinco documentos Markdown de apoio. Pode ser lido por agentes que aceitam diretórios de Skills ou simplesmente fornecido como referência de projeto. Para uso prático, a pessoa precisa de um ambiente de desenvolvimento com WordPress e WooCommerce, acesso ao código da extensão, uma versão do WooCommerce compatível com a Store API em uso e meios de executar testes locais. O pacote documental não instala WooCommerce, não fornece uma loja de teste e não fixa uma versão mínima do PHP. Antes de alterar código, confira a matriz de requisitos da versão efetivamente instalada na documentação de desenvolvimento do WooCommerce.

O commit desta edição é 55596a6d1e015c7c6a1b70d3d1aa03e6a5180087. O arquivo da Skill não declara uma versão semântica própria. Fixar o commit permite conferir o conteúdo desta cópia, mas não congela a versão do plugin em sua loja. Se o código local for de outra revisão, compare classes e assinaturas antes de seguir um exemplo.

Instalação sem executar código desconhecido

Baixe o ZIP local do card, compare seu SHA-256 com o valor exibido, extraia em uma pasta de inspeção e leia ORIGEM.md e LICENSE. O arquivo contém apenas seis Markdown originais, a licença e a nota de origem. Não há instalador, PHP, dependência, token ou binário. Depois, copie a pasta woocommerce-store-api para o diretório de Skills aceito pelo cliente escolhido, ou peça ao agente que leia SKILL.md diretamente. O procedimento exato de descoberta varia entre clientes, portanto confirme a documentação do seu agente antes de afirmar que a Skill foi carregada.

Há uma limitação importante do espelho: o SKILL.md aponta para classes PHP e para outras Skills do monorepositório WooCommerce. Esses caminhos relativos não estão dentro do ZIP. Abra o diretório oficial no commit fixado ao consultar essas referências. O botão de repositório da página é uma ação separada do download local.

Configuração antes do primeiro pedido

Defina no pedido ao agente qual repositório e branch ele pode ler, qual versão do WooCommerce está instalada, se a mudança é uma rota nova ou uma alteração de contrato, e quais arquivos pode editar. Forneça um ambiente descartável, dados sintéticos e testes existentes. Comece com leitura e proposta de diff. Não entregue credenciais administrativas, pagamentos reais, dados de clientes nem banco de produção para uma tarefa de documentação ou revisão.

A Skill remete a woocommerce-backend-dev para convenções gerais e a woocommerce-performance para padrões de cache. Essas outras Skills não integram este ZIP. Se a tarefa depender delas, leia as versões oficiais no mesmo commit e registre quais recomendações foram adotadas. O pacote não autoriza instalar plugins adicionais automaticamente.

Primeiro uso verificável

Um teste seguro é pedir: “No meu branch de desenvolvimento, localize a rota de leitura de produtos da Store API, descreva o esquema que ela anuncia, compare com a resposta produzida e proponha um teste para qualquer divergência. Não edite arquivos nem faça requisições de escrita.” O resultado esperado é um relatório com caminhos e linhas conferíveis, hipóteses separadas de fatos e um plano de teste. Depois da revisão, autorize uma alteração pequena em branch próprio e execute a suíte de testes do projeto.

Para uma rota que altera carrinho, peça que o agente justifique a classe base, o modelo de sessão, a proteção contra CSRF e os códigos de erro. A documentação oficial de nonce mostra que operações de escrita exigem proteção específica. O documento authentication.md da Skill alerta que estender a classe genérica sem proteção equivalente pode abrir uma superfície de CSRF. Não trate uma resposta 200 em teste feliz como prova de segurança.

Esquema, variações e desempenho

O documento schema-design.md recomenda tratar o esquema como contrato público: cada campo anunciado deve corresponder ao que a rota devolve, inclusive unidades, sanitização e valores limitados pelo servidor. rest-conventions.md separa coleção, item e ação, além de pedir semântica explícita para operações repetidas. variation-handling.md orienta reconciliar atributos de variação no servidor em vez de confiar na identidade enviada pelo cliente. São decisões que exigem inspeção do código real, não apenas aceitar o texto gerado.

performance.md situa o cache priming no caminho das respostas da Store API e aponta para uma Skill de desempenho adicional, não empacotada aqui. Isso não equivale a um benchmark. Meça consultas e tempo de resposta em um ambiente controlado antes de dizer que a alteração melhorou a loja. A documentação de extensão da Store API ajuda a decidir quando ampliar um esquema existente e quando criar uma rota própria.

Permissões, riscos e limites

Instalar este ZIP apenas disponibiliza texto ao agente. O risco aparece quando o agente recebe permissão para ler dados privados, editar PHP, acionar uma API, executar testes com efeitos ou implantar a alteração. Delimite cada permissão. Uma rota pública não deve expor configuração interna ou dados de outro comprador. Uma rota de escrita precisa de autorização, proteção de intenção da requisição e teste negativo. Revisão de segurança e compatibilidade da versão são responsabilidades da equipe que mantém a loja.

O material nasceu dentro do monorepositório oficial do WooCommerce; sua orientação é específica para esse código e pode mudar. Este espelho documental não inclui o plugin nem afirma que o Bastidores executou uma loja, mediu desempenho ou validou uma extensão real. Para APIs administrativas, a Store API não é o atalho correto: consulte a documentação oficial da API autenticada.

Erros comuns e como investigar

Se o agente não carregar a Skill, confirme o nome da pasta, a presença de SKILL.md na raiz dessa pasta e o caminho de descoberta suportado pelo cliente. Se um link relativo para PHP não abrir no ZIP, use o repositório oficial fixado, pois o código executável foi excluído deliberadamente. Se uma requisição de escrita devolver erro de nonce, verifique o fluxo de sessão, cabeçalhos e classe base antes de desativar a proteção. Se o esquema e a resposta divergirem, trate isso como quebra de contrato potencial e acrescente um teste que reproduza o caso. Se uma variação errada for adicionada ao carrinho, confira a reconciliação dos atributos no servidor e não apenas o payload do navegador.

Origem, licença e download

Os seis documentos vieram do repositório oficial do WooCommerce no commit indicado. O aviso de licença do repositório permite redistribuição sob GNU GPL versão 2 ou posterior, sem garantia. O ZIP local inclui esse aviso e ORIGEM.md com hashes dos arquivos. Confira o SHA-256 do pacote no card e considere o repositório como fonte atual para correções futuras.