# DfAddressAutocomplete: preenchimento automático de moradas para Shopware 6

> Apresentação O DfAddressAutocomplete acrescenta uma pesquisa instantânea de moradas aos formulários de morada do Shopware 6: checkout, livro de moradas da conta de cliente e registo. O cliente escreve o…

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

## Apresentação

O DfAddressAutocomplete acrescenta uma pesquisa instantânea de moradas aos formulários de morada do Shopware 6: checkout, livro de moradas da conta de cliente e registo. O cliente escreve o início da morada, seleciona uma sugestão e todos os campos se preenchem automaticamente: rua, complemento, código postal, localidade e país.

Estão incluídos dois fornecedores: **BAN** (Base Adresse Nationale, gratuita, França) e **Google Places (New)** (pago, mundial). A arquitetura é extensível: qualquer API de moradas pode ser ligada através de uma interface PHP.

A BAN cobre apenas as moradas francesas. Para uma loja que venda em Portugal, o fornecedor a configurar é o Google Places, com a restrição de país `PT`.

## Pré-requisitos

- Shopware 6.6 ou 6.7
- PHP 8.2 no mínimo
- Para o Google Places: uma chave de API Google Cloud com a **Places API (New)** ativada (não a antiga Places API)

## Instalação

1. Carregue o ZIP para `custom/plugins/` ou pela administração do Shopware (Extensões → As minhas extensões → Carregar uma extensão).
2. Execute os seguintes comandos:

```
bin/console plugin:refresh
bin/console plugin:install --activate DfAddressAutocomplete
bin/console cache:clear
```

1. Compile o storefront para que o JavaScript e o CSS sejam integrados:

```
./bin/build-storefront.sh
```

Nos ambientes sem script de build, use `bin/console theme:compile` depois de ter compilado os recursos uma primeira vez.

## Configuração

Vá a **Extensões → As minhas extensões → DfAddressAutocomplete → Configurar**. Todas as definições podem ter âmbito por sales channel.

### Fornecedor

- **Fornecedor de preenchimento automático**: BAN (por predefinição) ou Google Places.
- **Chave de API Google Places**: necessária apenas se o Google estiver selecionado. A chave fica do lado do servidor e nunca é enviada ao navegador.
- **Restrição de país**: códigos ISO 3166-1 alpha-2 separados por vírgulas (por exemplo `PT,ES,FR`). Vazio = sem restrição. A restrição só se aplica ao Google (a BAN é, por natureza, apenas França).

### Páginas de ativação

Três interruptores independentes: **checkout**, **conta de cliente** (livro de moradas) e **registo**. Cada um ativa-se ou desativa-se em separado.

### Comportamento

- **Caracteres mínimos** (predefinição 3): nenhuma pesquisa abaixo deste limiar.
- **Atraso antirressalto** (predefinição 250 ms): tempo de espera após a última tecla antes de consultar a API.
- **Sugestões máximas** (predefinição 5).
- **Cache de servidor** (ativa por predefinição): 5 minutos nas pesquisas, 15 minutos nos detalhes. Reduz a faturação da Google e a latência.

## Configurar o Google Places

1. Na [Google Cloud Console](https://console.cloud.google.com/), crie ou selecione um projeto.
2. Ative a **Places API (New)**; atenção, não a antiga «Places API».
3. Crie uma chave de API e restrinja-a **por endereço IP de servidor** (o do seu alojamento Shopware). Não a restrinja por referrer HTTP: o tráfego é de servidor para servidor.
4. Cole a chave na configuração da extensão.

A API Places (New) é faturada à utilização. A cache de servidor da extensão e o antirressalto limitam o número de chamadas, mas vigie o seu consumo na consola da Google.

## Funcionamento do lado do cliente

Aparece um campo de pesquisa acima do formulário de morada normal. A navegação por teclado é completa: setas para cima e para baixo para percorrer as sugestões, Enter para selecionar, Esc para fechar. Na seleção, os campos normais do Shopware são preenchidos e o país é selecionado automaticamente na lista pendente.

## Acrescentar um fornecedor personalizado

Implemente a interface `AutocompleteProviderInterface` (namespace `DataFirefly\DfAddressAutocomplete\Provider`) na sua própria extensão:

```
final class MapboxProvider implements AutocompleteProviderInterface
{
    public function getKey(): string { return 'mapbox'; }

    public function search(string $query, int $limit, string $salesChannelId, array $countryCodes = []): array
    {
        // Consulte a sua API e devolva um array de AddressSuggestion
    }

    public function details(string $id, string $salesChannelId): ?AddressDetails
    {
        // Resolva o id num AddressDetails completo
    }
}
```

Depois marque o serviço no seu services.xml (id do serviço = classe completa do seu fornecedor):

```
<service id="My\Plugin\MapboxProvider">
    <tag name="df_address_autocomplete.provider"/>
</service>
```

Cada sugestão transporta o prefixo do seu fornecedor no id (por exemplo `mapbox:abc123`): o encaminhamento das chamadas de detalhe é automático.

## Temas personalizados

A extensão estende o componente normal `component_address_form` e deteta os campos pelo nome (`*AddressStreet`, `*AddressZipcode`, `*AddressCity`, `*AddressCountry`). Se o seu tema renomear estes campos, sobreponha o método `_cacheTargetFields` da extensão JavaScript para lhe indicar os novos nomes.

## Resolução de problemas

- **O campo de pesquisa não aparece**: verifique que o storefront foi mesmo recompilado depois da ativação, e que a página em causa está ativa na configuração.
- **Nenhuma sugestão com o Google**: verifique que a Places API (New) está ativada no projeto, que a chave é válida e que a sua restrição de IP corresponde ao IP do seu servidor.
- **O país não fica selecionado**: a extensão compara o código ISO com o atributo `data-country-iso` das opções da lista pendente, e depois com o respetivo texto visível. Se o seu tema não expuser nem um nem outro, o país atual é mantido.

## Privacidade (RGPD)

A extensão não guarda qualquer dado pessoal. As introduções do utilizador passam pelo seu servidor Shopware até ao fornecedor escolhido. Com a BAN, os dados são tratados por um serviço público francês (DINUM). Com o Google, ficam sujeitos às condições da Google Cloud; mencione-o na sua política de privacidade se for necessário.