Custom Checkout Fields: documentação

Apresentação

O DataFirefly Custom Checkout Fields acrescenta campos personalizados ao checkout e ao formulário de registo do PrestaShop 8 e 9: número da ordem de compra, data de entrega pretendida, SIRET, setor de atividade, anexo ou qualquer outro campo que criar. Os valores são verificados antes da confirmação da encomenda e depois levados para a página da encomenda, a fatura PDF, a guia de remessa, os e-mails, as listas do back office, as exportações CSV e o webservice.

Instalação

1. No back office, abra Módulos > Gestor de módulos e clique em Carregar um módulo.
2. Selecione o ficheiro dfcheckoutfields.zip.
3. A instalação cria três tabelas, a pasta protegida upload/dfcheckoutfields, os menus Encomendas > Campos personalizados e Encomendas > Exportar campos, e cinco campos prontos a usar.
4. Clique em Configurar para definir as opções gerais.

Para atualizar, carregue o novo ZIP por cima do anterior: os scripts de atualização acrescentam as novas colunas sem alterar os seus campos nem os valores guardados.

Campos criados na instalação

• Número da ordem de compra (po_number): texto até 50 caracteres, guardado na encomenda, visível na fatura, na guia de remessa e como coluna da lista de encomendas.
• Data de entrega pretendida (desired_date): no mínimo hoje + 2 dias, apenas dias úteis.
• Número SIRET (siret): verificado pela chave de Luhn, guardado na conta de cliente, pedido no registo e no checkout, limitado a clientes de França.
• Setor de atividade (sector): lista de oito setores, guardada na conta de cliente, pedida no registo.
• Anexo (attachment): PDF, imagens e documentos Office, máx. 8 MB.

Nenhum destes campos é obrigatório por predefinição. Altere-os, desative-os ou elimine-os conforme as suas necessidades.

Definições gerais

Módulos > Gestor de módulos > Campos personalizados de encomenda e registo > Configurar.

• Posição do bloco no checkout: passo de pagamento, acima dos métodos de pagamento (predefinição), ou passo de envio, abaixo das transportadoras. Carrinhos só com produtos virtuais usam sempre o passo de pagamento.
• Título do bloco: apresentado no checkout, nas páginas de encomenda, nos PDF e nos e-mails, por idioma.
• Posição na fatura PDF: cabeçalho abaixo do número da fatura, ou fundo da fatura. Consulte Fatura e guia de remessa.
• Nota privada se faltar um campo obrigatório: acrescenta a lista dos campos em falta à nota privada da encomenda quando um módulo de pagamento contorna a verificação.
• Copiar os campos SIRET para o SIRET nativo do cliente: mantém atualizado o campo SIRET da ficha do cliente, usado pelo modo B2B do PrestaShop.

Criar ou editar um campo

Encomendas > Campos personalizados, depois Adicionar um campo ou o lápis de uma linha. O formulário mostra apenas as opções úteis para o tipo e o armazenamento escolhidos.

Campo

• Rótulo, texto de exemplo e texto de ajuda: por idioma. Um idioma vazio usa o rótulo do idioma predefinido.
• Código: identificador técnico em minúsculas, algarismos e sublinhados. Serve também de variável de e-mail {dfcf_CODE} e no webservice.
• Tipo: texto, texto de várias linhas, número, e-mail, data, lista pendente, caixa de seleção, SIRET ou ficheiro.
• Guardado em: Encomenda (um valor por encomenda) ou Conta de cliente (valor guardado na ficha do cliente, pré-preenchido no checkout e copiado para cada encomenda).
• Opções da lista: uma opção por linha no formato chave|Rótulo, por exemplo industry|Indústria. Mantenha as mesmas chaves em todos os idiomas.

Onde e quando

• Mostrar no registo e obrigatório no registo: apenas campos da conta de cliente, sem o tipo ficheiro. Também aparecem no formulário Dados pessoais da conta.
• Mostrar no checkout e obrigatório no checkout.
• Mostrar apenas se: consulte Apresentação condicional.
• Países: país da morada de faturação no checkout, do visitante no registo. Vazio para todos os países.
• Grupos de clientes: tudo desmarcado para todos os grupos.

Validação

• Comprimento máximo: 0 para a predefinição (255 caracteres, 2000 em várias linhas).
• Padrão de validação: expressão regular sem delimitadores, por exemplo ^[A-Z]{2}[0-9]{6}$.
• Prazo mínimo e horizonte máximo em dias para uma data guardada na encomenda.
• Apenas dias úteis: recusa sábado e domingo.
• Dias de encerramento: um por linha, 2026-12-24 para um dia, 2026-08-01:2026-08-21 para um período, 12-25 para todos os anos.
• Extensões permitidas e tamanho máximo para um ficheiro. Scripts e executáveis são sempre recusados.

Documentos e exportações

Mostrar ao cliente (confirmação, conta de cliente, e-mails ao cliente), na fatura PDF, na guia de remessa, como coluna filtrável das listas do back office, nas exportações CSV.

Lista de campos

Os ícones da lista ativam ou desativam uma definição com um clique. Arraste as linhas para mudar a ordem. A ação Duplicar cria uma cópia desativada com o código code_copy. Um campo com valores em encomendas não pode ser eliminado: desative-o para conservar o histórico.

Apresentação condicional

Exemplo: mostrar o SIRET apenas às empresas.

1. Crie um campo Caixa de seleção guardado na conta de cliente, código is_company, rótulo Sou uma empresa.
2. Edite o campo SIRET, secção Onde e quando, e escolha Mostrar apenas se: Sou uma empresa. Deixe vazio «tem um destes valores»: numa caixa de seleção significa marcada.

