Como Migrar do Endcorp para o Endereço BH e Endereço Externo¶

Visão Geral¶

Endereço Corporativo (Endcorp) é um serviço cujo 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 de 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 mantém algumas das premissas do Endcorp, contudo novas estratégias de negócio foram definidas:

• O Endereço BH contempla apenas endereços de Belo Horizonte (e os endereços a validar), uma vez que o Cadastro Técnico responsável pela manutenção de endereços só dispõe de capacidade para validar endereços de BH. A parte do Endcorp referente a endereços fora de Belo Horizonte não é contemplada pelo Endereço BH.
• Para atender essa necessidade foi disponibilizado um segundo serviço, o Endereço Externo, que cobre o cadastro e a pesquisa de endereços dos demais municípios brasileiros e estrangeiros (com exceção de BH).
• Os serviços passam a ser somente de leitura no caso do Endereço BH (com exceção da inclusão de endereço a validar), autenticados por OAuth2/Keycloak e paginados. O Endereço Externo também oferece escrita (inclusão, atualização e exclusão lógica de endereço fora de BH).
• O resultado do Endereço BH é retornado em formato GeoJSON, e não mais como array de objetos com wrappers. O Endereço Externo retorna objetos JSON com lista de resultados e totais de paginação.

Premissa para migração completa: para suprir totalmente as funcionalidades do Endcorp, os sistemas que precisarem de endereços de BH, endereços a validar e endereços fora de BH deverão integrar com os dois novos serviços:

Neste documento serão detalhados os casos de uso similares, as diferenças de comportamento entre os serviços e as funcionalidades que não foram contempladas no Endereço BH — indicando, quando aplicável, o endereço correspondente no Endereço Externo.

Cobertura dos serviços — Endereço BH e Endereço Externo¶

Escopo de cada serviço¶

Para suprir 100% das funcionalidades do Endcorp, o sistema consumidor precisa integrar os dois serviços — cada um com permissão própria concedida no Acesso PBH/SDM.

Equivalência dos endpoints do Endcorp no Endereço Externo¶

Mapeamento dos casos de uso do Endcorp que não são atendidos pelo Endereço BH (documentação oficial de migração: /documentacao/migracao/endcorp-enderecoexterno/ e OpenAPI do serviço):

Atenção: os identificadores (id) do Endereço Externo pertencem à base própria do serviço (endereços externos, municípios, logradouros...) e não são o cod_endereco_corporativo do Endcorp nem o id do Endereço BH. Cada serviço tem sua própria chave.

Acesso e formato das chamadas — Endereço Externo¶

Requisição (mesmo padrão do Endereço BH):

GET /enderecos?cep=14620959&numero=351&pagina=0
Authorization: Bearer CONTEUDO_ACESS_TOKEN

Observações verificadas (homologação endereco-externo-hm.pbh.gov.br):

• Sem token: 401 com {"codigo":"SEG-401","mensagem":"Você precisa estar autenticado..."}. Apenas /healthcheck responde sem autenticação.
• Recurso inexistente: 404 com {"codigo":"ME-003","mensagem":"...","data":"..."}. Valor inválido em {id} (ex.: texto): 500 com corpo texto plano (não JSON).
• Valores com acento ou espaço devem ser percent-encoding UTF-8 (Orlândia → Orl%C3%A2ndia); a requisição sem encoding é rejeitada pelo proxy com 400 Bad request.
• Filtro nome em /logradouros faz igualdade exata com o nome completo (busca parcial retorna vazio); use q para busca parcial. Em /municipios o filtro nome foi ignorado na verificação (retornou a listagem completa) — usar q ou id_uf/sigla_uf.
• q e os filtros cep, numero, listar_desativados, ordenar de /enderecos foram verificados funcionando.
• O Endereço Externo não retorna geometria/coordenadas no endereço.
• Produção (endereco-externo.pbh.gov.br) estava em manutenção (HTTP 503) no momento desta verificação; os dados acima foram validados em homologação.

Exemplos de chamadas ao Endereço Externo¶

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 a área responsável. Mais informações neste link ou 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

Endereço Externo: caso o sistema também necessite de endereços fora de BH, é preciso solicitar, separadamente, a permissão para os serviços do Endereço Externo — são serviços e permissões distintos, ainda que utilizem o mesmo usuário do Acesso PBH e o mesmo fluxo OAuth2.

Diferença em relação ao Endcorp: nas chamadas de leitura testadas, o Endcorp não exigia autenticação. As operações de escrita do Endcorp exigem os campos autenticacao (id_josso, senha_josso, email_usuario, sigla_sistema) no corpo da requisição. No Endereço BH todas as operações exigem Access Token no cabeçalho.

Passo 2¶

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

Endpoints¶

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

Endereço base dos serviços do Endcorp¶

