Tesouraria & Cobrança

A Tesouraria formaliza a dívida em guias/DUT (Documento Único de Tributação) com referência de pagamento, regista os pagamentos (balcão, mobile money, banco, POS), emite recibos numerados sem lacunas, concilia com extractos e fecha a caixa de cada operador. É também a única via pela qual uma dívida passa a paga — incluindo os pagamentos iniciados no portal do munícipe.

Secção	Menus
Tesouraria	Dashboard · Cobrança & Guias · Pagamentos · Recibos
Cobrança & Guias	Lista · Emitir guia · Ficha da guia (Lançamentos · Referência · Pagamentos)
Pagamentos	Pagamentos · Registar pagamento · Conciliação (Sessão de caixa · Importar extrato)
Recibos	Lista · 2.ª via (PDF)
Portal do munícipe	Guias · Pagar · Comprovativos · Recibos · Consultar dívida

Permissões

Acção	Permissão
Ver guias, pagamentos, recibos, caixa, dashboard	tesouraria.view
Emitir guia, registar pagamento, abrir/fechar caixa, submeter comprovativo, callback do provedor	tesouraria.manage
Conciliar manualmente e importar extracto	tesouraria.conciliar
Anular guia ou pagamento; fechar a caixa de outro operador	tesouraria.anular

Perfis padrão: o Tesoureiro tem view, manage e conciliar — não anula; a anulação é do Vereador de Finanças. Todas as mutações (emissão, pagamento, conciliação, anulação, abertura/fecho de caixa, importação) ficam na trilha de auditoria.

Dashboard

Tesouraria — Painel: Taxa de cobrança, Guias por liquidar, Receita do período, Caixas abertas, repartição por meio de pagamento (donut) e funil de estados das guias, com atalhos para Cobrança & Guias, Pagamentos e Recibos.

Guias / DUT

O que é uma guia

Uma guia agrega um ou mais lançamentos pendentes do mesmo contribuinte e do mesmo exercício, atribui um número e uma referência bancária, e marca os lançamentos como faturado. Cada lançamento incluído é uma linha (receita, descrição TIPO exercício · objecto, exercício, valor, juros).

Elemento	Regra
Número	GU-{exercício}-{000001} — sequência por município e exercício, sem lacunas
Referência de pagamento	13 dígitos AA MM SSSSSSS CC: exercício (2) · discriminante do município (2) · sequência anual (7) · dígitos de controlo (2); apresentada como 999 999 999 9999
Entidade	parâmetro publicado tesouraria.entidade_referencia; sem ele usa 11999 (valor por confirmar com o banco)
Data-limite	obrigatória e futura
Valor total	soma das linhas (+ juros quando vence)

WARNING

A referência é gerada uma vez e nunca recalculada — é o que está impresso na guia com que o munícipe vai ao banco. A entidade deve ser publicada em Administração › Parâmetros antes de emitir guias em produção.

Estados e transições

Estado	Significado
Emitida	por cobrar, dentro do prazo
Parcial	recebeu pagamento(s) mas ainda há dívida
Vencida	data-limite ultrapassada, com juros de mora recalculados
Paga	valor pago ≥ valor total; os lançamentos passam a pago
Anulada	anulada com motivo; os lançamentos voltam a pendente; dívida = 0

• Vencimento é avaliado automaticamente ao abrir a lista, as estatísticas, a ficha ou ao registar um pagamento: uma guia emitida/parcial/vencida com data-limite anterior a hoje passa a vencida e cada linha recebe juros = valor × 0,0004 × dias de atraso (arredondado a 2 casas); o total passa a capital + juros. Guias pagas ou anuladas nunca são tocadas;
• Uma guia paga ou parcial não pode ser anulada — anule primeiro os pagamentos;
• A anulação de um pagamento devolve a guia a emitida (se nada ficou pago) ou parcial.

Lista

Tesouraria › Cobrança & Guias. Cartões: Emitidas / Parciais, Pagas, Vencidas (após data-limite, com juros), Taxa de cobrança (pago ÷ emitido, sem anuladas; mostra também as anuladas) e Valor em aberto. Pesquisa por número, contribuinte, código ou referência (com ou sem espaços — a pesquisa compara só os dígitos); filtros Estado e Exercício. Colunas: Guia · Contribuinte · Referência · Total · Em dívida (a vermelho) · Limite · Estado.

Emitir uma guia (passo a passo)

Cobrança & Guias › Emitir guia (exige tesouraria.manage).

