Contribuintes (Cadastro Central)

O Cadastro Central é a fonte única de verdade de quem o município tributa e cobra: o contribuinte (pessoa singular ou colectiva) e os seus objectos tributáveis — imóveis (IPRA), veículos (IAV) e estabelecimentos (IPA / licenças). Tudo o que a Tributação lança e a Tesouraria cobra aponta para uma ficha deste cadastro. A conta do munícipe no portal liga-se também a uma ficha daqui.

Secção	Menus
Gestão tributária	Contribuintes (lista · ficha · novo/editar)
Ficha do contribuinte	Dados · Imóveis · Veículos · Estabelecimentos · Conta-corrente · Histórico
Sistema / Administração	Parâmetros (P, categoria do município, tabelas FA/FI — usados no Valor Patrimonial)
Portal do munícipe	Registar conta · Meus bens · Consultar dívida

Permissões

O módulo abre com qualquer um de dois pares de permissões:

Acção	Permissão aceite
Ver lista, ficha, extracto	cadastro.view ou tributacao.view
Criar/editar contribuinte, registar bens, inativar	cadastro.manage ou tributacao.manage

Perfis padrão com escrita: Atendimento ao Munícipe, Técnico de Cadastro / GIS, Chefe de Urbanização, Vereador de Finanças (via tributacao.manage). O Tesoureiro e o Técnico de Tributação só lêem (cadastro.view).

WARNING

O menu Contribuintes na consola só aparece a quem tem tributacao.view, e os botões Registar imóvel / veículo / estabelecimento só a quem tem tributacao.manage. Um utilizador só com cadastro.* tem acesso pela API mas pode não ver o menu (não verificado no ecrã).

Lista de contribuintes

Gestão tributária › Contribuintes. Cartões no topo: Contribuintes (singulares · colectivos), Ativos, NUIT não verificado (com % sobre os activos), Cadastros incompletos (não tributáveis) e Dívida em aberto (agregada) — soma dos saldos de conta-corrente no âmbito filtrado.

• Pesquisa (300 ms de atraso): nome, NUIT, nº de documento ou código;
• Filtros: Tipo (Singular/Coletivo), Estado (Ativo/Inativo), Bairro, NUIT (verificado / não verificado);
• Colunas: Código · Nome/Designação · NUIT (com selo verificado/não verificado) · Bairro · Imóveis · Saldo (dívida, a vermelho se > 0) · Estado;
• Ordenação por defeito: código. A API aceita ordenar por codigo, nome, nuit, tipo, estado, saldo_conta_corrente, total_imoveis, total_veiculos, total_estabelecimentos, created_at, updated_at;
• Clicar na linha abre a ficha. Botão Novo contribuinte.

Cadastrar um contribuinte (passo a passo)

Contribuintes › Novo contribuinte. O código é gerado automaticamente (C000123, sequencial por município).

Campo	Obrigatório	Notas
Tipo de contribuinte	Sim	Singular (pessoa física) · Coletivo (empresa/entidade)
Nome completo / Razão social	Sim	máx. 200 caracteres
Tipo de documento	Não	Bilhete de Identidade · DIRE · Passaporte
Nº do documento	Condicional	máx. 60; único no município
NUIT	Condicional	exactamente 9 dígitos; único no município; obrigatório para pessoa colectiva
Data de nascimento	Não (só singular)	não pode ser futura; recomendada
Sexo	Não (só singular)	Masculino · Feminino
Bairro · Posto administrativo	Não	bairro recomendado (âmbito territorial e relatórios)
Telefone · Email	Não	email validado; telefone dígitos com + opcional
Morada	Não	máx. 255

Regras aplicadas no servidor (não só no browser):

1. Documento OU NUIT — uma ficha sem nenhum identificador é recusada; na edição também não é possível apagar o único identificador que resta;
2. Pessoa colectiva exige NUIT;
3. Duplicados — NUIT ou documento já existentes noutra ficha do município devolvem erro no próprio campo ("Já existe um contribuinte com este NUIT / documento");
4. Ao mudar o tipo para Coletivo, data de nascimento e sexo são limpos;
5. O NUIT nasce não verificado (nuit_verificado = false). Existe na API a acção Verificar NUIT (POST …/verificar-nuit), que marca a ficha como verificada com a data e regista a confirmação em Integrações › Verificações (NUIT/AT) — é uma confirmação manual do operador, sem consulta automática à AT. Botão na ficha: (não verificado).

Toda a criação/edição fica na trilha de auditoria (utilizador, IP, valores antes/depois).