• Base de produção: http://endcorp.pbh/endereco-corporativo/soa
• Base de homologação: http://endcorp-hm.pbh/endereco-corporativo/soa

Todos os serviços usam HTTP POST com corpo JSON no formato {"parametros": { ... }} e retornam um array de objetos com wrapper nomeado (por exemplo, {"enderecoValidado": { ... }}).

O caminho completo é a base acima mais o path do serviço. A maioria dos serviços fica sob /service/, exceto /lougradouros e /tipologradouros.

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

Exemplos de possíveis equivalências¶

Os exemplos abaixo utilizam chamadas reais ao Endcorp (produção) e o recurso correspondente do Endereço BH. q é a busca por texto livre e os demais parâmetros são filtros estruturados (nota 1).

Nota 1¶

Equivalência entre os casos de uso¶

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

O Endereço BH oferece as duas formas de pesquisa:

• Filtros estruturados (nome_logradouro, numero, cep, bairro_popular, id_logradouro, id_regional, id_territorio, ...) — equivalentes aos campos individuais do Endcorp, com semântica de filtro (AND entre os parâmetros informados).
• Busca por texto livre (q) — o usuário informa todos os termos em um único campo e o Endereço BH busca a presença desses termos em todos os campos do endereço.

Portanto, ao usar q, 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", endereços desse bairro podem retornar nos resultados caso os demais termos da busca também tenham similaridade.

Recomendação de migração: quando o sistema atual monta a consulta campo a campo, migrar para os filtros estruturados do Endereço BH (equivalência total). Use q apenas quando o sistema deseja busca aproximada/ponderada.

Nota 2¶

Mudança no identificador da entidade Endereço¶

O campo 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 nomeadas como id nos objetos do Endereço BH.

Trata-se do mesmo valor (não há conversão de chave): o índice do Endereço BH é alimentado a partir da coluna ENDERECO_CORPORATIVO.COD_ENDERECO_CORPORATIVO. Exemplo verificado em produção para o endereço AMAROS, 172 - A:

• Endcorp POST /service/enderecocodigo {"parametros":{"param_endereco":713858}} → {"enderecoCorporativo":{"enderecoPBH":{"logradouro":"AMAROS","numero":172,"letra":"A", ... }}}
• Endereço BH GET /enderecos/713858 → {"type":"Feature","properties":{"id":713858, ...}}

No objeto de endereço também existe o atributo id_endereco_pbh, que equivale ao atributo id do serviço Geocoder e corresponde à chave na tabela do cadastro técnico (ENDERECO_PBH.ID_ENDERECO_PBH). Ele está presente para garantir a retrocompatibilidade e facilitar a compatibilização entre os sistemas que utilizam a chave desta tabela. mais informações abaixo

Recomendação: sistemas que já persistem cod_endereco_corporativo podem continuar utilizando o mesmo valor (lendo o campo id do Endereço BH). Sistemas que ainda não adotaram a chave devem passar a persistir id (= CodEndcorp) e, quando precisarem do vínculo com o Cadastro Técnico, id_endereco_pbh.

Nota 3¶

Limites de retorno e paginação¶

O Endcorp não pagina: os resultados são truncados silenciosamente por ROWNUM no banco:

O Endereço BH pagina todos os recursos. Os parâmetros são quantidade (tamanho da página) e pagina (número da página, iniciando em 0):

Atenção: os envelopes de paginação do Endereço BH não informam o total de registros (totalElements/totalPages não são retornados). Para percorrer todos os resultados, itere pagina incrementando de 1 em 1 até que features venha vazio. Se o sistema atual dependia dos até 100/50 registros do Endcorp, revise o laço de paginação na migração.

Nota 4¶

Semântica das buscas por nome e filtros¶

• Endcorp: o parâmetro tipo_pesquisa_logradouro controla o curinga aplicado ao nome informado (% antes, depois ou ambas). Ele é obrigatório sempre que logradouro_informado for informado nos serviços de endereço — sem ele o serviço responde Err003: O campo obrigatório TIPO_PESQUISA_LOGRADOURO não foi preenchido. Em /lougradouros o parâmetro equivalente é tipo_pesquisa (documentado como "consultar RNE002"). Em /enderecocompleto é obrigatório tipo_pesquisa (1..5, indicando quais conjuntos de endereços consultar).
• Endereço BH: em q a busca é por similaridade/presença do termo; nos filtros estruturados (nome_logradouro, bairro_popular, sigla_tipo_logradouro, q em coleções) o tratamento de acentuação, caixa e correspondência parcial deve ser validado durante a migração — os dois sistemas não necessariamente retornam os mesmos conjuntos de resultados. Diferenças de presença e de ordenação entre os dois serviços são esperadas.
• Ordenação: o Endereço BH permite ordenar (ordenar=campo,asc|desc); por padrão, /logradouros é ordenado por cod_logradouro e /dnes por cep; /enderecos não ordena.
• Filtro aproximado de número: o Endcorp usa numero_informado + num_aproximado + maior_que/menor_que; o Endereço BH usa aproximado=true e/ou numero_min/numero_max (com paridade=true para mesma paridade).