Para uma lista pendente, indique as chaves esperadas separadas por vírgulas, por exemplo health,public. As condições encadeiam-se: um campo cujo campo pai está oculto também fica oculto. Um campo oculto nunca é obrigatório e o seu valor não é guardado. O campo pai tem de ser apresentado no mesmo sítio (registo ou checkout) ou já estar preenchido na conta de cliente.

Do lado do cliente

No checkout

O bloco aparece no passo escolhido. Cada valor é guardado durante a escrita. Enquanto um campo obrigatório estiver vazio ou inválido, o clique em Encomendar (ou Continuar no passo de envio) fica bloqueado, a mensagem aparece abaixo do campo e a página desloca-se até ele. O anexo envia-se por arrastar ou com um clique, com barra de progresso. O cliente pode removê-lo e enviar outro.

No registo e em Dados pessoais

Os campos da conta de cliente marcados Mostrar no registo são acrescentados ao formulário nativo de criação de conta, ao formulário de convidado do checkout e ao formulário Dados pessoais. Os erros aparecem como os dos campos do PrestaShop.

Depois da encomenda

Os valores marcados Mostrar ao cliente aparecem na página de confirmação e no detalhe da encomenda da conta de cliente. O cliente dono da encomenda pode descarregar aí o anexo.

Fatura e guia de remessa

Fundo da fatura: o módulo usa o hook displayPDFInvoice e imprime uma tabela depois dos totais. Nenhum ficheiro é alterado.

Cabeçalho, abaixo do número da fatura: o PrestaShop não tem hook nesse local. Ao guardar esta definição, o módulo acrescenta um bloco delimitado por {* dfcf:start *} e {* dfcf:end *} no fim de themes/O_SEU_TEMA/pdf/invoice.summary-tab.tpl. Se o ficheiro não existir, é criado a partir do do PrestaShop. Se já existir, o módulo completa-o e guarda uma cópia .dfcf-backup. Voltar a Fundo da fatura ou desinstalar remove o bloco. Se o ficheiro não puder ser alterado, uma mensagem indica o seu caminho.

Com o DataFirefly Invoice Editor, que substitui a apresentação da fatura, use Fundo da fatura: o editor mantém o conteúdo dos módulos na posição que escolher.

A guia de remessa usa o hook displayPDFDeliverySlip, campo a campo.

E-mails

Nos e-mails que contêm o ID da encomenda, entre eles order_conf e new_order, há dois tipos de variáveis:

• {dfcf_fields}: todos os valores numa tabela. Em order_conf apenas os campos marcados Mostrar ao cliente, em new_order, destinado ao comerciante, todos os campos.
• {dfcf_CODE}: um só valor, por exemplo {dfcf_po_number} ou {dfcf_desired_date}.

Acrescente-as em Design > Tema de e-mail, ou nos ficheiros de e-mail do seu tema.

Back office

• Página da encomenda: cartão Campos personalizados com todos os valores. O botão Editar permite corrigir um valor ou substituir o anexo.
• Ficha do cliente: cartão com os campos da conta de cliente, editável da mesma forma.
• Listas: cada campo marcado como coluna filtrável aparece na lista de encomendas com um filtro de texto. Os campos da conta de cliente aparecem também na lista de clientes.

Exportação CSV

Encomendas > Exportar campos. Escolha Encomendas ou Clientes, o período, os estados de encomenda (tudo desmarcado para todos), o separador e se exporta apenas as linhas com pelo menos um valor. O ficheiro está em UTF-8 com BOM e abre diretamente no Excel. As encomendas são exportadas com referência, data, estado, cliente, totais sem e com IVA e moeda, seguidos dos campos marcados Incluir nas exportações CSV.

Webservice

1. Parâmetros avançados > Webservice: ative o webservice e crie ou edite uma chave.
2. Marque GET no recurso dfcf_values.
3. Chame /api/dfcf_values?filter[id_order]=[123]&display=full.

Cada valor é devolvido com id_dfcf_field, id_order, id_customer, id_cart, value, value_display, field_code, field_label e has_file. Os valores do perfil de cliente têm id_order e id_cart a 0.

Anexos e segurança

Cada ficheiro é verificado pela extensão (lista do campo) e pelo conteúdo real: um script renomeado para .pdf é recusado. É guardado em upload/dfcheckoutfields com um nome aleatório e sem extensão, numa pasta cujo acesso direto é proibido por um ficheiro .htaccess. Em Nginx, acrescente a regra location ^~ /upload/dfcheckoutfields/ { deny all; }. O download passa sempre pelo módulo, que verifica se o visitante é o cliente da encomenda ou um funcionário.

RGPD

Os valores guardados numa conta de cliente são eliminados com o cliente. O módulo responde aos pedidos de exportação e eliminação do módulo RGPD oficial do PrestaShop. Os valores copiados para as encomendas ficam com a encomenda.

Resolução de problemas

O bloco não aparece no checkout

Verifique se o campo está ativo, marcado Mostrar no checkout, e se o grupo e o país do cliente correspondem às suas restrições. Se escolheu o passo de envio, verifique se o tema chama o hook displayAfterCarrier.

O botão Encomendar não fica bloqueado

O módulo reconhece o botão dos temas Classic e Hummingbird. Um tema que substitui esse botão por outro elemento, ou um pagamento expresso lançado a partir da página de produto, não está coberto: ative a nota privada para ser avisado das encomendas incompletas.

Os campos não aparecem no cabeçalho da fatura

Verifique se o ficheiro do tema pdf/invoice.summary-tab.tpl pode ser alterado, guarde de novo as definições e limpe a cache em Parâmetros avançados > Desempenho.

Uma variável de e-mail aparece tal como está

Só é preenchida nos e-mails que contêm o ID da encomenda. Verifique também se o código corresponde exatamente ao do campo.