Como Migrar do Endcorp para o Endereço Externo¶

Visão Geral¶

O Endereço Externo é um novo serviço desenvolvido para atender a necessidade específica de sistemas que demandem o cadastro e pesquisa de endereços dos demais municípios brasileiros e estrangeiros. A diferenciação dos dois serviços deve-se ao fato dos endereços de Belo Horizonte serem auditados e terem uma gestão de governança interna pela Prodabel. Enquanto o Endereço Externo utiliza bases de terceiros, endereços cadastrados pelos próprios sistemas e não possui uma revisão por parte da Prodabel. Contudo, o sistema de histórico e versionamento do serviço permite aos próprios sistemas realizar correções e revisões dos mesmos.

Este documento detalha os casos de uso similares e funcionalidades disponíveis no Endereço Externo para substituir os endpoints do Endcorp relacionados a endereços fora de Belo Horizonte.

Autenticação e Autorização¶

Endcorp¶

O Endcorp utiliza autenticação baseada no Josso, onde as credenciais são fornecidas em cada requisição através de parâmetros no corpo da requisição.

Exemplo de requisição Endcorp: Endcorp (SOAP/JSON):

{
   parametros:  {
      autenticacao:
        {   
            id_josso: "Endcorp",
            senha_josso:"senha",
            email_usuario:"email_usuario@pbh.gov.br",
            sigla_sistema:"SIGPS"
        },
      nome_logr:"Nome da Rua"
    },
}

Endereço Externo¶

O Endereço Externo implementa o protocolo OAuth2/OpenConnectID para controlar o acesso aos serviços. Para utilizar os serviços do Endereço Externo é necessário encaminhar no cabeçalho de cada requisição o Access Token obtido através do AcessoPBH.

Exemplo de requisição Endereço Externo:

GET /enderecos?q=nome da rua
Authorization: Bearer CONTEUDO_ACCESS_TOKEN

Esta mudança é centralizada e afeta todas as chamadas ao serviço. Você precisará: 1. Criar um usuário do tipo sistema no AcessoPBH 2. Solicitar permissão para acessar o Endereço Externo 3. Implementar a obtenção do Access Token através do fluxo OAuth2 4. Alterar todas as chamadas para enviar o token no cabeçalho Authorization

Endpoints Equivalentes¶

A seguir, a tabela correlaciona os endpoints do Endcorp aos endpoints equivalentes no Endereço Externo:

Diferenças Importantes¶

1. Protocolo: Endcorp utiliza SOAP enquanto Endereço Externo utiliza REST
2. Formato de dados: Endcorp retorna dados em XML/JSON enquanto Endereço Externo retorna dados em JSON
3. Autenticação: Endcorp recebe credenciais em cada requisição, Endereço Externo utiliza OAuth2 com Access Token no cabeçalho
4. Paginação: Endereço Externo implementa paginação padrão em todas as listagens
5. Campos: Os nomes e estrutura dos campos podem variar entre os serviços

Exemplos de Migração¶

Consulta de Endereço Fora BH¶

Endcorp (SOAP/JSON):

{
   parametros:  {
      autenticacao:
        {   
            id_josso: "Endcorp",
            senha_josso:"******",
            email_usuario:"email@pbh.gov.br",
            sigla_sistema:"SIGPS"
        },
      nome_logr:"Brasil",
      numero:"1000"
    },
}

Endereço Externo (REST):

GET /enderecos?q=Avenida Brasil 1000
Authorization: Bearer CONTEUDO_ACCESS_TOKEN

Consulta de Logradouro¶

Endcorp (SOAP/JSON):

{
   parametros:  {
      autenticacao:
        {   
            id_josso: "Endcorp",
            senha_josso:"******",
            email_usuario:"email@pbh.gov.br",
            sigla_sistema:"SIGPS"
        },
      nome_logr:"dos Andradas"
    },
}

Endereço Externo (REST):

GET /logradouros?q=Rua dos Andradas
Authorization: Bearer CONTEUDO_ACCESS_TOKEN

Passo a passo para migração¶

1. Criação de usuário e permissões para acesso ao Endereço Externo
2. Implementação da autenticação OAuth2
3. Mapeamento e substituição dos endpoints
4. Testes e validação

Passo 1¶

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

Para acessar os serviços do Endereço Externo é 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 Externo.

Passo 2¶

Implementação da autenticação OAuth2¶

Substituir o envio de credenciais em cada requisição pelo fluxo OAuth2: 1. Implementar a obtenção do Access Token através do AcessoPBH 2. Armazenar o token de forma segura 3. Enviar o token no cabeçalho Authorization de todas as requisições 4. Implementar a renovação do token quando necessário (O token expira a cada 5 min) 5. Caso o serviço seja utilizado no lado cliente, é recomendado a implementação de um proxy para iteragir com o mesmo e não deixar as tokens visíveis.

Passo 3¶

Mapeamento e substituição dos endpoints¶

Para cada endpoint do Endcorp utilizado em seu sistema: 1. Identificar o endpoint equivalente no Endereço Externo 2. Substituir a chamada SOAP por REST 3. Adaptar os parâmetros de entrada conforme a documentação 4. Mapear os campos de retorno para manter a compatibilidade com o sistema

Passo 4¶

Testes e validação¶

1. Validar os resultados das chamadas migradas
2. Verificar a performance das novas chamadas
3. Garantir que todos os casos de uso foram cobertos
4. Validar o tratamento de erros e exceções

Considerações Finais¶

O Endereço Externo foi desenvolvido com tecnologias mais modernas e padrões atuais de desenvolvimento, proporcionando melhor performance e manutenibilidade. Embora haja mudanças significativas na forma de acesso e autenticação, a funcionalidade principal de pesquisa e consulta de endereços fora de Belo Horizonte é mantida e aprimorada.