O que mostra publicamente a sua loja

Módulo 2: Instalar e configurar · Tempo de leitura: 10 minutos

Objetivo de aprendizagem: Depois desta lição, saberá explicar o que são a Store API e a API REST do WooCommerce, que dados devem ser públicos e quais não devem, e como utilizar chaves da API e webhooks com segurança.

Conceitos-chave: API, API REST do WordPress, Store API (wc/store/v1), API REST do WooCommerce (wc/v3), JSON, público e protegido, chave da API, permissões de leitura e escrita, privilégio mínimo, webhook, chave secreta de um webhook, X-WP-Total

Uma loja com duas portas

Um visitante vê a sua loja como páginas web. Mas a sua loja também tem "portas" para programas: endereços onde um programa pode pedir ou enviar dados, sem o aspeto gráfico de uma página. Uma porta destas chama-se API (application programming interface). O WordPress tem uma em /wp-json/, a API REST. O curso de WordPress mostrou na lição 7.3 que aí é possível, por exemplo, obter nomes de utilizador se nada estiver protegido.

O WooCommerce acrescenta duas API próprias, com finalidades muito diferentes:

A Store API é, portanto, a entrada da montra: o que está numa página de produto da sua loja também está ali, só que em forma de dados. A API REST do WooCommerce é a porta das traseiras do armazém: essa deve estar fechada à chave.

A Store API: o que um visitante (e qualquer pessoa) pode consultar

Abra no seu navegador:

https://shop.example.com/wp-json/wc/store/v1/products

Obtém uma lista em JSON, um formato de texto para dados. Para cada produto vê, entre outros, o nome, o slug, o tipo (simples, variável), o endereço da página do produto (permalink), o SKU, os preços, as imagens, as categorias, se está em stock e se está à venda. Nos cabeçalhos da resposta encontra X-WP-Total: o número de produtos que a loja mostra aos visitantes.

Algumas coisas a saber:

• Os preços estão em cêntimos. Um bule de € 34,95 aparece como "price": "3495" com "currency_minor_unit": 2. Divida por 100. Se é o preço com ou sem IVA depende da sua definição em "Mostrar preços na loja" (lição 4.1). Usamos esta característica no exercício da lição 4.1.
• Apenas o que está visível. A Store API não conta os produtos em rascunho, privados ou ocultos no catálogo. Por isso, X-WP-Total pode ser inferior ao número que vê na administração.
• Ler é permitido a todos, escrever não é tão simples. Adicionar algo ao carrinho ou finalizar a compra através da Store API só é possível com um código de utilização única (nonce) retirado da página, e apenas para o carrinho do próprio visitante.

É grave que isto seja público? Não: são os mesmos dados que constam das suas páginas de produto. Um concorrente que queira acompanhar os seus preços pode fazê-lo também com as páginas normais. Convém, no entanto, ter presente: tudo o que colocar num campo de produto pode acabar na Store API. Nunca coloque preços de compra, nomes de fornecedores ou notas internas na descrição curta ou longa "porque o tema não mostra esse campo de qualquer forma".

Também não feche a Store API. Os blocos de carrinho e de finalização da compra precisam dela (lição 2.2). Plugins de segurança que "desativam a API REST para visitantes" acabam, por isso, por vezes, por impedir a finalização da compra. Se quiser restringir a API REST, deixe a Store API de fora dessa restrição.

Existe abuso da Store API, mas do lado da escrita: atacantes que, com números de cartão roubados, tentam milhares de pequenas encomendas. Chama-se card testing; esse é o tema da lição 6.3.

A API REST do WooCommerce: sempre protegida por uma chave

Abra agora, sem sessão iniciada:

https://shop.example.com/wp-json/wc/v3/orders

A resposta correta é uma mensagem de erro com o estado 401 (sem sessão iniciada) e um código como woocommerce_rest_cannot_view. A sua loja diz: "não tem permissão para ver isto". É assim que deve ser. Se aqui obtiver uma lista de encomendas, há algo gravemente errado: um plugin que abre permissões, código personalizado no tema ou uma chave que está num endereço público. Nesse caso, tem uma possível violação de dados (curso de WordPress, lição 7.5, e base de conhecimento 6749).

Os programas que precisam de aceder às suas encomendas recebem uma chave da API. Cria-a em WooCommerce > Configurações > Avançado > API REST (Advanced > REST API). Uma chave é composta por duas partes (uma consumer key e um consumer secret) e pertence a um utilizador do WordPress. Escolhe as permissões:

• Leitura: o programa pode consultar dados;
• Escrita: o programa pode criar e alterar dados;
• Leitura/Escrita: ambos.

Regras a seguir sempre:

1. Privilégio mínimo. Uma ligação à contabilidade que apenas obtém encomendas recebe apenas leitura. Uma ligação de stock que atualiza o stock precisa de escrita, mas uma ferramenta de relatórios não.
2. Uma chave por ligação, com uma descrição clara ("Contabilidade, só leitura, 2026"). Se uma ligação deixar de ser usada, revoga apenas essa chave.
3. Associe a chave a um utilizador com as permissões adequadas. A chave de um administrador pode fazer tudo o que um administrador pode. É preferível criar um utilizador separado com a função Gestor de loja (lição 6.2).
4. Guarde a metade secreta em segurança. Só a vê uma vez, ao criá-la. Deve ficar nas configurações do programa ou num gestor de palavras-passe, não num e-mail, num documento partilhado ou num repositório de código público.
5. Faça limpeza. Em API REST vê, para cada chave, quando foi utilizada pela última vez. Uma chave que não é usada há meses deve ser revogada.

