Como Migrar do Endcorp para o Endereço BH¶

Visão Geral¶

Endereço Corporativo (Endcorp), é um serviço cujo o objetivo foi padronizar a forma de consumir e pesquisar endereços entre os sistemas da Prefeitura Municipal de Belo Horizonte. Como premissa, este serviço estabeleceu a chave de endereço única e imutável (CodEndcorp). Essa chave representa um identificador único para o endereço independente dos estados que ele assuma dentro da base e das atualizações cadastrais da cidade. Além dessa estratégia o Endcorp também visava baratear os custos do desenvolvimento de novos sistemas eliminando deles a necessidade de manter um cadastro de endereços, tanto para endereços de Belo Horizonte quanto fora de Belo Horizonte.

O Endereço BH, veio mantendo algumas das premissas do Endcorp, contudo novas estratégias de negócio foram definidas. Ao contrário do Endcorp ele não será um repositório irrestrito de endereços. Apenas endereços de Belo Horizonte serão contemplados nele, uma vez que o Cadastro Técnico, responsável pela manutenção de endereços, só dispõe de capacidade para validar os endereços de Belo Horizonte. Para os endereços de fora de Belo Horizonte, um novo serviço deverá ser disponibilizado futuramente.

Neste documento será detalhado os casos de usos similares e funcionalidades que não foram contempladas no novo serviço.

Passo a passo¶

1. Criação de usuário e permissões para acesso ao Endereço BH
2. Validação dos casos de usos disponíveis no Endereço BH
3. Alteração na implementação existente

Passo 1¶

Criação de usuário e permissões para acesso ao Endereço BH¶

Para acessar os serviços do Endereço BH é necessário um usuário, do tipo sistema, cadastrado no Acesso PBH.

Caso o sistema ainda não possua usuário, é necessário solicitar para área responsável. Mais informações neste link ou mais informações no manual disponível em autorizacaodesistemas.pbh.gov.br

Solicitar concessão de permissão para que o usuário possa acessar os serviços do Endereço BH Mais informações

Passo 2¶

Validação dos casos de usos disponíveis no Endereço BH¶

Endpoints¶

É necessário idenfificar todos os casos de usos atualmente utilizados no Endcorp e verificar se casos de usos disponíveis no Endereço BH atendem aos requisitos existentes. Para facilitar a migração tabela abaixo contém as possíveis equivalências entre os serviços do Endcorp e Endereço BH

Possíveis equivalências entre endpoints dos serviços¶

Possíveis equivalência entre os parâmetros utilizados nos dois serviços¶

Exemplos de possíveis equivalências¶

Nota 1¶

Equivalência entre os casos de usos¶

O Endcorp utiliza filtros para realizar a busca por endereços. O usuário informa individualmente cada campo que compõe o endereço, cabendo ao Endcorp restringir o resultado da consulta somente aos endereços que possuem todos os campos informados pelo usuário.

Já o Endereço BH realiza pesquisa pela presença dos termos informados pelo usuário nos campos do endereço. O usuário deverá informar todos os termos a serem pesquisados em um único campo e Endereço BH pesquisará pela presença dos termos em todos os campos dos endereços.

Portanto, mesmo informando termos pertencentes a um determinado campo do endereço, caso estes termos estejam presentes em outros campos, estes serão incluídos no resultado.

Ex:

Se o termo pesquisado for Rua Carmo, e também existir um bairro Carmo, pode ser que endereços desse bairro retornem nos resultados caso outros termos da busca também tenham similaridade.

Nota 2¶

Mudança no identificador da entidade Endereço¶

O campos cod_endereco_corporativo presente no Endcorp equivale ao id no Endereço BH, para o objeto de endereço. Seguindo a convenção de mercado para serviços REST e modelos de dados, convencionou-se que todas as chaves serão nomeada como id nos objetos do Endereço BH. No objeto de endereço, também existe o atributo id_endereco_pbh que equivale ao atributo id do serviço Geocoder, e corresponde a chave na tabela do cadastro técnico. Neste caso id_endereco_pbh está presente para garantir a retrocompatibilidade e facilitar compatibilização entre os diversos sistemas que utilizam a chave desta tabela. mais informações abaixo

