Envio de Polígonos ao SIG-RI: 9 Achados na API do ONR

Contexto

O Provimento CN-CNJ n. 195/2025 criou o SIG-RI, base de dados geográficos das informações imobiliárias mantidas pelos cartórios, e atribuiu aos oficiais a obrigação de alimentá-lo com os perímetros dos imóveis georreferenciados (art. 343-F, I). O panorama da norma, com as obrigações e os prazos de cada uma, está em Provimento CNJ 195/2025: SIG-RI, IERI-e e prazos.

Este artigo trata do lado técnico do envio. Para uma serventia com acervo pequeno, o upload manual pelo portal resolve. Para quem tem milhares de matrículas georreferenciadas, a via é a API de envio de polígonos, documentada no Manual API para Envio dos Polígonos, versão 1.0, do Mapa do Registro de Imóveis.

Este artigo é o relatório técnico de uma implementação de referência dessa API, construída pela equipe de engenharia da Mupi Systems (responsável pelo RI-Online): geração dos shapefiles, execução dos três endpoints e conferência das respostas contra a API de produção. São nove achados, cada um com evidência, análise de impacto e proposta de correção. A intenção é somar ao padrão, e nenhum achado vem sem um caminho de solução.

Como os achados foram levantados

Construímos um gerador que monta os quatro arquivos do shapefile (.shp, .shx, .dbf, .prj) em memória, com os 34 campos da seção 6 do manual, e um cliente para os três endpoints da API. Rodamos o conjunto contra a API de produção do Mapa, com matrículas rurais reais, percorrendo o fluxo inteiro: geração de URLs, upload, confirmação e polling de status.

Os achados têm três origens, e a distinção importa porque cada uma pede um tipo diferente de correção:

• Divergências entre o que o manual documenta e o que a API responde (achados 5 e 6);
• Defeitos internos do próprio documento, verificáveis sem executar nada (achados 3, 4 e 9);
• Lacunas, comportamentos que a API exige e o manual nunca descreve (achados 2 e 7).

Os achados 1 e 8 ficam fora dessa divisão. São questões de modelagem do dado, e correção de texto não resolve.

Resumo dos achados

#	Achado	Severidade
1	A especificação não representa condomínio fracionado: metade dos campos de titularidade aceita lista, a outra metade não	Alta
2	Nenhum sistema de coordenadas é documentado, embora exista status de erro para projeção não suportada	Alta
3	O script QGIS oficial cria AREA_HA com 2 casas decimais; o exemplo do próprio manual tem 4	Alta
4	O JSON Schema publicado é sintaticamente inválido	Média
5	categoria_poligono documentado em minúsculo; a API exige maiúsculo	Média
6	BASE_URL com www não resolve no DNS, e o manual se contradiz internamente	Média
7	Status terminais nunca definidos, e o exemplo retorna um valor fora da lista	Média
8	CLASSIFICA × classificacao_poligonos: dois campos confundíveis, e o vínculo com o art. 343-C	Média
9	Cinco dos 34 campos com descrição truncada no PDF	Baixa

Os achados em detalhe

1. A especificação não representa condomínio fracionado — Alta

Evidência. A tabela da seção 6 define os campos de titularidade assim:

Campo	Tipo	Exemplo do manual
NOME_PROP	Alfanumérico	João Silva, Maria Souza
CPF_CNPJ	Numérico	000000000-00, 000000000-00
REL_JUR	Letra	propriedade, usufruto, promessa c&v
PER_REL	Numérico	33,33%
DAT_INI	Numérico	02/06/2024
DAT_FIM	Numérico	02/06/2025

Os dois primeiros são alfanuméricos, e os próprios exemplos do manual trazem listas separadas por vírgula. Já PER_REL, DAT_INI e DAT_FIM são numéricos, e campo numérico de DBF não comporta lista.