Ficha do contribuinte

Cabeçalho com nome, código e tipo; acções Voltar, Editar e Inativar (se activo). Quatro cartões: Imóveis, Veículos, Estabelecimentos e Saldo (dívida).

Separador Dados

Código, tipo, nome/razão social, estado, documento, NUIT (com selo verificado/não verificado), data de nascimento e sexo (só singular), telefone, email, bairro, posto administrativo, morada e o selo Tributável (completo/incompleto).

Tributável (completo_para_tributacao) é derivado automaticamente: tem pelo menos um imóvel com Valor Patrimonial apurado, ou um veículo, ou um estabelecimento. Os contadores e este selo recalculam-se sempre que se cria, edita ou inactiva um bem.

Inativar

Um contribuinte nunca é apagado: a inactivação muda o estado para inativo e a ficha continua visível.

1. Inativar → diálogo com Motivo da inativação (obrigatório, 3–500 caracteres);
2. Se houver dívida em aberto (saldo > 0), o pedido é recusado com aviso: inativar retira os bens da emissão em massa do IPRA/IPA. Só passa reenviando com a confirmação de dívida (confirmar_divida) — o diálogo actual não expõe esse toggle (não verificado);
3. A mesma cautela aplica-se se mudar o estado para inativo pela edição.

DANGER

Um contribuinte inativo não aceita novos bens ("Não é possível registar bens tributáveis num contribuinte inativo") e os bens que já tem saem do universo do lançamento anual de IPRA/IPA. Reactive a ficha (Editar › estado Ativo) antes de lançar.

Imóveis (objecto do IPRA)

Separador Imóveis › Registar imóvel (diálogo). Coluna Tributável mostra se o imóvel tem VP apurado.

Campo	Obrigatório	Notas
Código	Não	gerado (IM000123) se vazio; único no município
Tipo	Sim	Habitacional (defeito) · Comercial · Industrial · Misto — determina a taxa do IPRA
Bairro	Não
Zona fiscal	Condicional	texto; tem de coincidir com uma zona da tabela FI publicada (por defeito: urbana, suburbana, turistica)
Área edificada — AE (m²)	Condicional	0 a 200 000
Área de logradouro — AL (m²)	Condicional	0 a 200 000
Ano de construção	Condicional	1900 até ano seguinte; deriva o FA
Factor de localização — FI	(pré-visualização)	ver nota abaixo
Longitude · Latitude	Não	-180…180 · -90…90

Regras do servidor:

• Sem nenhuma área (AE e AL vazios/0): o imóvel grava-se como rascunho, VP = 0, incompleto — não é erro, permite registar por etapas;
• Com alguma área: ano de construção e zona fiscal passam a ser obrigatórios (sem eles não há FA nem FI, logo não há VP);
• Se a idade não cair em nenhum escalão FA publicado, ou a zona não existir na tabela FI para a categoria do município, o registo é recusado com a mensagem respectiva.

Valor Patrimonial (VP)

O VP é calculado no servidor e nunca aceite do cliente. Fórmula do Decreto n.º 61/2010 (a mesma do motor tributário e do Simulador):

VP = (AE × P × FA + 0,05 × AL × P) × FI

Símbolo	Origem
AE, AL	áreas do imóvel (m²)
P	preço médio de construção (MT/m²) — parâmetro publicado P
FA	factor de antiguidade — escalão da tabela publicada fa pela idade (ano corrente − ano de construção)
FI	factor de localização — linha da tabela publicada fi pela zona fiscal + categoria do município (categoria_municipio)

Sem parametrização publicada, o imóvel com áreas não se regista

Não há valores por omissão. Se categoria_municipio, P, fa ou fi não estiverem publicados em Administração › Parâmetros, gravar um imóvel com áreas é recusado com uma mensagem que nomeia cada chave em falta.

É deliberadamente a porta fechada: factores por omissão davam um Valor Patrimonial — e logo uma base de IPRA e de SISA — que nenhuma assembleia deliberou, com o agravante de ninguém dar por isso. Um imóvel sem áreas continua a poder ser registado por etapas (VP = 0, incompleto).

O diálogo mostra um painel Valor Patrimonial (VP) — pré-visualização com o IPRA anual estimado, calculado no browser com o fiscal-engine e os parâmetros vigentes (mostra versão, P e categoria). O campo FI do formulário alimenta só essa pré-visualização e é validado contra os intervalos legais por categoria (A 0,75–1,50 · B 0,75–1,13 · C 0,70–1,12 · D 0,65–1,00); o valor gravado é sempre o que o servidor devolve a partir da tabela FI publicada.

