> 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/hablla-docs-en/automation-flows/all-components/others/via-cep.md).

# Via CEP

### Overview

The **ViaCEP Integration Component** (identified in the interface by the descriptive technical name `via_cep`) is an action node focused on data enrichment (*data enrichment*) and querying external public utility APIs. Its main function is to automate the location of Brazilian postal addresses in the service flow. It captures a postal code (CEP) provided by the user and performs, natively and in the background, an HTTP request of type `GET` to ViaCEP service servers, returning the complete structure of street, neighborhood, city, and state.

### Configuration Parameters

The block configuration manages the input string for the webservice query through a single required criterion:

* **CEP (\* Required Field):** Text input field intended to receive the postal code number to be queried. It accepts static values or injection of dynamic flow variables that store the response typed by the customer (e.g.: `{{response}}` or `{{cliente.cep_bruto}}`).<br>

### Visual Builder

The builder interface was designed under a lean and direct model, aiming to abstract complex header or request token configurations:

* **Direct Input Panel:** Displays a clean layout composed exclusively of the CEP input field. The asterisk indicator (`*`) acts as a visual safety lock, preventing the administrator from saving the component without defining a search parameter. Since it is a native public query bus, the node does not require credential selectors, API authentications, or media uploads.<br>
* **Output Payload Availability:** In the visual automation map, the block presents traditional continuous input and output connectors. When attached to the tree, the system automatically exposes the resulting ViaCEP data object so neighboring nodes can read and consume the properties of the located address.<br>

### Special Operators

The logical properties of this component manage real-time data cleansing, request error handling, and JSON payload mapping:

* **Automatic Mask Handling (Sanitization):** The component's internal engine automatically cleans the string entered in the field *CEP* before triggering the endpoint. It applies regular expressions to remove special characters, hyphens (`-`) or empty spaces, ensuring the correct sending of the standard 8-digit format required by ViaCEP.<br>
* **Response Structure Mapping (JSON Object):** After successfully processing the synchronous call, the platform engine injects the returned properties directly into the contact data scope (`$data`). The returned payload follows the service standard and includes the following ready-to-use subvariables:
  * `via_cep.logradouro`: Street, avenue, square, etc.<br>
  * `via_cep.bairro`: Corresponding neighborhood or district.<br>
  * `via_cep.localidade`: Municipality/city name.<br>
  * `via_cep.uf`: State abbreviation (Federative Unit).<br>
  * `via_cep.complemento`: Additional subdivision or region information (if any).<br>
* **Failure Route Handling (Nonexistent CEP):** If the webservice returns that the queried CEP is invalid or nonexistent (return `{ "erro": true }`), the component prevents blank data from being saved and allows the flow to take alternative correction paths.<br>

### Practical Examples

The table below demonstrates scenarios for applying this component to optimize registrations and deliveries within the bot journey:

| **CEP Entered in the Builder** | **ViaCEP Server Response**      | **Properties Injected into the Flow**                                                                                                                                                                                   | **Practical Use Case**                                                                                                                                                                                                                                                                               |
| ------------------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `70040-010`                    | Request successful.             | <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>                                            | The customer types the CEP with a hyphen in the chat. The block processes the string, fetches the data, and automatically fills in the address for billing purposes.                                                                                                                                 |
| `{{resposta_cep}}`             | Request successful.             | <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> | In an e-commerce delivery flow, the bot asks for the customer's CEP. This component processes the response and then displays a confirmation message: *"You live on the `{{via_cep.logradouro}}`, in the neighborhood `{{via_cep.bairro}}` in `{{via_cep.localidade}}`/`{{via_cep.uf}}`? Yes or No?"* |
| `00000000`                     | Error response (CEP not found). | No address property is injected.                                                                                                                                                                                        | The user types an invalid number in the chat. The system identifies the failure in the block's return and directs it to a question node asking them to re-enter the postal code.                                                                                                                     |


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.hablla.com/hablla-docs-en/automation-flows/all-components/others/via-cep.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.