# Indicativo Telefónico Internacional (dfphoneintl)

> Apresentação O DataFirefly International Phone Input (dfphoneintl) acrescenta um seletor de indicativo telefónico com bandeira aos campos Telefone e Telemóvel do PrestaShop, e uniformiza os números no formato internacional E.164…

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

## Apresentação

O DataFirefly International Phone Input (`dfphoneintl`) acrescenta um seletor de indicativo telefónico com bandeira aos campos **Telefone** e **Telemóvel** do PrestaShop, e uniformiza os números no formato internacional E.164 na base de dados. O módulo atua a dois níveis: do lado do navegador para a experiência do utilizador, e do lado do servidor para garantir que qualquer inserção ou atualização de morada, incluindo via API, back-office ou importação, produz um número normalizado.

Formato de armazenamento: para um cliente português que introduza `912345678`, o valor guardado na base de dados é `+351912345678`: indicativo do país, sem espaços nem separadores. Os números portugueses não têm prefixo « 0 » de rede, ao contrário dos franceses ou espanhóis; o módulo trata os dois casos.

## Pré-requisitos

- PrestaShop 8.0.0 a 9.99.99
- PHP 7.4 no mínimo (8.1+ recomendado)
- Nenhuma dependência externa: o módulo não incorpora nenhuma biblioteca de terceiros

## Instalação

1. Descarregue o arquivo `dfphoneintl-1.0.0.zip` a partir da sua conta de cliente DataFirefly.
2. No back-office PrestaShop, vá a **Módulos → Gestor de módulos → Instalar um módulo**.
3. Arraste e largue o ficheiro ZIP e clique em **Instalar**.
4. O módulo regista-se automaticamente nos hooks necessários. Não é criada nenhuma tabela SQL: o módulo lê os indicativos a partir da tabela nativa `ps_country`.

## Configuração

Vá a **Módulos → Gestor de módulos → DataFirefly International Phone Input → Configurar**. Estão disponíveis três definições:

- **Ativar no campo « Telefone »**: ativa ou desativa o seletor e a normalização no campo `phone`.
- **Ativar no campo « Telemóvel »**: idem para o campo `phone_mobile`.
- **Países preferidos**: lista de códigos ISO2 separados por vírgulas. Estes países são fixados no topo da lista pendente. Valor por defeito: `fr,be,lu,ch,gb,us,de,es,it,nl`; numa loja portuguesa, coloque por exemplo `pt,es,br,fr,gb,de,ch,lu`.

A lista dos países apresentados no seletor provém dos países **ativados** na sua loja (Envio → Zonas geográficas → Países). Um país desativado ou sem indicativo preenchido na coluna `call_prefix` não aparece.

## Funcionamento do lado do cliente

### Páginas em causa

O seletor aparece em todas as páginas do front-office onde figuram campos de telefone: criação de conta, inscrição, gestão das moradas, funil de encomenda (5 etapas e one-page checkout), página de identidade, página de contacto e acompanhamento de encomenda de convidado.

### Sincronização com o país

Quando o cliente muda o país no formulário de morada, o indicativo do seletor atualiza-se automaticamente. Selecionar Espanha passa o indicativo a +34, Brasil a +55, etc. Esta sincronização funciona também nos recarregamentos AJAX do checkout nativo: o módulo escuta os eventos PrestaShop `updatedAddressForm`, `updatedAddress`, `updateCustomerAddressForm` e `changedCheckoutStep`, com um MutationObserver com debounce como rede de segurança para os temas fortemente personalizados.

### Deteção nas moradas existentes

Se o campo já contiver um número em formato internacional (edição de uma morada existente), o módulo deteta o país correspondente por correspondência do indicativo mais longo (longest dial-code match): `+1242...` é reconhecido como Bahamas e não como Estados Unidos.

## Funcionamento do lado do servidor

A normalização no servidor está ligada aos hooks `actionObjectAddressAddBefore` e `actionObjectAddressUpdateBefore`. Antes de cada INSERT ou UPDATE na tabela `ps_address`, os campos `phone` e `phone_mobile` passam pela classe `DfPhoneFormatter`. Isto cobre todos os canais de escrita: formulários do front-office, back-office, webservice, importações CSV e módulos de terceiros que manipulam a classe `Address`.

### Regras de normalização

Para uma morada associada a um país de indicativo +351:

- Número que começa por `+` → conservado tal como está, só os separadores são retirados: `+351 912 345 678` torna-se `+351912345678`.
- Número que começa por `00` → o `00` é substituído por `+`: `00351912345678` torna-se `+351912345678`.
- Número que começa por `0` (prefixo de rede, nos países que o usam como França ou Espanha) → o `0` é retirado e o indicativo é prefixado: `0633547864` com indicativo +33 torna-se `+33633547864`.
- Número que já começa pelo indicativo sem `+` → o `+` é simplesmente acrescentado: `351912345678` torna-se `+351912345678`.
- Outro número composto apenas por algarismos → o indicativo é prefixado: `912345678` torna-se `+351912345678`.

As moradas existentes **não** são modificadas retroativamente na instalação. A normalização aplica-se na próxima gravação de cada morada. Para uma normalização massiva do existente, contacte o suporte: um script SQL que segue a mesma lógica está disponível a pedido.

## Compatibilidade de temas e checkout

- Tema Classic PS 8 (Bootstrap 4) e tema PS 9 (Bootstrap 5) suportados nativamente.
- Checkout em 5 etapas e one-page checkout (OPC) suportados.
- As bandeiras são emojis Unicode (Regional Indicator Symbols): sem sprite nem CDN, renderização nativa por todos os navegadores e SO modernos.
- Multiloja: parâmetros globais, lista de países filtrada por loja.
- Multilingue: nomes dos países apresentados no idioma do visitante.

## Resolução de problemas

### O seletor não aparece

- Verifique que o campo está ativado na configuração do módulo.
- Verifique que o seu tema usa os nomes de campos padrão `phone` / `phone_mobile` (ou `address[phone]` / `address[phone_mobile]`). Para um campo renomeado por um tema personalizado, contacte o suporte.
- Limpe a cache do PrestaShop (Parâmetros avançados → Desempenho) depois da instalação.

### As bandeiras aparecem como letras (PT, ES...)

Comportamento esperado em alguns sistemas Windows antigos que não renderizam os emojis de bandeiras. O indicativo `+351` continua apresentado e o módulo continua plenamente funcional.

### O indicativo não segue a mudança de país

Num tema muito personalizado cujo select de país não usa o nome `id_country`, a sincronização automática não consegue ligar-se. O MutationObserver reinicializa mesmo assim o widget, e o cliente pode escolher manualmente o seu indicativo. Contacte o suporte com o URL da sua loja para uma adaptação.

## Desinstalação

A desinstalação elimina as três chaves de configuração do módulo. Os números já normalizados na base de dados ficam em formato internacional: nenhum dado de cliente é modificado nem eliminado.

## Suporte

Suporte por e-mail incluído, atualizações incluídas durante 12 meses. Garantia de satisfação ou reembolso de 14 dias em todos os módulos DataFirefly.