Impacto. Um imóvel com três coproprietários a 33,33% cada gera três nomes, três CPFs e um único percentual. O implementador não tem escolha dentro do formato: precisa eleger um titular e descartar a fração dos demais, ou omitir o percentual de todos. O mesmo acontece com REL_JUR, cujo exemplo lista três relações jurídicas distintas (propriedade, usufruto e promessa de compra e venda) para um só par DAT_INI/DAT_FIM.

Fração ideal e usufruto pesam sobre a disponibilidade do imóvel, que é o que o art. 343-F, III, “b” manda controlar ao impedir “registros de imóveis em duplicidade material de matrículas e alienações a non domino”. O SIG-RI recebe o polígono correto e um quadro de titularidade incompleto sempre que houver mais de um titular.

A raiz do problema está em acomodar uma relação 1:N (um imóvel, N titulares) num registro plano. O mesmo limite reaparece em CONF_MAT e CONF_NOM, campos de caractere com teto de 254 posições, o máximo do formato DBF. Num imóvel rural com muitos confrontantes, a lista é truncada sem aviso.

Proposta.

• Um registro por titular, repetindo a geometria, com a chave da matrícula ligando as feições. Cabe no shapefile sem mudar o formato.
• Ou manter um registro por polígono e receber o quadro de titularidade em documento estruturado à parte (JSON), enviado junto do shapefile, com uma entrada por titular contendo nome, documento, relação jurídica, fração e datas.

A segunda alternativa tem precedente: é assim que a titularidade aparece nos schemas da ITN-04.

2. Nenhum sistema de coordenadas é documentado — Alta

Evidência. O manual exige o arquivo .prj em todos os endpoints, e é o .prj que declara o sistema de referência do shapefile. Em nenhum ponto do documento se diz qual sistema de coordenadas o SIG-RI aceita: nem na seção 2, nem na tabela de atributos da seção 6, nem no script da seção 7.

Ao mesmo tempo, a lista de status da seção 4 inclui:

Projeção não suportada pelo sistema {[data_processamento]}. Por favor aguarde revisão da equipe técnica

Há um estado de erro dedicado à projeção inválida e nenhuma documentação sobre qual projeção é válida.

Impacto. O implementador descobre o requisito por tentativa e erro, gastando ciclos de envio e processamento para chegar a uma informação de uma linha. Pior, o erro não chega na hora. Ele aparece depois do upload dos quatro arquivos e da confirmação, já dentro da fila de processamento, e a mensagem pede que se “aguarde revisão da equipe técnica”. O retorno passa a depender de intervenção humana do outro lado.

Em nossa implementação, o .prj é fixado em SIRGAS 2000 (EPSG:4674), geográfico, em graus decimais, sem reprojeção. Chegamos a esse valor testando contra a produção. Acervos antigos descritos em SAD-69 ou Córrego Alegre exigem reprojeção prévia, e um cartório que não saiba disso envia o lote inteiro em datum errado, com deslocamento de dezenas de metros e sobreposições falsas no mosaico.

Proposta. Declarar o sistema de referência aceito na seção 2, junto da descrição do .prj, e listar os data de origem que exigem reprojeção prévia. Melhor ainda seria validar a projeção na chamada de geração de URLs, antes do upload, devolvendo erro síncrono em vez de status assíncrono.

3. O script oficial perde precisão de área — Alta

Evidência. A tabela da seção 6 define AREA_HA como numérico e dá como exemplo:

Campo	Tipo	Exemplo
AREA_HA	Numérico	50,7575

Quatro casas decimais. Já o script QGIS distribuído na seção 7 do mesmo documento cria todos os campos Double assim:

if ftype == QVariant.Double:
    # define double com 2 casas decimais (prec=2) e até 10 dígitos totais (len=10)
    fields_to_add.append(QgsField(name[:10], ftype, len=10, prec=2))

E AREA_HA está mapeado como QVariant.Double. O script oficial cria um campo com duas casas decimais para receber um valor de exemplo com quatro.

Impacto. Num campo numérico de DBF, prec determina a gravação: o valor vai para o arquivo como texto, com aquela quantidade de decimais. 50,7575 armazenado num campo declarado com 2 casas vira 50,76, uma diferença de 25 m².