Recomendamos que seja realizada a migração também dos identificadores, para utilizar o campo id do Endereço BH, realizando as modificações necessárias na base de dados.

Passo 3¶

Alteração na implementação existente¶

O serviços disponíveis no Endereço BH possuem URL, parâmetros e formatos de retorno diferentes dos serviços disponíveis no Endcorp, em alguns casos, não possuindo uma equivalência direta.

Poderá ser observado um comportamento diferente quanto aos resultados obtidos entre os serviços nos dois sistemas, principalmente diferenças quanto a presença de mais endereços ou com ordenação diferente dos resultados obtidos entre os dois sistemas.

Mudança de URL¶

URL base dos serviços:

• Endcorp http://endcorp-hm.pbh/endereco-corporativo/soa/service/
• Endereço BH: https://enderecobh.pbh.gov.br/api/

URL Ambiente de homologação: https://enderecobh-hm.pbh.gov.br

A nova URL está disponível somente o protoloco HTTPS

Requisição¶

Autorização e Autenticação¶

O Endereço BH implementam o protocolo OAuth2/OpenConnectID para controlar o acesso aos serviços. Para utilizar os serviços do Endereço BH é necesário encaminhar no cabeçalho de cada requisição o Acess Token obtido através do AcessoPBH/GAS-PBH

Exemplo de requisição ao Endereço BH

GET /enderecos?q=avenida afonso pena 1212
Authorization: Bearer CONTEUDO_ACESS_TOKEN

Mais informações na documentação do Endereço BH. Acesso ao link

Formato de saída¶

Endereço¶

No Endcorp os campos dos endereços estão disponíveis nas propriedades dos objetos, por exemplo enderecoValidado.

Exemplo saída JSON Endcorp - Pesquisa Endereço¶

[
  {
    "enderecoValidado": {
      "cod_endereco_corporativo": 614935,
      "id_endereco_pbh": 7164,
      "id_tipo_logradouro": 18,
      "sigla_tipo_logradouro": "RUA",
      "desc_tipo_logradouro": "RUA",
      "nome_logradouro": "PIAUI",
      "id_logradouro": 53624,
      "numero_imovel": 69,
      "cep": 30150320,
      "id_bairro": 141,
      "nome_bairro_popular": "Santa Efigênia",
      "nome_bairro_oficial": "Décima Terceira",
      "id_regional": 2,
      "nome_regional": "CENTRO-SUL",
      "id_territorio": 29,
      "nome_territorio": "Território 1 da Regional CENTRO-SUL",
      "coordenadax": 612606.427684689,
      "coordenaday": 7796771.17983388
    }
  }
]

Exemplo saída GeoJSON Endereço BH - Pesquisa Endereço¶

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": 713858,
        "id_endereco_pbh": 157801,
        "id_tipo_logradouro": 18,
        "tipo_logradouro": "RUA",
        "sigla_tipo_logradouro": "RUA",
        "id_logradouro": 3125,
        "nome_logradouro": "AMAROS",
        "numero": 172,
        "letra": "A",
        "id_bairro_popular": 167,
        "bairro_popular": "São Paulo",
        "id_bairro_oficial": 71,
        "bairro_oficial": "São Paulo",
        "id_regional": 4,
        "cod_regional": 21,
        "nome_regional": "NORDESTE",
        "cep": "31910180",
        "id_territorio": 4,
        "id_territorio_fiscalizacao": 7,
        "sigla_territorio": "NE3",
        "ind_ativo": "ativo",
        "status_ctm": "E",
        "wkt": {
          "epsg_4326": "POINT (-43.9223085833891 -19.8685332830945)",
          "epsg_31983": "POINT (612830.601300225 7802706.02354846)"
        }
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-43.9224199449533, -19.8685907791933]
      }
    }
  ],
  "sort": {
    "sorted": false,
    "unsorted": true,
    "empty": true
  },
  "offset": 0,
  "pageNumber": 0,
  "pageSize": 50,
  "paged": true,
  "unpaged": false
}

