{
  "openapi": "3.0.1",
  "info": {
    "title": "Montenegro WebGIS — API de Integração Territorial e Tributária",
    "description": "API RESTful para integração de dados geoespaciais, cartográficos e alfanuméricos entre a plataforma WebGIS Montenegro e sistemas de gestão tributária / ERP municipais (Thema).\n\n### Principais Recursos:\n- **Áreas Geométricas PostGIS**: Consulta de área real do lote, perímetro, projeção predial de edificações e divergências cadastrais.\n- **Recadastro Imobiliário (RECAD)**: Abertura e manutenção de recadastramentos para atualização de proprietário, endereço e características físicas.\n- **Auditoria & Rastreabilidade**: Log rigoroso de modificações cartográficas e cadastrais com registro de justificativa, data/hora e operador.",
    "version": "1.0.0",
    "contact": {
      "name": "Suporte Técnico WebGIS Montenegro",
      "url": "https://geowise.com.br"
    }
  },
  "servers": [
    {
      "url": "/gaussvision",
      "description": "Servidor de Produção / WebGIS"
    },
    {
      "url": "",
      "description": "Ambiente Local / Raiz"
    }
  ],
  "tags": [
    {
      "name": "Territoriais & Áreas Geométricas",
      "description": "Cálculo de áreas geométricas via PostGIS, perímetros, confrontações e análise de divergências cartográficas vs cadastro tributário do IPTU."
    },
    {
      "name": "Recadastro & Proprietários",
      "description": "Abertura de processos de recadastramento (RECAD) e atualização de proprietários, titularidades e contatos."
    },
    {
      "name": "Auditoria & Rastreabilidade",
      "description": "Histórico detalhado de modificações alfanuméricas e cartográficas com justificativa obrigatória e rastreabilidade por operador."
    },
    {
      "name": "Edificações & Áreas Construídas",
      "description": "Projeção de polígonos de edificações sobre lotes e cálculo de área construída cartográfica."
    },
    {
      "name": "Boletim de Informações Cadastrais (BIC)",
      "description": "Ficha cadastral completa do imóvel com unidades, dados de lote e tributação."
    }
  ],
  "paths": {
    "/api/integracao/territorial/areas": {
      "get": {
        "tags": ["Territoriais & Áreas Geométricas"],
        "summary": "Consulta de Áreas Geométricas e Divergência Cadastral",
        "description": "Retorna as áreas cartográficas calculadas via PostGIS (`ST_Area` e `ST_Perimeter` em m²), confrontadas com a área cadastral do IPTU (`areaterreno`), apontando a divergência em m² e percentual, além da área de projeção de edificações que intersectam a parcela.",
        "parameters": [
          {
            "name": "inscricao",
            "in": "query",
            "description": "Inscrição imobiliária municipal (ex: 3831619)",
            "required": false,
            "schema": { "type": "string", "example": "3831619" }
          },
          {
            "name": "chave",
            "in": "query",
            "description": "Chave cartográfica do lote (ex: 010050001201)",
            "required": false,
            "schema": { "type": "string", "example": "010050001201" }
          },
          {
            "name": "tolerancia_pct",
            "in": "query",
            "description": "Percentual de tolerância para alertar divergência relevante (default: 5.0%)",
            "required": false,
            "schema": { "type": "number", "default": 5.0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Cálculo de áreas e dados cadastrais obtidos com sucesso",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "inscricao": "3831619",
                  "proprietario": {
                    "nome_cadastral": "CONTRIBUINTE MODELO POC",
                    "cpf_cnpj": "000.000.000-00",
                    "nome_recadastro": "NOVO PROPRIETÁRIO EXEMPLO"
                  },
                  "localizacao": {
                    "logradouro": "AVENIDA CORONEL JOSÉ SOARES MARCONDES",
                    "numero": "1200",
                    "bairro": "CENTRO",
                    "setor": "01",
                    "quadra": "0050",
                    "lote": "0012",
                    "centroide": { "lat": -22.1255, "lng": -51.3889 }
                  },
                  "dados_geometricos": {
                    "area_cartografica_m2": 360.00,
                    "perimetro_cartografico_m": 76.00,
                    "area_cadastral_m2": 250.00,
                    "divergencia_area_m2": 110.00,
                    "divergencia_area_percentual": 44.00,
                    "tolerancia_aplicada_pct": 5.0,
                    "divergencia_relevante": true,
                    "testada_cadastral_m": 12.0,
                    "projecao_edificada_cartografica_m2": 140.00,
                    "area_construida_cadastral_m2": 110.00,
                    "qtd_edificacoes_cartograficas": 1,
                    "srid": 31982
                  },
                  "recadastro": {
                    "possui_recadastro": true,
                    "recad_id": 101,
                    "status": "pendente"
                  }
                }
              }
            }
          },
          "400": { "description": "Parâmetros inválidos" },
          "404": { "description": "Imóvel não localizado" }
        }
      }
    },
    "/api/integracao/territorial/divergencias": {
      "get": {
        "tags": ["Territoriais & Áreas Geométricas"],
        "summary": "Ranking de Imóveis com Divergência de Área",
        "description": "Lista os imóveis onde a área geométrica calculada na cartografia diverge da área tributária cadastrada no IPTU, ordenados pela maior discrepância em m².",
        "parameters": [
          {
            "name": "min_divergencia_m2",
            "in": "query",
            "description": "Divergência mínima em metros quadrados para o filtro (default: 10 m²)",
            "required": false,
            "schema": { "type": "number", "default": 10.0 }
          },
          {
            "name": "bairro",
            "in": "query",
            "description": "Filtrar por nome do bairro",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Quantidade máxima de registros retornados (máximo: 100)",
            "required": false,
            "schema": { "type": "integer", "default": 20 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Deslocamento para paginação",
            "required": false,
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": { "description": "Lista de divergências gerada com sucesso" }
        }
      }
    },
    "/api/integracao/territorial/lote/{chave}/geojson": {
      "get": {
        "tags": ["Territoriais & Áreas Geométricas"],
        "summary": "Exporta Feição Vetorial do Lote em GeoJSON",
        "description": "Retorna o polígono vetorial do lote em padrão GeoJSON (EPSG:4326), contendo área calculada e chaves cadastrais.",
        "parameters": [
          {
            "name": "chave",
            "in": "path",
            "description": "Chave cartográfica do lote",
            "required": true,
            "schema": { "type": "string", "example": "010050001201" }
          }
        ],
        "responses": {
          "200": { "description": "Feature GeoJSON retornada com sucesso" },
          "404": { "description": "Lote não encontrado" }
        }
      }
    },
    "/api/integracao/cadastro/proprietario/{inscricao}": {
      "get": {
        "tags": ["Recadastro & Proprietários"],
        "summary": "Consulta Proprietário, CPF/CNPJ e Endereço do Imóvel",
        "description": "Retorna o nome do proprietário registrado no cadastro tributário municipal, CPF/CNPJ, situação cadastral, endereço completo do imóvel e dimensões do lote (setor, quadra, lote, sublote, áreas). Exige autenticação por API Key ou Bearer token.",
        "parameters": [
          {
            "name": "inscricao",
            "in": "path",
            "description": "Inscrição imobiliária municipal",
            "required": true,
            "schema": { "type": "string", "example": "458000" }
          }
        ],
        "responses": {
          "200": { "description": "Dados do proprietário e do imóvel retornados com sucesso" },
          "404": { "description": "Imóvel não localizado" }
        }
      }
    },
    "/api/integracao/edificacoes/lote/{inscricao}": {
      "get": {
        "tags": ["Edificações & Áreas Construídas"],
        "summary": "Edificações e Projeção Construtiva sobre o Lote",
        "description": "Identifica as edificações cartográficas poligonais vinculadas ao lote correspondente à inscrição informada, totaliza a projeção geométrica e confronta com a área cadastral do IPTU exibindo a divergência.",
        "parameters": [
          {
            "name": "inscricao",
            "in": "path",
            "description": "Inscrição imobiliária",
            "required": true,
            "schema": { "type": "string", "example": "458000" }
          }
        ],
        "responses": {
          "200": { "description": "Edificações listadas com sucesso" }
        }
      }
    },
    "/api/integracao/recadastro/proprietario": {
      "post": {
        "tags": ["Recadastro & Proprietários"],
        "summary": "Atualiza Proprietário via Recadastro com Justificativa e Auditoria",
        "description": "Permite que sistemas tributários municipais ou operadores de fiscalização atualizem os dados do proprietário (nome, CPF/CNPJ, titularidade, documento comprobatório, e-mail, whatsapp). O sistema registra automaticamente a modificação no log de auditoria cadastral com valor anterior, novo valor, usuário e justificativa formal.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["inscricao", "proprietario", "justificativa"],
                "properties": {
                  "inscricao": {
                    "type": "string",
                    "example": "3831619",
                    "description": "Inscrição imobiliária a ser atualizada"
                  },
                  "proprietario": {
                    "type": "object",
                    "required": ["nome"],
                    "properties": {
                      "nome": { "type": "string", "example": "NOVO PROPRIETÁRIO EXEMPLO" },
                      "cpf_cnpj": { "type": "string", "example": "123.456.789-00" },
                      "titularidade": { "type": "string", "example": "Proprietário Titular" },
                      "doc_titularidade": { "type": "string", "example": "Matrícula do RI" },
                      "num_doc_titularidade": { "type": "string", "example": "99.999-L1" },
                      "email": { "type": "string", "example": "contato@exemplo.com.br" },
                      "whatsapp": { "type": "string", "example": "(18) 99999-0000" }
                    }
                  },
                  "justificativa": {
                    "type": "string",
                    "example": "Averbação de Compra e Venda registrada no Cartório de Registro de Imóveis",
                    "description": "Motivo formal da alteração (obrigatório para auditoria da PoC)"
                  },
                  "agente": {
                    "type": "string",
                    "example": "Auditor Fiscal Tributário Municipal",
                    "description": "Identificação do operador ou sistema de origem"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Proprietário atualizado e alterações gravadas no log de auditoria",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "mensagem": "Dados de proprietário atualizados com sucesso e auditados.",
                  "recad_id": 101,
                  "inscricao": "3831619",
                  "justificativa": "Averbação de Compra e Venda registrada no Cartório de Registro de Imóveis",
                  "alteracoes_registradas": [
                    {
                      "campo": "proprietario.nome",
                      "valor_anterior": "CONTRIBUINTE ANTERIOR MODELO",
                      "valor_novo": "NOVO PROPRIETÁRIO EXEMPLO"
                    }
                  ],
                  "total_campos_alterados": 1
                }
              }
            }
          },
          "400": { "description": "Dados inconsistentes ou campos obrigatórios ausentes" },
          "404": { "description": "Imóvel não encontrado" }
        }
      }
    },
    "/api/integracao/recadastro/{inscricao}": {
      "get": {
        "tags": ["Recadastro & Proprietários"],
        "summary": "Consulta Status e Dados do Recadastro",
        "description": "Retorna o status atual do recadastro imobiliário (pendente, aprovado, revisado), dados vigentes de identificação, proprietário e características do terreno.",
        "parameters": [
          {
            "name": "inscricao",
            "in": "path",
            "description": "Inscrição imobiliária",
            "required": true,
            "schema": { "type": "string", "example": "3831619" }
          }
        ],
        "responses": {
          "200": { "description": "Dados do recadastro retornados com sucesso" }
        }
      }
    },
    "/api/integracao/recadastro/historico/{inscricao}": {
      "get": {
        "tags": ["Auditoria & Rastreabilidade"],
        "summary": "Histórico Completo de Alterações e Auditoria do Imóvel",
        "description": "Retorna o extrato cronológico de todas as modificações realizadas nos dados cartográficos e alfanuméricos do imóvel, exibindo valor anterior, novo valor, operador responsável, justificativa formal e data/hora. Cumpre integralmente o requisito de auditoria cadastral da PoC.",
        "parameters": [
          {
            "name": "inscricao",
            "in": "path",
            "description": "Inscrição imobiliária",
            "required": true,
            "schema": { "type": "string", "example": "3831619" }
          }
        ],
        "responses": {
          "200": {
            "description": "Extrato de auditoria retornado com sucesso",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "inscricao": "3831619",
                  "total_modificacoes": 1,
                  "historico": [
                    {
                      "auditoria_id": 101,
                      "inscricao": "3831619",
                      "setor": "01",
                      "quadra": "0050",
                      "lote": "0012",
                      "tipo": "proprietario",
                      "campo": "proprietario.nome",
                      "valor_anterior": "CONTRIBUINTE ANTERIOR MODELO",
                      "valor_novo": "NOVO PROPRIETÁRIO EXEMPLO",
                      "agente": "Auditor Tributário Municipal (PoC) [Justificativa: Averbação de Compra e Venda no Registro de Imóveis]",
                      "data_hora": "2026-09-28T08:00:00.000Z"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/cadastro/bic": {
      "get": {
        "tags": ["Boletim de Informações Cadastrais (BIC)"],
        "summary": "Boletim de Informações Cadastrais (BIC)",
        "description": "Retorna o espelho cadastral tributário completo (dados gerais, testadas, áreas, características de infraestrutura do logradouro e unidades prediais).",
        "parameters": [
          {
            "name": "inscricao",
            "in": "query",
            "description": "Inscrição imobiliária",
            "required": true,
            "schema": { "type": "string", "example": "3831619" }
          }
        ],
        "responses": {
          "200": { "description": "Ficha cadastral retornada com sucesso" }
        }
      }
    },
    "/api/cadastro/lote-geom": {
      "get": {
        "tags": ["Territoriais & Áreas Geométricas"],
        "summary": "Geometria do Lote para WebGIS",
        "description": "Retorna a geometria do lote correspondente à inscrição em formato GeoJSON WGS84 para renderização direta no mapa.",
        "parameters": [
          {
            "name": "inscricao",
            "in": "query",
            "description": "Inscrição imobiliária",
            "required": true,
            "schema": { "type": "string", "example": "3831619" }
          }
        ],
        "responses": {
          "200": { "description": "Geometria retornada com sucesso" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "ATENÇÃO: Cole a Chave de API de Montenegro abaixo. Chave Padrão de Homologação: gw_montenegro_2026_api"
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ]
}