1. Contribuinte — seleccione na lista (a lista carrega até 100 contribuintes; pesquise a ficha em Contribuintes se precisar do código);
2. Data-limite de pagamento — tem de ser posterior a hoje;
3. Lançamentos pendentes — aparecem os pendentes do contribuinte; marque um ou mais. O rodapé mostra Selecionados e Total;
4. Emitir guia → abre a ficha da guia com número e referência atribuídos. O munícipe recebe a notificação "Guia emitida" no portal.

Erros possíveis (422): lançamento inexistente ou já não pendente ("já está faturado"), lançamentos de contribuintes ou exercícios diferentes, data-limite não futura. Ids repetidos são ignorados.

Ficha da guia

Cartões Valor total, Pago, Em dívida, Data-limite. Botões Imprimir guia (PDF) e Anular guia (só com tesouraria.anular, e se não estiver paga/anulada).

• Lançamentos — linhas incluídas (receita, descrição, exercício, juros, valor);
• Referência — entidade, referência, estado, emissão, data-limite, exercício; se anulada, data e motivo;
• Pagamentos — data, meio, valor, recibo e estado de conciliação de cada pagamento da guia.

Anular

Anular guia › Motivo da anulação (obrigatório). Os lançamentos voltam a pendente e podem ser incluídos noutra guia. O registo não é apagado; o PDF de uma guia anulada sai com a marca ANULADA.

PDF da guia

Imprimir guia (PDF) gera o documento original (cabeçalho do município, número, exercício, datas, linhas, caixa com entidade/referência/valor — legível a preto e branco) e arquiva-o no DMS; reimprimir devolve o mesmo código de documento. A 2.ª via descarregada pelo munícipe no portal sai marcada 2.ª VIA. Nome do ficheiro: guia-GU-2026-000123.pdf (-2a-via na segunda via).

Pagamentos

Meios e provedores

Meio	Provedor	Conciliação inicial
Numerário	—	conciliado de imediato
Mobile money	mpesa · emola · mkesh	por conciliar (referência da transacção obrigatória)
Banco	banco	por conciliar
POS	—	por conciliar

Em todos os meios registados ao balcão o pagamento é aplicado na guia e o recibo emitido na hora; o estado Por conciliar é só metadado para o cruzamento com o extracto.

Registar um pagamento (balcão)

Pagamentos › Registar pagamento (exige tesouraria.manage).

1. Referência de pagamento (ou número da guia) › Procurar guia. Só guias em aberto (emitida, parcial, vencida) são candidatas; uma paga ou anulada nunca aparece;
2. Se a referência coincidir exactamente, a guia é identificada; se houver várias candidatas sem correspondência exacta, o operador tem de escolher ("Selecionar esta guia") — nunca há pré-selecção;
3. Confirme a ficha resumida: guia, contribuinte, estado, total, em dívida, referência;
4. Preencha:

Campo	Obrigatório	Notas
Meio de pagamento	Sim	Numerário · Mobile money · Banco · POS
Valor	Sim	pré-preenchido com a dívida; parcial permitido; mínimo 0,01; não pode exceder a dívida
Provedor	Não	mobile money / banco
Referência externa	Se mobile money	ID da transacção; garante idempotência

5. Registar pagamento → a guia actualiza-se (parcial ou paga), o recibo é emitido e o munícipe é notificado ("Pagamento confirmado" se numerário, "Pagamento recebido" nos restantes).

Guardas do servidor:

• A referência enviada é cruzada com a da guia — se não bater, nada é gravado (422);
• A guia é bloqueada durante o registo: dois pagamentos simultâneos sobre a mesma guia não ultrapassam a dívida;
• A mesma referência externa (ou idempotency_key) repetida para a mesma guia e valor devolve o pagamento já existente; usada noutra guia/valor → 409;
• O pagamento fica ligado à caixa aberta do próprio operador (se existir). Uma caixa indicada explicitamente tem de estar aberta e pertencer ao município;
• Valores negativos ou não numéricos são recusados.

Lista de pagamentos

Cartões por meio (Numerário, Mobile money, Banco, POS) e Recebido no período · Divergências · Caixas abertas. Pesquisa por guia, contribuinte, referência ou recibo; filtros Meio, Conciliação (Por conciliar · Conciliado · Divergente) e período De / Até. Colunas: Guia (+ contribuinte) · Data · Meio (+ provedor) · Valor (rasurado se anulado) · Recibo · Conciliação (ou Anulado).