O erro é silencioso. O shapefile é gerado sem exceção nem aviso, o envio é aceito, e a área registrada no SIG-RI diverge da área da matrícula. Em imóvel rural, área é elemento da especialidade objetiva, e a divergência entra no mosaico que o art. 343-F, II manda usar para conferir sobreposições.

O problema alcança outros campos do mesmo script. CEP e RIP são criados como QVariant.Int, e o exemplo de CEP na tabela é 01001000. Um inteiro descarta o zero à esquerda, e todo CEP da capital paulista começa com zero.

Proposta.

• Corrigir o script para declarar AREA_HA com pelo menos 4 casas decimais, alinhando-o ao exemplo da tabela;
• Especificar a precisão exigida por campo na tabela da seção 6, em vez de aplicar um prec uniforme a todos os Double;
• Tipar como caractere os identificadores compostos por dígitos (CEP, RIP, CIF), preservando zeros à esquerda. A regra é a mesma que já apontamos nos achados da ITN-03: identificadores são strings, mesmo quando só têm números.

Em nossa implementação, AREA_HA é declarado com 4 casas decimais.

4. O JSON Schema publicado é sintaticamente inválido — Média

Evidência. A seção 2 traz o JSON Schema da requisição de importação. Entre as propriedades numero_prenotacao e nivel_publicidade há uma chave de abertura órfã, sem correspondente de fechamento. O bloco, como publicado, não é JSON válido.

Impacto. Um schema existe para ser consumido por máquina: carregado num validador, usado para gerar cliente, colado numa ferramenta de teste. Com erro de sintaxe, ele não passa em nenhuma dessas etapas. Quem tenta carregá-lo recebe erro de parse e precisa reconstruir a estrutura no olho, adivinhando o aninhamento pretendido.

Há um efeito colateral de leitura. Com as chaves desbalanceadas, a indentação deixa de refletir a estrutura, e fica ambíguo quais campos pertencem ao objeto properties. Isso importa porque a lista required é a única fonte que diz que numero_prenotacao é obrigatório, e é essa informação que o erro faz perder.

Proposta. Corrigir a chave órfã e, antes de publicar, submeter o bloco a um validador de JSON Schema. É verificação de um comando, automatizável no fluxo de geração do documento.

5. categoria_poligono exige maiúsculo, contra o próprio schema — Média

Evidência. O schema da seção 2 define o domínio do campo em minúsculo:

"categoria_poligono": {
  "type": "string",
  "enum": ["urbano", "rural"]
}

E o exemplo de corpo de requisição, logo acima, usa "categoria_poligono": "urbano".

A API de produção rejeita esse valor. O aceito é URBANO / RURAL, em maiúsculas.

Impacto. A divergência quebra na primeira chamada e custa depuração desproporcional ao tamanho do problema. Quem segue o manual à risca, inclusive copiando o exemplo, recebe erro, e o erro não indica que a causa está na caixa do texto. Um enum explícito no schema é o artefato em que se confia para não ter de testar valor por valor.

Proposta. Alinhar schema, exemplo e API. Se o comportamento correto é maiúsculo, corrigir o enum para ["URBANO", "RURAL"] e atualizar o exemplo. Alternativa mais tolerante: normalizar a caixa no recebimento e aceitar as duas formas.

6. BASE_URL com www não resolve, e o manual se contradiz — Média

Evidência. A seção 1 estabelece:

BASE_URL: https://www.mapa.onr.org.br/

Todos os endpoints da seção 2 são montados a partir dessa base. O subdomínio www.mapa.onr.org.br não resolve no DNS.

O documento ainda se contradiz: a seção 5, passo 1, instrui o acesso a https://mapa.onr.org.br/sigri/intranet, sem www. As duas formas convivem no mesmo manual, e só a segunda funciona.

Impacto. Falha na primeira requisição, com erro de resolução de nome, que não sugere ao implementador ter o manual como causa. O host correto é https://mapa.onr.org.br, o mesmo do portal.

