DataFirefly Digital Product Passport: documentação

Introdução

O plugin DataFirefly Digital Product Passport acrescenta ao WooCommerce tudo o que é necessário para gerar um Passaporte Digital de Produto (DPP) conforme ao Regulamento europeu de Conceção Ecológica para Produtos Sustentáveis (ESPR). Este passaporte torna-se progressivamente obrigatório na União Europeia a partir de 2027, começando pelos têxteis, pelas baterias e pela eletrónica de consumo, antes de se estender a quase todos os produtos colocados no mercado europeu.

Na prática, cada produto WooCommerce ganha um identificador único estável (UUID v4), um QR code nativo, um URL público limpo do tipo /dpp/{uuid}, um registo completo de componentes e materiais, uma linha temporal de rastreabilidade e uma API REST pública. Sem qualquer chamada externa: tudo é gerado no servidor.

Requisitos

• WordPress 6.0 ou superior
• WooCommerce 7.0 ou superior, ativo
• PHP 7.4 no mínimo (testado até ao PHP 8.3)
• Um permalink diferente de «Simples» (Definições → Permalinks)

Instalação

1. Descarregue o ZIP dfdpp-1.0.0.zip a partir da sua conta DataFirefly.
2. Vá a Plugins → Adicionar → Carregar plugin, selecione o ZIP e clique em Instalar agora.
3. Clique em Ativar. As 5 tabelas personalizadas são criadas automaticamente (wp_dfdpp_passports, wp_dfdpp_components, wp_dfdpp_materials, wp_dfdpp_suppliers, wp_dfdpp_events) e as opções predefinidas são colocadas.
4. Se o URL público /dpp/{uuid} não responder de imediato, vá a Definições → Permalinks e clique em Guardar alterações (sem alterar nada) para forçar o flush.

Configuração global

Vá a WooCommerce → Passaporte DPP. Este ecrã reúne todas as definições do plugin.

URL público e QR Code

• Prefixo de URL: por predefinição dpp, o que dá oseudominio.com/dpp/{uuid}. Altere-o se preferir passaporte, product-passport ou outro. Lembre-se de visitar Definições → Permalinks depois da alteração.
• Tamanho do QR: fator de ampliação de 1 a 10. O valor 6 (predefinido) produz cerca de 240 px de lado.
• Margem: número de módulos brancos em redor do QR (4 por predefinição).
• Correção de erros: L / M / Q / H. Fique-se pelo H se o QR for impresso numa etiqueta: até 30% do código pode ficar danificado sem comprometer a leitura.
• Formato preferido: PNG (raster, universal) ou SVG (vetorial, melhor para impressão em grande formato).

Identidade do fabricante por predefinição

Indique aqui as informações que não quer voltar a escrever produto a produto:

• Designação social, morada, país de fabrico
• País predefinido aplicado aos componentes e aos materiais
• Categoria ESPR predefinida (têxtil, bateria, eletrónica, mobiliário, etc.)

Apresentação pública

Cinco interruptores independentes controlam o que os seus clientes veem na página pública do passaporte:

• Pegada de carbono (ativa por predefinição)
• Fornecedores (desativada por predefinição, dados sensíveis)
• Composição material (ativa)
• Reparabilidade e peças sobresselentes (ativa)
• Linha temporal de rastreabilidade (ativa)

Publicação automática

Se assinalar esta opção, cada passaporte passa automaticamente a published quando o próprio produto WooCommerce é publicado. Útil num catálogo de várias centenas de produtos gerido por uma equipa não técnica. Caso contrário, cada passaporte tem de ser publicado manualmente, o que garante um controlo final.

Marca