Pagamento por referência (portal, ATM, mobile money)

Quando o munícipe paga fora do sistema com a entidade e a referência da guia, a liquidação chega por uma de duas vias:

1. Callback do provedor (POST /tesouraria/pagamentos/callback, tesouraria.manage): recebe transaction_id, referencia_pagamento (aceite com ou sem espaços) e valor. Se houver uma intenção pendente do portal para essa guia, é ela que fica conciliada (com o transaction_id gravado); caso contrário cria um pagamento mobile money já conciliado. Em ambos os casos aplica na guia e emite recibo. Idempotente por transaction_id;
2. Conciliação manual (abaixo), depois de o operador confirmar o depósito no extracto.

Conciliação

Separador Pagamentos › Conciliação (importação exige tesouraria.conciliar).

• Conciliar um pagamento (POST …/pagamentos/{id}/conciliar): passa por conciliar → conciliado e regista o operador. Se o pagamento ainda não tinha recibo (intenção vinda do portal), é neste momento que se aplica na guia e se emite o recibo; um pagamento de balcão já aplicado não é creditado duas vezes;
• Importar extrato: escolha a origem (Banco · Mobile money · POS) e cole as linhas referencia_externa, valor, data (uma por linha; separadores , ; ou tabulação) › Importar e conciliar. Cada linha é casada por referência externa e meio:

Situação	Resultado
Referência encontrada e valor igual	pagamento conciliado (aplica na guia se ainda não tinha recibo)
Valor diferente	pagamento marcado divergente e listado
Sem pagamento correspondente	listado em Divergências ("Sem pagamento correspondente no sistema")
Linha mal formada, sem referência ou valor ≤ 0	listado como divergência

O resultado mostra N conciliados · N divergentes e a tabela de divergências (referência, valor do extracto, motivo). Linhas repetidas no mesmo ficheiro contam uma vez.

Anular (reverter) um pagamento

POST …/pagamentos/{id}/anular com motivo (exige tesouraria.anular). Efeitos, numa única transacção:

1. O valor sai do pago da guia; a guia volta a emitida ou parcial (uma guia já anulada não é reactivada);
2. Se a guia tinha ficado paga, os lançamentos voltam a faturado e os autos de contravenção ligados voltam a confirmado;
3. Todos os recibos do pagamento ficam anulados (nunca apagados);
4. A dívida volta à conta-corrente do contribuinte e a contabilidade recebe o contra-movimento na execução da receita.

Idempotente: anular duas vezes não reverte o saldo duas vezes. Na consola, esta acção não tem botão na lista de pagamentos (não verificado); está disponível pela API.

Caixa (sessão de tesouraria)

Separador Conciliação › Sessão de caixa.

• Abrir caixa — uma sessão por operador; cada guichê trabalha na sua ("Feche a sua caixa atual antes de abrir outra"). A caixa mostra Aberta em, estado e os totais do sistema por meio (pagamentos não anulados da sessão);
• Fechar caixa — introduza os valores contados por meio (Numerário, Mobile money, Banco, POS) › o sistema calcula Diferenças (contado − sistema), a verde quando zero e a vermelho quando não. Só o operador que abriu (ou quem tem tesouraria.anular) pode fechar; quem fecha fica na auditoria;
• Uma caixa fechada não aceita pagamentos — é um documento de prestação de contas.

Recibos

Cada pagamento aplicado gera um recibo RC-{exercício}-{000001} (sequência por município e exercício, sem lacunas) com número, data, guia, valor, meio e operador.

Tesouraria › Recibos: cartões Recibos emitidos, Anulados e Valor total (recibos válidos) — calculados sobre os 200 recibos mais recentes, não sobre a totalidade. Pesquisa por recibo, guia ou contribuinte; filtro Válidos / Anulados. Colunas: Recibo · Guia / Contribuinte · Meio · Data · Valor · Estado · botão 2.ª via.

2.ª via (PDF) reimprime sempre o mesmo documento; se o recibo foi entretanto anulado, sai com a marca ANULADO — nunca se esconde um documento emitido. Ficheiro recibo-RC-2026-000045.pdf, arquivado no DMS.

Sequências e séries de numeração

Série	Formato	Consumida em
Lançamentos	LC-AAAA-000001	criação de lançamento (Tributação e módulos de origem)
Guias	GU-AAAA-000001	emissão da guia
Recibos	RC-AAAA-000001	emissão do recibo