Proposta. Corrigir a BASE_URL da seção 1 para o host sem www e uniformizar as ocorrências ao longo do documento. Se o www for um alias pretendido, criar o registro DNS correspondente.

7. Status terminais nunca são definidos — Média

Evidência. A seção 4 recomenda backoff exponencial no polling e determina:

“O polling deve cessar assim que um status terminal for recebido.”

A seguir, lista onze status. Nenhum é marcado como terminal. A lista mistura um identificador técnico (WAITING_CONFIRMATION) com frases descritivas em linguagem natural (“Processamento finalizado com sucesso”, “Erro identificado ao tentar salvar o polígono no banco de dados”, “Arquivos em processo de envio”).

E o exemplo de resposta do endpoint de status, na seção 2, devolve:

"data": { "status": "PROCESSANDO" }

PROCESSANDO não consta da lista da seção 4.

Impacto. A instrução é impossível de cumprir como escrita, porque manda parar num conjunto que o documento não delimita. Cada implementador precisa inferir quais estados são finais e classificar frases em português, sujeitas a variação de acento, caixa e redação, em vez de comparar códigos estáveis. Um cliente que erre a inferência entra em polling infinito ou desiste de uma importação que ainda seria concluída.

Em nossa implementação, a comparação é feita por trecho da frase, insensível a acento e caixa, porque não há código para comparar.

Proposta.

• Publicar os status como códigos estáveis (o padrão que WAITING_CONFIRMATION já sugere), com a frase em português como campo descritivo separado;
• Marcar na tabela quais são terminais, e entre estes quais representam sucesso e quais representam falha;
• Incluir PROCESSANDO na lista, ou corrigir o exemplo para um valor existente.

8. CLASSIFICA e classificacao_poligonos são coisas diferentes — Média

Evidência. O envio carrega dois campos de “classificação”, com nomes próximos e domínios incompatíveis, em lugares distintos:

	classificacao_poligonos	CLASSIFICA
Onde	Corpo da requisição (JSON)	Atributo do shapefile
Domínio	1 a 10	1 a 3
Significa	Natureza do envio	Origem e qualidade da geometria
Valores	Geral, Loteamento, Usucapião, Retificação, REURB, Definido pelo RI1, Definido pelo RI2, Estrangeiro, Fusão, Desmembramento	A (certificado), B (sem certificação), C (desenho sobre satélite)

Impacto. A confusão é fácil e o erro é silencioso, já que ambos são inteiros pequenos e válidos nos dois domínios. Enviar 3 pensando em CLASSIFICA quando o campo é classificacao_poligonos classifica o polígono como Usucapião; o inverso classifica a geometria como desenho sobre imagem de satélite.

Há aqui uma consequência normativa que costuma passar despercebida. O CLASSIFICA = 1 corresponde à categoria A, georreferenciado rural com certificação do Incra, ou urbano com ART. É o grupo do art. 343-C cuja alimentação tem prazo de um ano contado da vigência do Provimento 195. Declarar um imóvel certificado como categoria B equivale a afirmar que ele está fora do grupo cuja obrigação vence agora.

Proposta. Renomear um dos dois campos para eliminar a ambiguidade (natureza_importacao para o do payload, por exemplo) e incluir na seção 6 uma nota ligando CLASSIFICA às categorias do art. 343-C do CNN/CN/CNJ-Extra, com menção ao prazo aplicável a cada uma.

9. Cinco dos 34 campos têm a descrição truncada — Baixa

Evidência. Na tabela de atributos da seção 6, a coluna “Descrição” foi cortada pela largura da célula em cinco campos: CCIR_SNCR, SIGEF, SNCI, CIB_NIRF e ITBI. O que se lê é “Número do Certificado de”, “Número do Sistema de Gestão”, “Número do Sistema Nacional”, “Número do Cadastro Imobiliário” e “Valor do ITBI (transferência)”. O restante não aparece.

