API de integração

Visão geral

• Endereço base: https://geometodo.tech/api/v1/{cidade}, onde {cidade} é o identificador do município no geoportal (ex.: araguainha).
• Somente HTTPS. Respostas em JSON (UTF-8).
• Inscrições como no cadastro municipal (ex.: lote 01.002.0001, unidade 01.002.0001.001).
• Geometrias em SIRGAS 2000 geográfico (EPSG:4674), em GeoJSON ou WKT, quando pedidas.

curl -H "Authorization: Bearer $CHAVE" \
  "https://geometodo.tech/api/v1/araguainha/lotes?por_pagina=2"

Autenticação

Cada sistema usa uma chave própria, criada pelo administrador do município no geoportal (Administração → API). A chave aparece uma única vez, na criação; guarde-a como senha. Envie-a em todas as requisições:

Authorization: Bearer gm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Uma chave vale só para o seu município. Para trocar uma chave, crie a nova, atualize o sistema e revogue a antiga.

Convenções

• Datas: AAAA-MM-DD; datas e horas: ISO 8601 com fuso (ex.: 2026-09-01T00:00:00-03:00). Números decimais com ponto.
• Áreas em m², extensões em metros. Campo sem informação vem como null.
• Listas paginadas: pagina (a partir de 1) e por_pagina (padrão 100, máximo 500). A resposta traz paginacao.proxima com o caminho da página seguinte, ou null na última.
• Feeds (alterações, transferências) usam cursor: guarde o proximo_apos_id e peça apos_id com ele na próxima vez.
• situacao: ativo (padrão), extinto ou todos. Lotes e unidades extintos (desmembramento, unificação) continuam consultáveis.

{
  "dados": [ ... ],
  "paginacao": { "pagina": 1, "por_pagina": 100, "total": 139, "proxima": "/api/v1/araguainha/lotes?pagina=2" }
}

Erros e limites

{ "erro": { "codigo": "chave_invalida", "mensagem": "Chave inválida ou revogada." } }

Lotes

GET/{cidade}/lotesescopo cadastro

GET/{cidade}/lotes/{inscricao}escopo cadastro

curl -H "Authorization: Bearer $CHAVE" \
  "https://geometodo.tech/api/v1/araguainha/lotes/01.002.0001?geometria=geojson"

{
  "dados": {
    "inscricao": "01.002.0001",
    "situacao": "ativo",
    "setor": "01", "quadra": "002", "numero": "1",
    "loteamento": "Núcleo Cohab",
    "bairro": "Núcleo Cohab",
    "endereco": { "logradouro": "Rua Ricardo Franco", "numero": null },
    "testadas": [
      { "logradouro": "Rua Ricardo Franco", "extensao_m": 13.24, "principal": true },
      { "logradouro": "Avenida João Ponce de Arruda", "extensao_m": 26.76, "principal": false }
    ],
    "area_medida_m2": 360.21,
    "area_matricula_m2": null,
    "matricula": null, "cartorio_cns": null, "cib": null,
    "edificacoes": { "quantidade": 0, "area_construida_m2": null, "pavimentos_max": null },
    "unidades": 0,
    "versao": 1,
    "atualizado_em": "2026-09-24T18:10:12.345Z",
    "extinto_em": null,
    "geometria": { "type": "MultiPolygon", "coordinates": [ ... ] },
    "srid": 4674
  }
}

area_medida_m2 é calculada da geometria do levantamento (elipsoide GRS80); area_matricula_m2 é a área declarada na matrícula do Registro de Imóveis.

Unidades imobiliárias

A unidade é a base do lançamento do IPTU: casa, apartamento, sala ou terreno. O campo cib traz o código do Cadastro Imobiliário Brasileiro atribuído pelo SINTER (Receita Federal) à unidade, quando o município já fez a remessa; é nulo antes disso.

GET/{cidade}/unidadesescopo cadastro

GET/{cidade}/unidades/{inscricao}escopo cadastro

curl -H "Authorization: Bearer $CHAVE" \
  "https://geometodo.tech/api/v1/demonstracao/unidades/01.001.0001.001?incluir=titulares"

{
  "dados": {
    "inscricao": "01.001.0001.001",
    "inscricao_lote": "01.001.0001",
    "situacao": "ativo",
    "cib": "K7M2QX4P",
    "uso": { "codigo": "RES", "descricao": "Residencial" },
    "endereco": { "logradouro": "Avenida Brasil", "numero": "24", "complemento": null },
    "area_privativa_m2": null,
    "fracao_ideal": null,
    "edificacao": { "pavimentos": 1, "ano_construcao": 2016, "area_construida_m2": 184.93 },
    "titulares": [
      {
        "nome": "Compradora Demonstração", "tipo": "fisica", "cpf_cnpj": "52998224725",
        "vinculo": "proprietario", "percentual": 100, "responsavel_tributario": true, "inicio": "2026-09-22"
      }
    ],
    "versao": 1,
    "atualizado_em": "2026-09-24T20:17:31.000Z"
  }
}

Pessoas: busca por CPF/CNPJ e nome

Localiza o contribuinte e todos os imóveis em que ele é titular: pelo CPF/CNPJ (exato) ou pelo nome ou razão social (aproximado, sem acento e tolerante a erro de digitação). Útil para atendimento, certidões e conferência do cadastro de contribuintes do tributário.

GET/{cidade}/pessoas?cpf_cnpj={cpf_cnpj}escopo titulares

GET/{cidade}/pessoas?nome={nome}escopo titulares

GET/{cidade}/pessoas/{cpf_cnpj}escopo titulares