Nota 5¶

Filtro de logradouro em enderecologradouro¶

No Endcorp, o parâmetro id_logradouro_informado de enderecologradouro é aplicado sobre a coluna lg.cod_logradouro, enquanto o retorno expõe lg.id_logradouro (AppJpaDAO.pesquisaEnderecoLogradouro). No Endereço BH, GET /enderecos?id_logradouro= filtra pela coluna id_logradouro.

Nas consultas realizadas os valores cod_logradouro e id_logradouro foram sempre iguais, mas recomenda-se validar esse parâmetro com os dados de produção antes de concluir a migração.

O mesmo serviço no Endcorp também exclui do resultado os endereços com status_reg_urbana = 'R' AND status_ctm = 'N' e somente retorna ind_ativo = 'S'. No Endereço BH o padrão é ind_ativo=ativo (use ind_ativo=todos para ignorar).

Nota 6¶

Filtros não funcionais no Endcorp¶

• /lougradouros: o parâmetro id_logr não é aceito como critério único de pesquisa (Err005: Deve ser informado pelo menos um parâmetros de pesquisa) e é ignorado quando combinado com nome_logr. No Endereço BH a consulta por identificador existe: GET /logradouros/{id}.
• /service/bairros, /service/regionais e demais catálogos aceitam filtro por identificador, mas no Endereço BH esses filtros estão disponíveis em /{id} (coleções como /regionais aceitam apenas cod_regional, não id).

Nota 7¶

Formato de erro¶

Ajuste o tratamento de exceções do sistema consumidor: não é mais possível identificar "sem resultado" apenas pelo código Err008.

Passo 3¶

Alteração na implementação existente¶

Os serviços disponíveis no Endereço BH possuem URL, método HTTP, parâmetros e formato 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 dois sistemas, principalmente diferenças quanto à presença de mais endereços ou com ordenação diferente dos resultados.

Mudança de URL¶

URL base dos serviços:

• Endcorp: http://endcorp.pbh/endereco-corporativo/soa/ (homologação: http://endcorp-hm.pbh/endereco-corporativo/soa/)
• Endereço BH: https://enderecobh.pbh.gov.br/api/v1/

URL do ambiente de homologação: https://enderecobh-hm.pbh.gov.br (conferir o caminho /api/v1 no ambiente de homologação)

A nova URL está disponível somente no protocolo HTTPS.

• Endereço Externo (quando o sistema precisa de endereços fora de BH): https://endereco-externo.pbh.gov.br/ — os paths ficam na raiz (/enderecos, /logradouros, ...), sem prefixo /api/v1.

URL do ambiente de homologação: https://endereco-externo-hm.pbh.gov.br/

URL, método e corpo das chamadas ao Endereço Externo são próprios do serviço — ver Cobertura dos serviços e o Swagger.

Método HTTP e corpo da requisição¶

Exemplo:

# Endcorp
curl -X POST http://endcorp.pbh/endereco-corporativo/soa/service/enderecosvalidados \
  -H "Content-Type: application/json" \
  -d '{"parametros":{"logradouro_informado":"AFONSO PENA","numero_informado":1000,"tipo_pesquisa_logradouro":1}}'

# Endereço BH
curl -X GET "https://enderecobh.pbh.gov.br/api/v1/enderecos?nome_logradouro=AFONSO+PENA&numero=1000" \
  -H "Authorization: Bearer CONTEUDO_ACESS_TOKEN"

Requisição¶

Autorização e Autenticação¶

O Endereço BH implementa o protocolo OAuth2/OpenID Connect (Keycloak, realm PBH) para controlar o acesso aos serviços. Para utilizar os serviços é necessário encaminhar no cabeçalho de cada requisição o Access Token obtido através do AcessoPBH/ GAS-PBH.

Endpoint de emissão do token (fluxo password, client credentials do sistema):

https://acesso.pbh.gov.br/auth/realms/PBH/protocol/openid-connect/token

Exemplo de requisição ao Endereço BH:

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