Impacto. A especificação oficial de 15% dos campos está ilegível. Os nomes usuais dos cadastros permitem inferir o sentido pretendido, mas inferência não substitui especificação. CIB_NIRF reúne dois cadastros distintos no mesmo campo, e sem a descrição completa não se sabe qual tem precedência quando o imóvel possui os dois, nem em que formato.

Proposta. Republicar a tabela com as descrições completas, incluindo para cada campo o formato esperado (com ou sem máscara) e o comportamento quando o dado não existe.

Achados menores

Sem impacto operacional relevante, mas indicativos de que o documento não passou por revisão técnica:

• O exemplo rotulado 400 Bad Request retorna "status": "422" no corpo;
• A resposta do endpoint de status usa a chave "mensagem:", com dois-pontos dentro do nome da chave;
• O código 401 Unauthorized é usado para “Sem permissao para confirmar esta importacao”, que descreve falta de permissão sobre o recurso, e não falha de autenticação; semanticamente, um 403;
• A numeração das seções salta de 2 para 4, e não existe seção 3;
• A seção do endpoint de status chama os valores de “Parâmetros da URL”, mas eles trafegam no corpo da requisição;
• A seção 1 diz que a chave é gerada por perfis “Oficial ou Substituto”; o passo 1 da mesma seção acrescenta “ou Preposto”.

Duas notas de operação

Dois pontos que não chegam a ser defeitos, mas mudam o dimensionamento do esforço para quem tem acervo grande.

O token vale 15 dias. É gerado manualmente no portal, por usuário autenticado com certificado digital ICP-Brasil, e expira automaticamente. Para uma serventia que vai alimentar milhares de matrículas ao longo de meses, isso significa uma renovação manual a cada duas semanas, dependente da presença do Oficial ou do Substituto. O manual informa que chaves antigas continuam válidas até expirar e que é possível manter várias simultâneas. Isso permite sobrepor janelas e evitar interrupção, desde que a rotina esteja prevista.

As URLs assinadas expiram em 30 minutos. O campo expires_in_minutes da resposta traz esse valor. Como cada importação sobe quatro arquivos, um lote grande precisa ser fatiado em janelas que caibam nesse limite, com nova geração de URLs a cada bloco. O manual não declara isso como restrição de projeto em nenhum ponto; o valor aparece só como um campo da resposta.

Conclusão

O SIG-RI só cumpre o papel que o Provimento 195 lhe atribui, o controle da malha imobiliária, da disponibilidade e da unicidade matricial, se o que cada cartório envia for fiel ao que está na matrícula. Dos nove achados acima, seis são correções de baixo esforço no documento ou no script: uma chave órfã, um enum, um host, uma tabela truncada, uma lista de status, uma precisão decimal.

Os outros dois pedem decisão de modelagem. A impossibilidade de representar condomínio fracionado é a mais séria, porque a informação perdida, quem é titular de qual fração, alimenta o controle de disponibilidade que a norma quer exercer. A ausência de um sistema de coordenadas documentado transforma em tentativa e erro o que deveria ser uma linha de especificação.

Documentamos os achados de forma aberta para que possam ser verificados, contestados ou incorporados por quem mantém a especificação. É a mesma contribuição que já fizemos do lado da escrituração, em SREI e ITN-04: 14 Melhorias para a Interoperabilidade, e do lado do envio de atos, em ITN-03 na Prática. Um padrão mais sólido reduz o custo de adoção, e com o prazo do art. 343-F correndo esse custo se paga em tempo.

Críticas, correções e dúvidas sobre qualquer um dos achados são bem-vindas em suporte@mupisystems.com.br.

Os achados deste artigo referem-se ao Manual API para Envio dos Polígonos, versão 1.0, do Mapa do Registro de Imóveis (ONR), e foram levantados a partir de uma implementação de referência exercitada contra a API de produção. Achados de divergência descrevem o comportamento observado na data de publicação e podem ser corrigidos em versões posteriores do manual ou da API.