Serviço de Endereços Externos¶

Objetivo¶

O serviço de Endereços Externos permite a consulta e gestão de endereços em municípios do Brasil e do Exterior, com exceção de endereços no município de Belo Horizonte.

Endpoints Disponíveis¶

Listagem de Endereços¶

GET /enderecos

Permite pesquisar endereços com diversos filtros e parâmetros de paginação.

Consulta por ID¶

GET /enderecos/{id}

Retorna um endereço específico pelo seu identificador.

Criação de Endereço¶

POST /enderecos

Permite criar um novo endereço no sistema.

Atualização de Endereço¶

PUT /enderecos/{id}

Permite atualizar um endereço existente.

Exclusão Lógica de Endereço¶

DELETE /enderecos/{id}

Realiza uma exclusão lógica do endereço, alterando seu status para inativo.

Histórico de Alterações¶

GET /enderecos/atualizacoes

Permite consultar o histórico de todas as alterações realizadas nos endereços.

Histórico de um Endereço Específico¶

GET /enderecos/{id}/atualizacoes

Permite consultar o histórico de alterações de um endereço específico.

Serviço de CEPs do DNE dos Correios¶

O serviço de CEPs permite confirmar se um CEP existe na base do DNE dos Correios, independente de haver ou não endereço cadastrado para ele no serviço de endereços externos. Útil para validar a existência de um CEP antes de cadastrar um endereço.

Listagem de CEPs¶

GET /dne/cep

Lista de forma paginada todos os CEPs existentes na base DNE dos Correios, mesmo aqueles sem endereço cadastrado. Aceita paginação e ordenação.

Consulta de CEP¶

GET /dne/cep/{cep}

Verifica se o CEP existe na base DNE dos Correios e, em caso afirmativo, retorna a lista de logradouros do CEP com município, UF e código IBGE. Responde 404 quando o CEP não existe na base.

GET /dne/cep/30130-000

[
    {
        "cep": "30130000",
        "localidade": "Belo Horizonte",
        "tipo_logradouro": "Avenida",
        "logradouro": "Afonso Pena",
        "municipio": "Belo Horizonte",
        "codigo_ibge": "3106200",
        "uf": "Minas Gerais",
        "sigla_uf": "MG"
    }
]

O campo bairro não é retornado nesse endpoint, pois a base do DNE vincula o bairro a um endereço e não diretamente ao CEP.

Endereços do DNE¶

Listagem de Endereços DNE¶

GET /dne

Pesquisa endereços DNE paginado com filtros, ordenação e pesquisa textual.

Consulta de Endereço DNE por ID¶

GET /dne/{id}

Retorna um endereço DNE específico pelo seu identificador.

Consulta de Endereços DNE por CEP¶

GET /dne/enderecos/{cep}

Retorna os endereços DNE associados ao CEP informado. Retorna apenas endereços que já possuem registro na base de endereços externos, ou seja, previamente cadastrados por algum sistema. Para confirmar se um CEP existe no DNE, use GET /dne/cep/{cep}.

Campos Obrigatórios¶

Os seguintes campos são obrigatórios para a criação de um endereço:

id_sistema_origem: Identificador do sistema responsável pelo endereço

Campos Condicionais¶

Alguns campos são condicionais, sendo obrigatório informar o ID ou o nome textual:

id_pais ou pais_informado
id_uf ou uf_informado
id_municipio ou municipio_informado
id_logradouro ou logradouro_informado
id_bairro ou bairro_informado
id_cep ou cep_informado

Regras de Negócio¶

Endereços de Belo Horizonte não podem ser cadastrados
CEP é obrigatório, podendo ser informado via ID ou campo textual
Apenas endereços de sistemas serão indexados no Elasticsearch
Endereços novos ou atualizados são inseridos no banco de dados e posteriormente no índice do Elasticsearch
A consulta de CEP em GET /dne/cep/{cep} lê a base do DNE dos Correios e responde 404 para CEPs inexistentes
A consulta de endereços em GET /dne/enderecos/{cep} retorna apenas endereços já cadastrados, podendo retornar lista vazia para um CEP válido no DNE