# 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,…

- Página: <https://www.datafirefly.com/pt/documentation/dfcheckoutfields/>
- Idioma: pt
- Atualizado em: 2026-09-30
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfcheckoutfields/index.md), [en](https://www.datafirefly.com/en/documentation/dfcheckoutfields/index.md), [es](https://www.datafirefly.com/es/documentation/dfcheckoutfields/index.md), [de](https://www.datafirefly.com/de/documentation/dfcheckoutfields/index.md), [it](https://www.datafirefly.com/it/documentation/dfcheckoutfields/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfcheckoutfields/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfcheckoutfields/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## 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.