CadastroMunicipio

Identificador externo. A rota /WsMunicipio/{codmun} aceita apenas dígitos do código IBGE municipal — de 1 a 7 posições (pattern ^\d{1,7}$). Tamanho real é validado em runtime via TamSX3("CC2_CODMUN"); pontuação ou letras retornam 400.

Read-only. Não há POST, PUT ou DELETE. A manutenção da CC2 é responsabilidade do complemento fiscal da TOTVS; expor escrita aqui contaminaria a base IBGE oficial. Para uso interno (vincular A1_COD_MUN a um cliente, por exemplo), o cliente da API consulta aqui e grava o código no endpoint da entidade pai.

Whitelist de campos retornados. Por padrão, o GET devolve o conjunto definido em CAMPOS_GET: CC2_EST, CC2_CODMUN, CC2_MUN, CC2_CAPITAL, CC2_CODANP, CC2_DDD, CC2_REGIAO. O parâmetro fields permite reduzir o conjunto, mas nunca expandi-lo — campos fora da whitelist provocam 400.

Paginação e page-out-of-range. /WsMunicipio usa page/pageSize (default 50, máx 500). Pedir uma página além do total não é erro: o endpoint responde 200 com data:[] e count:0. Cabe ao consumidor inferir fim da paginação quando count < pageSize ou data vazio.

Estratégia de índice por filtro. A listagem escolhe o índice mais seletivo automaticamente: codanp → est(+mun) → mun → scan completo. Sem filtro a operação varre a CC2 inteira (cara, intencionalmente não bloqueada como fallback de inspeção).

Busca normalizada (typeahead). /_search usa U_NoAcento para comparar termo e nome da base sem acento e case-insensitive. Termo mínimo de 2 caracteres; modo contains sem filtro de UF tem teto absoluto de 2.000 leituras (SEARCH_SCAN_CAP) para evitar varredura indiscriminada.