> For the complete documentation index, see [llms.txt](https://docs.hablla.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hablla.com/fluxos-de-automacoes/todos-os-componentes/others/via-cep.md).

# Via CEP

### Visão Geral

O **Componente de Integração ViaCEP** (identificado na interface pelo nome técnico descritivo `via_cep`) é um nó de ação focado em enriquecimento de dados (*data enrichment*) e consulta de APIs externas de utilidade pública. Sua função principal é automatizar a localização de endereços postais brasileiros no fluxo de atendimento. Ele captura um código postal (CEP) fornecido pelo usuário e realiza, de forma nativa e em segundo plano, uma requisição HTTP do tipo `GET` aos servidores do serviço ViaCEP, retornando a estrutura completa de logradouro, bairro, cidade e estado.

### Parâmetros de Configuração

A parametrização do bloco gerencia a string de entrada para a consulta do webservice através de um único critério obrigatório:

* **CEP (\* Campo Obrigatório):** Campo de entrada de texto destinado a receber a numeração do código postal que será consultado. Aceita o preenchimento de valores estáticos ou a injeção de variáveis dinâmicas do fluxo que armazenam a resposta digitada pelo cliente (ex: `{{response}}` ou `{{cliente.cep_bruto}}`).<br>

### Construtor Visual

A interface do construtor foi desenhada sob um modelo enxuto e direto, visando abstrair configurações complexas de cabeçalhos ou tokens de requisição:

* **Painel de Entrada Direta:** Exibe um layout limpo composto exclusivamente pelo campo de digitação do CEP. O indicador de asterisco (`*`) atua como uma trava de segurança visual, impedindo que o administrador salve o componente sem estipular um parâmetro de busca. Por se tratar de um barramento de consulta pública nativa, o nó dispensa seletores de credenciais, autenticações de API ou uploads de mídia.<br>
* **Disponibilização de Payload de Saída:** No mapa visual de automação, o bloco apresenta conectores tradicionais de entrada e saída contínua. Ao ser acoplado à árvore, o sistema expõe automaticamente o objeto de dados resultante do ViaCEP para que os nós vizinhos possam ler e consumir as propriedades do endereço localizado.<br>

### Operadores Especiais

As propriedades lógicas deste componente gerenciam a higienização de dados em tempo real, tratamento de erros de requisição e mapeamento de payloads JSON:

* **Tratamento Automático de Máscara (Sanitization):** O motor interno do componente limpa de forma automatizada a string inserida no campo *CEP* antes de disparar o endpoint. Ele aplica expressões regulares para remover caracteres especiais, hifens (`-`) ou espaços vazios, garantindo o envio correto do formato padrão de 8 dígitos exigido pelo ViaCEP.<br>
* **Mapeamento de Estrutura de Resposta (JSON Object):** Após processar a chamada síncrona com sucesso, o motor da plataforma injeta as propriedades retornadas diretamente no escopo de dados do contato (`$data`). O payload devolvido segue o padrão do serviço e inclui as seguintes subvariáveis prontas para uso:
  * `via_cep.logradouro`: Nome da rua, avenida, praça, etc.<br>
  * `via_cep.bairro`: Bairro ou distrito correspondente.<br>
  * `via_cep.localidade`: Nome do município/cidade.<br>
  * `via_cep.uf`: Sigla do Estado (Unidade da Federação).<br>
  * `via_cep.complemento`: Informações adicionais de loteamento ou região (se houver).<br>
* **Tratamento de Rota de Falha (CEP Inexistente):** Caso o webservice retorne que o CEP consultado é inválido ou inexistente (retorno `{ "erro": true }`), o componente impede a gravação de dados em branco e permite que o fluxo tome caminhos alternativos de correção.<br>

### Exemplos Práticos

A tabela abaixo demonstra cenários de como aplicar este componente para otimizar cadastros e entregas dentro da jornada do bot:

| **CEP Informado no Construtor** | **Resposta do Servidor ViaCEP**        | **Propriedades Injetadas no Fluxo**                                                                                                                                                                                     | **Caso de Uso Prático**                                                                                                                                                                                                                                                                    |
| ------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `70040-010`                     | Sucesso na requisição.                 | <p><code>via\_cep.logradouro</code> = "SBN Quadra 1 Bloco A"<br><br><br><br><code>via\_cep.localidade</code> = "Brasília"<br><br><br><br><code>via\_cep.uf</code> = "DF"</p>                                            | O cliente digita o CEP com hífen no chat. O bloco trata a string, busca os dados e preenche automaticamente o endereço para fins de faturamento.                                                                                                                                           |
| `{{resposta_cep}}`              | Sucesso na requisição.                 | <p><code>via\_cep.logradouro</code> = "Praça da Sé"<br><br><br><br><code>via\_cep.bairro</code> = "Sé"<br><br><br><br><code>via\_cep.localidade</code> = "São Paulo"<br><br><br><br><code>via\_cep.uf</code> = "SP"</p> | Em um fluxo de entrega de e-commerce, o bot pede o CEP do cliente. Este componente processa a resposta e exibe uma mensagem de confirmação em seguida: *"Você mora na `{{via_cep.logradouro}}`, no bairro `{{via_cep.bairro}}` em `{{via_cep.localidade}}`/`{{via_cep.uf}}`? Sim ou Não?"* |
| `00000000`                      | Resposta de erro (CEP não encontrado). | Nenhuma propriedade de endereço é injetada.                                                                                                                                                                             | O usuário digita um número inválido no chat. O sistema identifica a falha no retorno do bloco e direciona para um nó de pergunta pedindo para ele redigitar o código postal.                                                                                                               |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hablla.com/fluxos-de-automacoes/todos-os-componentes/others/via-cep.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.