Propriedades do Endereço¶

No Endereço BH o resultado utiliza o formato GeoJSON de retorno dos resultados, cada registro é retornado camo um objeto dentro do campo {features[]}, os campos de cada registro estão disponíveis no objeto {features[].properties}.

Equivalências entre os campos¶

Endereço¶

Campo Geometria¶

No Endcorp a geometria de cada endereço está presente nos atributos coordenadax e coordenaday. O formato de coodernada utilizado é o Sirgas 2000 23S (EPSG 31983).

Exemplo :

[{"enderecoValidado": {
   ...
   "coordenadax": 612606.427684689,
   "coordenaday": 7796771.17983388
}}]

No resultado do Endereço BH cada endereço será retornado como Feature do GeoJSON com um campo {features[].geometry}, utilizando o sistema de coodernadas WGS84 (EPSG 4326).

Também será informado o tipo {features[].geometry.type} de geometria e, que no caso dos endereços, será o tipo "Point".

Exemplo :

{
  ...
  "features": [
    {
      ...
      "geometry": {
        "type": "Point",
        "coordinates": [-43.9224199449533, -19.8685907791933]
      }
    }
  ],
  ...
}

Será retornado também as geometrias no formato WKT (campo {features[].properties.wkt}) nos sistemas de coordenadas:

• WGS84 (EPSG 4326) no campo {features[].properties.wkt.epsg_4326}
• Sirgas 2000 23S (EPSG 31983) no campo {features[].properties.wkt.epsg_31983} Sirgas 2000 23S (EPSG 31983) é o mesmo sistema de coordenadas utilizado no Endcorp.

Exemplo :

{
  ...
  "features": [
    {
      ...
      "properties": {
        ...
        "wkt": {
          "epsg_4326": "POINT (-43.9224199449533 -19.8685907791933)",
          "epsg_31983": "POINT(612818.900382729 7802699.73479656)"
        },
      },
    ...
    }
  ],
  ...
}

Passos permissão¶

Passos para solicitar concessão de permissão¶

1. Definir quais serviços do Endereço BH serão utilizados.
2. Identificar as permissões necessárias para acessos aos serviços.
3. Solicitar via SDM a concessão das permissões para o usuário do sistema, informando o usuário e os tipos de permissões.

Área da solicitação SDM:

Servicos de Tecnologia e Informacao.Geoprocessamento.BHMap.Conteudo

Caso Uso básico do Endcorp¶

1. Usuário inicia a pesquisa por um determinado endereço em uma Aplicação.
2. Aplicação realiza a consulta ao Endcorp, utilizando SOAP.
3. Endcorp verifica as credenciais de acesso fornecidas no Josso.
4. Josso retorna as permissões para o Endcorp.
5. Aplicação exibe para o Usuário o endereço localizado.
6. Endcorp retorna o resultado em formato JSON para Aplicação.

Caso Uso básico do Endereço BH¶

1. Diagramas com fluxo Pesquisa de Endereço no Endereço BH

1. Usuário inicia a pesquisa por um determinado endereço em uma Aplicação.
2. Aplicação reliza autenticação e solicitação do credencial (acess token) ao AcessoPBH
3. AcessoPBH retorna a credencial para o Aplicação.
4. Aplicação realiza a requisição ao Endereço BH passando no cabeçalho a a credencial obtida do _AcessoPBH.
5. Endereço BH retorna o resultado em formato GeoJSON para Aplicação.
6. Aplicação exibe para o Usuário o endereço localizado.