Webhooks: a sua loja contacta outro programa

Uma API espera que alguém pergunte. Um webhook funciona ao contrário: quando ocorre um acontecimento na sua loja (uma nova encomenda, um produto alterado), o próprio WooCommerce envia uma mensagem para um endereço que indicar. Assim, o seu programa de envios sabe de imediato que há uma encomenda, sem ter de perguntar a cada minuto. Configura-os em WooCommerce > Configurações > Avançado > Webhooks.

Três pontos de atenção:

• A mensagem contém dados pessoais. Um webhook de nova encomenda envia o nome, a morada e os produtos encomendados. Envie isso apenas para um endereço com https e para uma entidade que conste da sua política de privacidade e do seu registo de atividades de tratamento (lição 5.5).
• A chave secreta. Num webhook, preenche uma chave secreta. Com ela, o programa recetor pode verificar que a mensagem vem realmente da sua loja e não de alguém que adivinhou o endereço. Não a deixe em branco e partilhe-a apenas com o destinatário.
• Entrega falhada. Se o endereço de destino estiver inacessível durante algum tempo, o WooCommerce pode desativar o webhook após falhas repetidas. Depois de uma avaria, verifique em Webhooks se continuam ativos.

Não confunda isto com o webhook do seu fornecedor de pagamentos (lição 4.4). Esse funciona ao contrário: o fornecedor informa a sua loja de que um pagamento foi bem-sucedido.

Na prática: é assim no WooCommerce

Noutros fornecedores de alojamento funciona da mesma forma; trata-se de componentes do próprio WooCommerce.

1. Abra numa janela privada /wp-json/wc/store/v1/products na sua loja (de teste). Procure um produto e converta o preço.
2. Abra na mesma janela privada /wp-json/wc/v3/orders. Deverá ver o estado 401.
3. Aceda a WooCommerce > Configurações > Avançado > API REST. Veja que chaves existem, de que utilizador e com que permissões. Revogue as chaves que não reconhece (ou já não usa).
4. Em Webhooks, veja que webhooks existem e para que endereço são enviados.
5. Se tiver um plugin de segurança que restringe a API REST, confirme que a Store API está excluída dessa restrição.

Resumo

• A Store API (wc/store/v1) é pública e contém o mesmo que as suas páginas de produto; os blocos de carrinho e de finalização da compra precisam dela.
• Não coloque dados internos em campos de produto: podem ficar visíveis através da Store API.
• A API REST do WooCommerce (wc/v3) deve responder com 401 sem chave; uma lista de encomendas sem chave é uma possível violação de dados.
• Chaves da API: privilégio mínimo, uma por ligação, associada a um utilizador adequado, guardada em segredo, e revogar as não utilizadas.
• Os webhooks enviam dados pessoais para outro programa: apenas por https, com uma chave secreta, para uma entidade do seu registo de atividades de tratamento.

Questionário

Exercício

Exercício A2.4: O que mostra publicamente a sua loja? Introduza o endereço da sua loja (de teste) e o número de produtos visíveis na sua loja. O programa faz três pedidos, sem cookies e sem chave, apenas de leitura:

1. /wp-json/wc/store/v1/products?per_page=1 (a Store API, através do endereço REST indicado pelo próprio site);
2. /wp-json/wc/v3/orders?per_page=1;
3. /wp-json/wc/v3/customers?per_page=1.

Correto é: a Store API responde com o estado 200 e uma lista JSON; o cabeçalho X-WP-Total é igual ao número que introduziu; orders e customers devolvem 401, 403 ou 404.

Laranja: X-WP-Total é diferente (os produtos em rascunho, privados ou ocultos não contam); a Store API devolve 401 ou 403, normalmente por causa de um plugin de segurança, o que impede o funcionamento dos blocos de finalização da compra.

Vermelho: a Store API não está acessível, embora o seu site utilize o WooCommerce; ou orders ou customers devolvem uma lista. Este último caso é grave: feche o acesso de imediato, verifique as suas chaves da API e os plugins, e avalie se tem de notificar uma violação de dados. Nesse caso, o programa guarda apenas o código de estado, nunca o conteúdo.

Depois, verifique pessoalmente em API REST e Webhooks: que chaves e webhooks existem e sabe para que serve cada um?

Para saber mais

• Curso gratuito de WordPress 7.3: Iniciar sessão: palavras-passe, autenticação de dois fatores e força bruta
• Curso gratuito de WordPress 7.5: Site pirateado: reconhecer, recuperar e prevenir
• Não é possível aceder ao xmlrpc.php do WordPress
• Trata-se de uma violação de dados e tenho de a comunicar?
• A Store API (developer.woocommerce.com, em inglês): https://developer.woocommerce.com/docs/apis/store-api/
• Limitação de pedidos (rate limiting) da Store API (developer.woocommerce.com, em inglês): https://developer.woocommerce.com/docs/apis/store-api/rate-limiting/