• Cor de destaque: formato hexadecimal (por exemplo #0f172a). Aplica-se ao bloco de destaque, aos títulos e aos botões da página pública.
• URL do logótipo: apresentado no topo da página pública. Use uma imagem transparente (PNG ou SVG), porque será invertida sobre fundo escuro.

Criar um passaporte para um produto

Abra qualquer produto no WooCommerce. Aparece um novo separador Passaporte DPP no painel de dados do produto (ao lado de Geral, Inventário, Envio, etc.). Reúne 8 secções.

Separador Identificação

O ponto de entrada obrigatório para publicar:

• Estado: Rascunho / Publicado / Arquivado. Só Publicado torna o URL público acessível.
• Categoria ESPR: determina a estrutura de dados que os auditores europeus esperam encontrar. Escolha textile, battery, electronics, furniture, iron_steel, aluminium, tyres, detergents, paints, lubricants, chemicals, cosmetics, toys, construction ou general.
• GTIN / EAN / UPC: o código de barras comercial internacional.
• Referência do modelo, Número de lote, Número de série: preencha os campos aplicáveis ao seu produto.
• Fabricante: nome, morada, país (pré-preenchidos a partir das definições globais, se as tiver configurado).
• Data de fabrico e Local de fabrico (cidade, fábrica ou oficina).

Separador Durabilidade e pegada

• Pegada de carbono: valor numérico, unidade (kgCO2e por predefinição) e metodologia de cálculo de referência (PEF, ISO 14067, GHG Protocol). Só indique a pegada se a conseguir justificar com uma metodologia documentada, porque é o ponto mais escrutinado nas auditorias.
• Índice de reparabilidade: nota em 10.
• Duração de vida prevista em anos.
• Duração da garantia em meses (obrigação de pelo menos 24 meses na UE para os bens de consumo).
• Disponibilidade de peças sobresselentes em anos.
• Conteúdo reciclado em percentagem.
• Conteúdo reciclável em percentagem.

Separador Instruções

Quatro campos ricos que aceitam HTML básico (parágrafos, listas, ligações):

• Utilização: conselhos para tirar o melhor partido do produto e prolongar a sua vida útil.
• Manutenção: lavagem, secagem, armazenamento.
• Reciclagem: fileira de reciclagem, separação seletiva, pontos de recolha.
• Fim de vida: o que fazer quando o produto deixa de ser utilizável.

Separador Conformidade

• Substâncias que suscitam preocupação (SCIP / REACH): lista das substâncias da lista candidata REACH presentes acima de 0,1% em peso. Formato livre, recomenda-se uma lista com marcadores contendo o nome e o número CAS.
• Matérias perigosas: menção das classes de perigo aplicáveis (CLP, GHS).
• Certificações e rótulos: OEKO-TEX, GOTS, GRS, Ecolabel, EPEAT, etc.

Separador Componentes

Registo simples dos componentes que constituem o produto. Para cada componente, acrescenta:

• Nome (obrigatório)
• Tipo: de uma lista predefinida (tecido principal, forro, sola, fivela, fecho, etc.)
• Peso em gramas
• Nome do fornecedor (nunca exposto publicamente, exceto se ativar o interruptor dedicado)
• País de origem em 3 carateres ISO 3166 alpha-3 (por exemplo PRT, ITA, CHN)
• Reciclável: sim / não
• Substituível: sim / não (pertinente para a eletrónica e para o mobiliário)

Separador Materiais

Registo de materiais mais granular, com os códigos normalizados:

• Código do material: menu pendente com os principais códigos ISO 11469 / ISO 1043 para os plásticos (PET, PP, PE, PVC, PS, PA, etc.), ISO 1833 para os têxteis (WO lã, CO algodão, PL poliéster, VI viscose, EL elastano, etc.), DIN 6120 para os metais, e as químicas de bateria (Li-ion, LFP, NMC, NCA, NiMH, Pb).
• Nome personalizado: se o código predefinido não servir.
• Percentagem: parte deste material no produto (até 4 decimais).
• Reciclado e % reciclado: se se trata de conteúdo reciclado e, em caso afirmativo, em que proporção.
• Renovável: matéria de origem biológica renovável.
• N.º CAS: identificador CAS da substância (para as substâncias químicas reguladas).

Separador Rastreabilidade

Linha temporal dos eventos-chave do ciclo de vida. Cada evento associa uma data, um tipo, um interveniente, um local e uma descrição. Os tipos disponíveis cobrem todo o ciclo:

• Produção
• Controlo de qualidade
• Transporte
• Importação / Exportação
• Distribuição
• Venda
• Reparação
• Recondicionamento
• Reciclagem
• Fim de vida

Separador QR Code

Este separador fica ativo assim que o produto é guardado pela primeira vez. Apresenta:

• O QR code gerado (pré-visualização em data-URI)
• O UUID do passaporte
• O URL público clicável
• Três botões de descarregamento: PNG, SVG e JSON em bruto

Publicar um passaporte

Um passaporte no estado Rascunho não é acessível publicamente: o URL devolve um 404. Para o publicar:

1. Abra o produto e vá ao separador Passaporte DPP → Identificação.
2. Coloque o Estado em Publicado.
3. Clique em Atualizar no topo à direita do produto.

A data da primeira publicação é memorizada automaticamente em published_at. Um passaporte publicado pode voltar a Rascunho ou passar a Arquivado a qualquer momento.

Página pública do passaporte

O URL do tipo oseudominio.com/dpp/8f3a2c1d-4b5e-6f7a-8b9c-0d1e2f3a4b5c abre uma página responsiva com:

• Um bloco de destaque com o nome do produto, a categoria ESPR, o logótipo da marca e a imagem do produto
• Uma faixa de identificadores (UUID, GTIN, modelo, lote, série, SKU)
• Um cartão de fabricante com morada e data de produção
• Um cartão de durabilidade e pegada com as métricas em mosaicos
• As tabelas de componentes e de materiais (conforme os interruptores de apresentação)
• As instruções (utilização, manutenção, reciclagem, fim de vida)
• A conformidade regulamentar (certificações, substâncias, matérias perigosas)
• Uma linha temporal de rastreabilidade vertical com datas e locais
• Uma barra lateral com o QR code e descarregamento em PNG / SVG / JSON
• Um bloco JSON-LD schema.org Product injetado automaticamente para o SEO e para a interoperabilidade

Na ficha de produto pública do WooCommerce, um bloco discreto convida os visitantes a consultar o passaporte, com um QR em miniatura. Este bloco é acrescentado automaticamente por baixo do resumo do produto (hook woocommerce_after_single_product_summary, prioridade 25).

Formatos alternativos

O mesmo URL aceita dois sufixos:

• /dpp/{uuid}?dfdpp_format=json ou /dpp/{uuid}.json: devolve o payload JSON completo, incluindo o bloco JSON-LD.
• /dpp/{uuid}?dfdpp_format=qr ou /dpp/{uuid}/qr: descarrega diretamente o QR code em PNG.

API REST

Todos os endpoints estão expostos no namespace dfdpp/v1.

Endpoints públicos

• GET /wp-json/dfdpp/v1/passport/{uuid}: devolve o payload JSON completo do passaporte.
• GET /wp-json/dfdpp/v1/passport/by-product/{product_id}: o mesmo, mas pesquisado pelo identificador de produto do WooCommerce.
• GET /wp-json/dfdpp/v1/passport/{uuid}/qr: devolve o QR code em SVG vetorial.

Estes endpoints só devolvem os passaportes no estado Publicado.

Endpoints autenticados

Exigem uma autenticação por Application Password ou OAuth e a permissão manage_woocommerce ou edit_products:

• PATCH /wp-json/dfdpp/v1/passport/{product_id}: atualiza parcialmente os campos de um passaporte.
• POST /wp-json/dfdpp/v1/passport/{product_id}/publish: publica o passaporte (atalho sem passar pela administração).

Personalização

Substituir a página pública

Copie o public/templates/dpp-public.php do plugin para uma pasta dfdpp/ na raiz do seu tema ativo. O plugin passa a usar prioritariamente esse ficheiro, o que lhe permite refazer por completo a apresentação sem tocar no plugin. A lógica de obtenção dos dados mantém-se inalterada: dispõe das variáveis $passport e $data exatamente como no template original.

Filtro do payload JSON

O filtro dfdpp_passport_payload permite acrescentar ou alterar campos na carga JSON exposta. Exemplo: acrescentar um campo próprio internal_reference visível apenas para o seu ERP.

add_filter( 'dfdpp_passport_payload', function ( $data, $passport ) {
    $data['custom'] = array(
        'internal_reference' => get_post_meta( $passport->product_id, '_erp_ref', true ),
    );
    return $data;
}, 10, 2 );

Bloco na ficha de produto

O bloco que convida a consultar o passaporte na ficha de produto pública do WooCommerce pode ser deslocado, desativado ou substituído manipulando o hook:

// Retirá-lo por completo
remove_action( 'woocommerce_after_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

// Colocá-lo noutro sítio, por exemplo por cima do botão Adicionar ao carrinho
add_action( 'woocommerce_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

Traduções

O plugin é entregue com uma tradução francesa completa (languages/dfdpp-fr_FR.po e .mo) e um ficheiro modelo dfdpp.pot (291 cadeias únicas) para traduzir para outros idiomas com o Poedit ou qualquer ferramenta compatível com gettext.

O Polylang Pro e o WPML são suportados para a tradução dos conteúdos de produto (nome, descrição, categoria ESPR). O passaporte mantém-se associado ao produto de origem, o que garante uma única fonte de verdade para os dados de conformidade, permitindo ao mesmo tempo uma apresentação multilingue da página pública.

Compatibilidade HPOS

O plugin declara explicitamente a compatibilidade com o armazenamento de encomendas de alto desempenho do WooCommerce (High-Performance Order Storage). Não guarda qualquer dado no custom post type shop_order: as 5 tabelas dedicadas são independentes. Pode ativar o HPOS sem receio de incompatibilidade com o plugin.

FAQ e resolução de problemas

O URL público devolve um 404

Três causas possíveis:

• O passaporte está no estado Rascunho ou Arquivado: coloque-o em Publicado.
• As rewrite rules não foram atualizadas: vá a Definições → Permalinks e guarde (sem alterar nada).
• Está ativo um permalink «Simples»: mude para «Nome da publicação» ou qualquer outro formato não simples.

O QR code não aparece

Verifique que o seu alojamento autoriza a escrita no diretório wp-content/uploads/ e que a extensão GD está ativa no PHP (necessária para a geração de PNG). Se estiver num ambiente limitado, force o formato SVG nas definições, porque não depende do GD.

Como fornecer a rastreabilidade a um parceiro externo?

Use a API REST. Crie um Application Password dedicado ao parceiro na conta de utilizador WordPress dele (Utilizadores → Perfil → Application Passwords), e forneça-lhe a documentação de um endpoint PATCH para que envie os seus próprios eventos de rastreabilidade ao longo do tempo.

Posso gerar os QR codes em massa?

Sim, através do WP-CLI. Um script personalizado pode percorrer os produtos e chamar o DFDPP_QRCode::output_png() ou o ::as_svg() para gerar os ficheiros. Contacte o suporte se quiser que lhe forneçamos um comando WP-CLI chave na mão para o seu catálogo.

Funciona com produtos variáveis?

Sim, o passaporte fica associado ao produto principal. Se precisar de um passaporte distinto por variação (típico na eletrónica, em que cada configuração tem uma pegada de carbono diferente), contacte-nos para falarmos de uma extensão.

Desinstalação

A simples desativação do plugin conserva todos os dados. Os seus passaportes ficam na base de dados, prontos a ser reativados.

A desinstalação completa (botão Eliminar na página de plugins) aciona o uninstall.php, que:

• Elimina as 5 tabelas personalizadas
• Elimina todas as opções dfdpp_*
• Limpa os eventuais transientes
• Faz flush às rewrite rules

Suporte

O suporte técnico é assegurado por e-mail em francês e em inglês. Escreva para support@datafirefly.com indicando a versão do plugin, a versão do WordPress e do WooCommerce, e um excerto dos registos se tiver uma mensagem de erro do PHP.