> For the complete documentation index, see [llms.txt](https://docs.scorepositivo.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scorepositivo.com.br/pessoa-fisica/relatorios-para-nome/cadastral-zip.md).

# Cadastral ZIP

<table><thead><tr><th width="297">Código</th><th>Tipo</th></tr></thead><tbody><tr><td><mark style="color:blue;">namepf-register-zip</mark></td><td>Síncrono</td></tr></tbody></table>

{% hint style="info" %}
A busca por nome permite o uso de caracteres coringa (`*`) para ampliar os resultados retornados.

Exemplos:

* `Antonio Maria*` → retorna registros cujos nomes iniciem com "Antonio Maria".
* `Karen* Lopes` → pode ampliar a quantidade de registros encontrados em comparação com a busca exata.

Entretanto, é importante observar alguns comportamentos da pesquisa:

* O mecanismo de busca não realiza uma varredura completa em qualquer posição do nome informado.
* A priorização ocorre com base nos primeiros termos informados na consulta.
* Dependendo da composição do nome, utilizar apenas parte dele pode não retornar todos os registros esperados.
* O uso do caractere coringa (`*`) aumenta a abrangência da pesquisa, mas também pode impactar a performance da consulta, pois um volume maior de registros precisa ser analisado.

Por exemplo, uma busca por "Karen Gonzalez\*" retornou registros onde "Gonzalez" aparecia como nome intermediário de outras pessoas, porém não retornou o registro esperado: *Karen Lopes Gonzalez*. Já ao pesquisar "Karen Lopes\*", o registro foi localizado corretamente. Isso indica que a busca possui critérios de relevância e priorização dos primeiros termos informados.

**Recomendação:** Sempre que possível, utilizar o maior número de informações conhecidas do nome. Em casos de busca parcial, utilizar o caractere `*` após o primeiro nome pode auxiliar na recuperação dos registros desejados.

Exemplo: "Karen\* Gonzalez" , o registro foi localizado corretamente.
{% endhint %}

{% hint style="info" %}

## Parâmetros opcionais:

| Campo         | Descrição                              |
| ------------- | -------------------------------------- |
| birthdate     | Data de nascimento. Formato dd/mm/aaaa |
| {% endhint %} |                                        |

## Campos de Retorno

<table><thead><tr><th width="301">Campo</th><th>Descrição</th></tr></thead><tbody><tr><td>retorno</td><td>Informação sobre a quantidade de registros encontrados.</td></tr><tr><td><a href="#pessoas">pessoas</a></td><td>Lista com registros encontrados.</td></tr></tbody></table>

#### pessoas

| Campo                   | Descrição                          |
| ----------------------- | ---------------------------------- |
| nr\_documento           | CPF.                               |
| nm\_nome                | Nome.                              |
| nm\_nome\_mae           | Nome da mãe.                       |
| dt\_nascimento          | Data Nascimento.                   |
| dt\_nascimento\_br      | Data Nascimento PT-BR (dd/mm/yyyy) |
| tp\_pessoa              | Tipo pessoa.                       |
| tp\_logradouro          | Tipo logradouro.                   |
| nm\_logradouro          | Nome logradouro.                   |
| nr\_logradouro          | Número.                            |
| ds\_complemento         | Complemento.                       |
| nm\_bairro              | Bairro.                            |
| nm\_cidade              | Cidade.                            |
| sg\_estado              | Estado.                            |
| nr\_cep                 | CEP.                               |
| situacao\_srf           | Situação Receita Federal.          |
| [telefones](#telefones) | Lista com telefones.               |

#### telefones

| Campo        | Descrição                                               |
| ------------ | ------------------------------------------------------- |
| nr\_ddd      | DDD.                                                    |
| nr\_telefone | Número.                                                 |
| fg\_celular  | <p>Indicador de número mobile:<br>- true<br>- false</p> |
| nr\_score    | Score.                                                  |
| nr\_ranking  | Ranking                                                 |