Enderecos

O Address (Endereco) armazena informacoes de localizacao dos clientes, utilizado para entregas, faturamento e integracao com servicos de geolocalizacao.

Descricao

Cada cliente pode ter multiplos enderecos cadastrados. O sistema integra com servicos de CEP para preenchimento automatico e calcula distancias para validacao de areas de entrega.

Dados

Campos Obrigatorios

Campo	Tipo	Descricao
zip_code	CEP	CEP (formato: XXXXX-XXX)
street	Texto	Logradouro (rua, avenida)
street_number	Texto	Numero (ou "s/n")
neighborhood	Texto	Bairro
city	Texto	Cidade
state	Selecao	Estado (UF)

Campos Opcionais

Campo	Tipo	Padrao	Descricao
complement	Texto	-	Complemento (apto, bloco)
country	Texto	Brasil	Pais
default	Booleano	false	Se e o endereco padrao

Campos Calculados

Campo	Descricao
short_address	Endereco resumido para exibicao
city_state	Cidade/UF formatado
lat	Latitude (geolocalizacao)
lng	Longitude (geolocalizacao)

Campos de Delivery

Campo	Descricao
delivery_area	Area de entrega vinculada
km_distance	Distancia da loja em km

Relacionamentos

Pertence a

Entidade	Descricao
account	Conta (multi-tenant)
customer	Cliente dono do endereco
delivery_area	Area de entrega (se aplicavel)

Integracao com CEP (ViaCEP)

Preenchimento Automatico

Ao informar o CEP, o sistema consulta a API ViaCEP:

Mapeamento de Campos

Campo ViaCEP	Campo Address
logradouro	street
bairro	neighborhood
localidade	city
uf	state

Comportamento

1. CEP deve ter 8 digitos para disparar consulta
2. Se API falhar, campos ficam editaveis manualmente
3. Usuario pode corrigir dados preenchidos

Endereco Padrao

Regra de Unicidade

Cada cliente pode ter apenas um endereco padrao:

Uso do Endereco Padrao

Uso	Descricao
Faturamento	Usado em notas fiscais
Delivery	Sugerido como destino
Cache	Armazenado no cliente para acesso rapido

Sincronizacao

Ao alterar o endereco padrao:

1. Sistema atualiza o cliente
2. Campo default_address do cliente e atualizado
3. Mudancas refletem em notas fiscais futuras

Geolocalizacao

Calculo de Coordenadas

Coordenadas sao calculadas automaticamente:

1. Monta endereco completo
2. Consulta servico de geocoding
3. Armazena lat/lng

Formato do Endereco para Geocoding

{street}, {number}, {neighborhood}, {city}, {state}

Uso das Coordenadas

Uso	Descricao
Calculo de distancia	Distancia ate a loja
Validacao de area	Se esta na area de entrega
Mapa	Exibicao em mapa

Validacao de Area de Entrega

Processo de Validacao

Validacao por CEP

CEP do cliente: 01310-100 (= 1310100)
Faixa da area: 01000-000 a 01999-999

Se: 1000000 <= 1310100 <= 1999999
Entao: Endereco na area

Validacao por Distancia

Coordenadas do cliente: [-23.5505, -46.6333]
Coordenadas da loja: [-23.5489, -46.6388]
Distancia calculada: 0.8 km
Raio da area: 5 km

Se: 0.8 <= 5
Entao: Endereco na area

Campos Derivados

short_address

Formato: {street}, {number}, {complement}, {neighborhood}, {city}, {state}

Exemplo: "Av. Paulista, 1000, Sala 101, Bela Vista, Sao Paulo, SP"

city_state

Formato: {city}/{state.upcase}

Exemplo: "Sao Paulo/SP"

Acoes Disponiveis

Acao	Layout	Descricao
index	embed	Lista enderecos do cliente
show	modal	Ver detalhes do endereco
new/create	modal	Adicionar endereco
edit/update	modal	Editar endereco
destroy	modal	Excluir endereco

Lista de Enderecos

Colunas Exibidas

Coluna	Descricao
short_address	Endereco resumido (clicavel)
city_state	Cidade/UF
country	Pais
zip_code	CEP
default	Indicador de padrao

Paginacao

20 enderecos por pagina

Estados Brasileiros

O campo state aceita apenas UFs validas:

AC, AL, AP, AM, BA, CE, DF, ES, GO, MA,
MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN,
RS, RO, RR, SC, SP, SE, TO

Regras de Negocio

Validacoes

Campo	Validacao
zip_code	Obrigatorio
street	Obrigatorio
street_number	Obrigatorio
neighborhood	Obrigatorio
city	Obrigatorio
state	Obrigatorio, UF valida

Restricoes

1. Unico endereco padrao: Por cliente
2. UF valida: Deve ser estado brasileiro
3. CEP formato: 8 digitos (com ou sem hifen)
4. Vinculo obrigatorio: Endereco deve ter cliente

Exportacao

• PDF: Lista de enderecos (A4, paisagem)
• Disponivel no contexto de clientes

Permissoes

Acao	Quem Pode
Criar	Usuarios com permissao CRM
Editar	Usuarios com permissao CRM
Excluir	Usuarios com permissao CRM
Ver	Usuarios com permissao CRM

Uso em Notas Fiscais

O endereco padrao do cliente e usado para:

Dado NF-e	Campo
Logradouro	street
Numero	street_number
Complemento	complement
Bairro	neighborhood
Cidade	city
UF	state
CEP	zip_code
Codigo IBGE Cidade	(derivado)
Codigo IBGE UF	(derivado)