As três séries vivem numa tabela de sequências por município, tipo e exercício, incrementada sob bloqueio dentro da transacção: não há colisões nem lacunas, mesmo com dois guichês em simultâneo. Um pedido inválido (por exemplo, valor negativo) é recusado antes de consumir um número. A referência de pagamento reutiliza a sequência da guia (7 dígitos; máximo 9 999 999 guias por ano).

Comprovativos de pagamento

O munícipe (portal) ou o operador (API POST /tesouraria/comprovativos, tesouraria.manage) pode anexar o comprovativo de uma transferência a uma guia (ficheiro + valor declarado opcional; uma guia anulada não aceita). A análise corre em segundo plano:

1. Duplicado exacto (hash do ficheiro) → suspeito de duplicado;
2. Duplicado visual (hash perceptual, distância configurável) → suspeito de duplicado;
3. OCR (extractor configurável por município; desligado por defeito) extrai valor, data, referência, banco e nº de operação; nº de operação já usado → suspeito de duplicado;
4. Sem extracção → pendente de revisão; valor fora da tolerância (1 % por defeito) ou referência diferente da guia → divergente; tudo compatível → validado.

Um comprovativo validado nunca cria um pagamento — fica ligado à guia para o operador registar/conciliar no fluxo normal. A fila de revisão (GET …/comprovativos/revisao) lista os suspeitos, divergentes e pendentes; Decidir (aprovar/rejeitar, motivo 3–500 caracteres) fica auditado e notifica o munícipe. Não existe ecrã dedicado na consola para esta fila (não verificado); os endpoints estão disponíveis.

Conta-corrente do contribuinte

Cada aplicação de pagamento abate o saldo do contribuinte pelo valor aplicado; cada anulação repõe-no. O extracto (lançamentos, guias e pagamentos) consulta-se na ficha em Contribuintes › Conta-corrente.

Relatórios de cobrança e exportações

• Dashboard de Tesouraria e cartões das listas — leitura imediata de taxa de cobrança, valor em aberto/vencido e recebido por meio e período (filtros De/Até);
• Analítica (bi.view): Explorador de receita, Relatórios e Exportações — receita por tipo, por território e série mensal;
• Contabilidade › Mapas (contabilidade_municipal.view): Execução da receita, Balancete e Conta de gerência exportam-se em PDF e Excel com o layout oficial (identidade do município, título, totais, rodapé com código de documento). O PDF e o Excel saem da mesma consulta.

Limites de exportação

O PDF aceita no máximo 1 000 linhas e o Excel 5 000 linhas (limites medidos; um mapa largo pode ser travado antes disso pelo tamanho do documento). Acima do limite o sistema recusa com uma mensagem a pedir que estreite o período ou os filtros — não gera um ficheiro parcial. Os botões ficam bloqueados enquanto um formato está a gerar e há Cancelar para desistir.

As listas de guias, pagamentos e recibos não têm exportação própria na consola.

Como o portal do munícipe paga

Sequência ponta a ponta, com a mesma tabela de guias da Tesouraria:

1. Em Guias o munícipe vê as suas guias (o vencimento e os juros são recalculados só para as guias dele) e pode descarregar a 2.ª via em PDF;
2. Pagar › escolhe M-Pesa, e-Mola, mKesh ou Referência bancária › confirma (o ecrã mostra entidade, referência com botão Copiar e o montante em dívida);
3. O portal regista uma intenção de pagamento (estado por conciliar, valor = dívida total) e mostra "Pagamento registado — aguarda confirmação" com os dados para transferir. A guia não fica paga nem há recibo nesta altura; repetir o pedido devolve a mesma intenção (se a guia já estiver paga, mostra o pagamento confirmado e o recibo);
4. A transferência real acontece na app do operador, ATM ou internet banking;
5. A liquidação chega por callback do provedor ou conciliação manual na Tesouraria — só então a guia fica paga, o recibo é emitido e o munícipe recebe a notificação; o recibo aparece em Recibos do portal;
6. Em alternativa o munícipe pode carregar o comprovativo da transferência na guia, que entra na análise descrita acima.

Sem conta, Consultar dívida (público) mostra as guias por NUIT ou por referência, com juros calculados à data, sem gravar nada; a consulta é limitada por IP.

TIP

Ao balcão, se o munícipe diz que "já pagou no telemóvel" e a guia continua em aberto, procure o pagamento por conciliar na lista (filtro Conciliação) e concilie-o depois de confirmar o depósito — não registe um segundo pagamento.