curl -H "Authorization: Bearer $CHAVE"   "https://geometodo.tech/api/v1/demonstracao/pessoas?nome=joao%20almeda"

{
  "dados": [
    {
      "cpf_cnpj": "00729164004", "tipo": "fisica", "nome": "João Campos Almeida",
      "contato": {
        "email": null, "telefone": "+55 19 981234567", "telefone2": null,
        "endereco_correspondencia": "Rua Tiradentes, 120 – Centro – Município de Demonstração/SP – CEP 13500-000",
        "endereco": { "logradouro": "Rua Tiradentes", "numero": "120", "complemento": null, "bairro": "Centro",
                      "cidade": "Município de Demonstração", "uf": "SP", "cep": "13500000", "conferido_no_cadastro": true }
      },
      "relevancia": 0.45,
      "atualizado_em": "2026-09-24T12:00:00.000Z",
      "imoveis": [
        {
          "inscricao_unidade": "01.021.0011.002", "inscricao_lote": "01.021.0011",
          "endereco": { "logradouro": "Avenida Rui Barbosa", "numero": "275", "complemento": "Apto 102" },
          "vinculo": "proprietario", "percentual": 100, "responsavel_tributario": true,
          "inicio": "2019-07-05", "fim": null, "vigente": true
        }
      ]
    }
  ]
}

No exemplo, “joao almeda” (sem acento e com erro) encontra “João Campos Almeida”. A busca por CPF/CNPJ devolve no máximo uma pessoa (lista vazia se não houver). Pessoas sem CPF/CNPJ cadastrado aparecem na busca por nome, com cpf_cnpj nulo. Cada consulta é registrada como acesso a dado pessoal.

Alterações

Tudo o que mudou no cadastro, em ordem, a partir do log de auditoria: é o que permite ao sistema tributário atualizar só o necessário.

GET/{cidade}/alteracoesescopo cadastro

{
  "dados": [
    { "id": 3601, "quando": "2026-09-24T20:17:31Z", "entidade": "titularidade", "operacao": "inclusao",
      "inscricao": "01.001.0001.001", "campos": ["unidade_id", "pessoa_id", "vinculo", "percentual", "..."] },
    { "id": 3602, "quando": "2026-09-24T20:17:31Z", "entidade": "lote", "operacao": "alteracao",
      "inscricao": "01.001.0001", "campos": ["matricula", "cartorio_cns"] }
  ],
  "cursor": { "proximo_apos_id": 3602, "ultimo_id": 3602, "tem_mais": false,
              "proxima": "/api/v1/demonstracao/alteracoes?apos_id=3602" }
}

Transferências

Mudanças de titularidade registradas com a matrícula atualizada do Registro de Imóveis.

GET/{cidade}/transferenciasescopo titulares

{
  "dados": [
    {
      "id": 1, "inscricao_lote": "01.001.0001", "unidades": ["01.001.0001.001"],
      "natureza": "compra_venda", "matricula": "45678", "cartorio_cns": "112233",
      "ato_registro": "R-4/45.678", "data_registro": "2026-09-22", "processo": "PA 4.321/2026",
      "registrada_em": "2026-09-24T20:17:31Z",
      "adquirentes": [ { "nome": "Compradora Demonstração", "cpf_cnpj": "52998224725", "vinculo": "proprietario",
                         "percentual": 100, "responsavel_tributario": true } ],
      "transmitentes": [ { "nome": "André Teixeira Pereira", "cpf_cnpj": "...", "vinculo": "proprietario" } ]
    }
  ],
  "cursor": { "proximo_apos_id": 1, "tem_mais": false }
}

Naturezas: compra_venda, doacao, heranca, usucapiao, adjudicacao, permuta, dacao, regularizacao, outra.

Sincronização recomendada

1. Carga inicial: antes de começar, chame /alteracoes?limite=1 e guarde cursor.ultimo_id; depois percorra /unidades?incluir=titulares e /lotes página a página. O que mudar durante a carga aparece no feed a partir desse cursor.
2. Atualização periódica (ex.: de hora em hora): chame /alteracoes?apos_id=o cursor guardado; para cada inscrição recebida, busque o registro atualizado em /lotes/{inscricao} ou /unidades/{inscricao}?incluir=titulares; grave o novo cursor só depois de processar tudo.
3. Transferências: para o cadastro de contribuintes, acompanhe /transferencias?apos_id= da mesma forma.

cursor = ler_cursor()                                  # 0 na primeira vez
repita:
    r = GET /alteracoes?apos_id={cursor}&limite=1000
    para cada a em r.dados:
        se a.entidade em (unidade, titularidade): atualizar_unidade(GET /unidades/{a.inscricao}?incluir=titulares)
        se a.entidade em (lote, testada, edificacao): atualizar_lote(GET /lotes/{a.inscricao})
    cursor = r.cursor.proximo_apos_id; gravar_cursor(cursor)
até r.cursor.tem_mais == falso

Segurança e LGPD

• Toda chamada fica registrada (chave, sistema, endpoint, quantidade de resultados, IP), visível ao administrador do município.
• Consultas com titulares e as buscas de pessoas são registradas como acesso a dado pessoal.
• Guarde a chave no servidor do sistema, nunca em código de navegador ou aplicativo.
• Chave comprometida: o administrador revoga na hora (Administração → API) e cria outra.
• Laudos com código de verificação podem ser conferidos publicamente em /verificar.

Versões

v1 (atual). Campos novos podem ser acrescentados sem aviso; mudanças que quebrem a integração virão numa nova versão (/api/v2), mantendo a anterior por um período de transição.