TIP

Publique primeiro P, categoria_municipio, fa e fi em Administração › Parâmetros (com vigência e fundamento) — é o passo que abre o cadastro de imóveis. Editar um imóvel depois recalcula o VP com os parâmetros vigentes nesse dia — e o VP gravado é o que o lançamento em massa de IPRA usa.

Veículos (objecto do IAV)

Separador Veículos › Registar veículo.

Campo	Obrigatório	Notas
Matrícula	Sim	4–20 caracteres (letras, dígitos, hífen, espaço), guardada em maiúsculas, única no município
Categoria	Sim	Ligeiro (defeito) · Pesado de carga · Pesado de passageiros
Ano de fabrico	Não	1900 até ano seguinte
Marca · Modelo	Não	máx. 60

A API aceita ainda cilindrada_cm3 (0–20 000) e combustivel (gasolina/gasoleo), necessários para casar o veículo com a tabela do IAV — só persistem se a migração respectiva estiver aplicada e não estão no formulário (não verificado). O lançamento anual em massa não cobre IAV (só IPRA e IPA) — ver Tributação.

Estabelecimentos (objecto do IPA / licenças)

Separador Estabelecimentos › Registar estabelecimento.

Campo	Obrigatório	Notas
Designação	Sim	máx. 200; única por contribuinte (sem distinguir maiúsculas) — o IPA é emitido um por estabelecimento
CAE	Não	máx. 20
Nº de alvará	Não	máx. 60

Os bens (imóvel, veículo, estabelecimento) inactivam-se por soft-delete auditado; um bem inactivado sai dos contadores e da emissão em massa.

Conta-corrente e extracto

O cartão Saldo (dívida) é o saldo_conta_corrente mantido em cache pela plataforma. Movimentos que o alteram:

Evento	Efeito no saldo
Lançamento emitido (massa, manual, licenciamento, fiscalização, mercados)	+ valor
Isenção/redução ou recálculo	± diferença
Lançamento anulado ou prescrito	− valor
Pagamento aplicado numa guia	− valor pago
Pagamento anulado	+ valor

O saldo nunca desce abaixo de zero (arredondamentos ficam em registo). O separador Conta-corrente da ficha lista os lançamentos do contribuinte (receita, exercício, valor, estado, data). A API do extracto (GET …/contribuintes/{id}/extrato) devolve ainda as guias (número, total, pago, estado, referência, emissão, limite) e os pagamentos (guia, recibo, valor, meio, anulado) — a ficha só mostra os lançamentos.

O separador Histórico está sempre vazio na versão actual: não existe endpoint de auditoria por contribuinte; use Auditoria › Trilha com o filtro de entidade.

Importação e exportação

Não existe importação por ficheiro nem exportação da lista de contribuintes. O registo é individual, pelo formulário ou pela API.

Ligação ao portal do munícipe

A conta do munícipe em portal-sgm liga-se a uma ficha do Cadastro Central — não cria contribuintes.

1. Em Registar o munícipe indica NUIT (9 dígitos), nº de documento, email (obrigatório) e telefone (opcional);
2. O sistema procura uma única ficha com esse par NUIT + documento e confirma a identidade com os contactos gravados na ficha;
3. O código de verificação (OTP) vai para o telefone da ficha; se a ficha não tiver telefone, para o email da ficha — nunca para um contacto escolhido por quem se regista;
4. Só pode existir uma conta por contribuinte; é criado um utilizador municipe e a sessão fica ligada ao contribuinte_id.

Depois de entrar, o munícipe vê Meus bens (imóveis, veículos e estabelecimentos da sua ficha, com valor patrimonial), Guias, pagamentos e recibos próprios — ver Portal do munícipe. A consulta pública Consultar dívida (sem conta) funciona por NUIT ou por referência de pagamento.

WARNING

Se a ficha não tiver email nem telefone correctos, o munícipe não consegue registar-se. Ao atender ao balcão, confirme e actualize os contactos antes de o encaminhar para o portal.

Boas práticas de cadastro

• Preencha bairro e posto administrativo: alimentam o âmbito territorial dos perfis e os relatórios por território;
• Registe o NUIT sempre que exista — é o que permite verificar junto da AT e cruzar com a facturação;
• Para imóveis, conclua AE, AL, ano e zona antes do lançamento anual; um imóvel incompleto nunca entra no IPRA;
• Nunca crie uma segunda ficha para "corrigir" um NUIT — edite a existente; a unicidade é imposta por município.