Mais informações na documentação do Endereço BH (https://enderecobh.pbh.gov.br/v3/api-docs e https://enderecobh.pbh.gov.br/swagger-ui.html).

O Endereço Externo usa o mesmo fluxo OAuth2/OpenID Connect do Acesso PBH (obter o Access Token e enviá-lo no cabeçalho Authorization: Bearer ...), conforme descrito em Cobertura dos serviços. No Endereço Externo o token expira em 5 minutos (verificado na homologação, expires_in=300) — implementar a renovação automática.

Formato de saída¶

Endereço¶

No Endcorp os campos do endereço ficam disponíveis nas propriedades de um objeto com wrapper (enderecoValidado, enderecoPBH, enderecoAValidar, ...), dentro de um array.

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

[
  {
    "enderecoValidado": {
      "cod_endereco_corporativo": 616372,
      "id_endereco_pbh": 10681,
      "id_tipo_logradouro": 3,
      "sigla_tipo_logradouro": "AVE",
      "desc_tipo_logradouro": "AVENIDA",
      "nome_logradouro": "AFONSO PENA",
      "id_logradouro": 1259,
      "numero_imovel": 1000,
      "cep": 30130003,
      "id_bairro": 37,
      "nome_bairro_popular": "Centro",
      "nome_bairro_oficial": "Terceira",
      "id_regional": 10,
      "nome_regional": "HIPERCENTRO",
      "id_territorio": 41,
      "nome_territorio": "Território 1 da Regional HIPERCENTRO",
      "coordenadax": 611236.429250523,
      "coordenaday": 7796811.7761125
    }
  }
]

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": 5,
  "paged": true,
  "unpaged": false
}

Os campos de paginação (pageNumber, pageSize, offset, paged, unpaged, sort) são decorrentes do parâmetro quantidade informado na requisição. Não há totalElements nem totalPages (nota 3).

Propriedades do Endereço¶

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

Equivalências entre os campos¶

Os wrappers do Endcorp variam conforme o serviço. As tabelas abaixo consideram os formatos retornados em produção.

Endereço — enderecoValidado (enderecosvalidados) e enderecoAValidar (enderecosavalidar)¶

Endereço — enderecoPBH (enderecocodigo, enderecologradouro)¶

Logradouro — logradouro (/lougradouros)¶

Tipo de logradouro — tipoLogradouro (/tipologradouros)¶

Bairro (popular) — bairro (/service/bairros)¶

Regional — regional (/service/regionais)¶

Complemento — complementoEndereco (/service/complementosendereco)¶

DNE — dne (/service/dne)¶

Território de Gestão Compartilhada — territoriogestaocompartilhada¶

Campo Geometria¶

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

Exemplo:

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

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

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

Exemplo:

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

São retornadas também as geometrias no formato WKT (campo {features[].properties.wkt}) nos sistemas de coordenadas:

• WGS84 (EPSG 4326) em {features[].properties.wkt.epsg_4326}
• Sirgas 2000 23S (EPSG 31983) em {features[].properties.wkt.epsg_31983} — 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)"
        }
      }
    }
  ],
  ...
}

Os parâmetros espaciais do Endereço BH (bbox, poligono, coordenadas, crs) aceitam EPSG4326 ou EPSG31983 conforme o parâmetro crs.

Regras de filtragem padrão¶

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 REST (POST com corpo JSON).
3. Endcorp verifica as credenciais de acesso fornecidas no Josso (necessário para as operações de escrita; as consultas de leitura testadas dispensaram autenticação).
4. Josso retorna as permissões para o Endcorp.
5. Endcorp retorna o resultado em formato JSON para Aplicação.
6. Aplicação exibe para o Usuário o endereço localizado.

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 realiza a autenticação e solicita a credencial (access token) ao AcessoPBH.
3. AcessoPBH retorna a credencial para Aplicação.
4. Aplicação realiza a requisição ao Endereço BH passando no cabeçalho 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.

Apêndice — fontes verificadas¶

• Swagger do Endcorp: endcorp-original/docs/requisitos/DocumentacaoSwagger/EndcorpDocumentacaoSwagger.yaml
• Código-fonte do Endcorp: AppJpaDAO (SQL, limites ROWNUM, semântica dos filtros) e recursos JAX-RS (@Path de cada serviço)
• OpenAPI do Endereço BH: https://enderecobh.pbh.gov.br/v3/api-docs (versão 1.0.32)
• Código-fonte do Endereço BH: webservice (mapeamento dos documentos/indexes), logstash (SQL de alimentação do Elasticsearch)
• Chamadas reais ao Endcorp em produção (leitura) para conferência de caminhos, wrappers, parâmetros obrigatórios e mensagens de erro
• Documentação do Endereço Externo: https://endereco-externo.pbh.gov.br/documentacao/, página oficial de migração https://endereco-externo.pbh.gov.br/documentacao/migracao/endcorp-enderecoexterno/ e Swagger https://endereco-externo.pbh.gov.br/swagger-ui/index.html
• OpenAPI do Endereço Externo (homologação): https://endereco-externo-hm.pbh.gov.br/v3/api-docs — produção estava em manutenção (HTTP 503) no momento da verificação
• Chamadas reais ao Endereço Externo em homologação (endereco-externo-hm.pbh.gov.br), com token do Acesso PBH, para conferência de filtros, paginação, formatos de erro e exemplos