IPTU Tubarão

IPTU Tubarão — integração para Home Assistant

Consulta os débitos de IPTU e demais tributos do município de Tubarão (SC) a partir de um CPF, e expõe nome do proprietário, situação, valores e a próxima data de vencimento como sensores do Home Assistant.

Os dados vêm do portal Meu IPTU da Prefeitura de Tubarão. Este projeto não tem vínculo com a prefeitura.

Requisitos

• Home Assistant 2024.4.0 ou superior
• CPF cadastrado no sistema de IPTU da Prefeitura de Tubarão

Instalação

Via HACS

1. No HACS, vá em Integrações → menu ⋮ → Repositórios personalizados.
2. Adicione https://github.com/dougbaptista/iptu_tubarao com o tipo Integração.
3. Procure por IPTU Tubarão, instale e reinicie o Home Assistant.
4. Em Configurações → Dispositivos e Serviços → Adicionar Integração, procure por "IPTU Tubarão" e informe o CPF.

Manual

1. Copie a pasta custom_components/iptu_tubarao para dentro de custom_components/ na sua instalação.
2. Reinicie o Home Assistant e adicione a integração pela interface.

Sensores

Cada CPF configurado vira um dispositivo com sete sensores:

O Status de Débitos aparece traduzido no painel, mas o valor guardado continua sendo com_debito / sem_debito — é com esses que automações e templates devem comparar:

{{ is_state('sensor.status_de_debitos', 'com_debito') }}

Todos os sensores trazem o atributo last_successful_update (ISO 8601) com o horário da última consulta bem-sucedida. O sensor de vencimento traz também due_dates, com todas as datas encontradas na página.

Como Próxima Data de Vencimento é um sensor de data de verdade (device_class: date), dá para usar em automações sem parsear string:

automation:
  - alias: Avisar 3 dias antes do vencimento do IPTU
    trigger:
      - platform: template
        value_template: >
          {{ (states('sensor.proxima_data_vencimento') | as_datetime | as_local).date()
             - now().date() == timedelta(days=3) }}
    action:
      - service: notify.persistent_notification
        data:
          message: >
            IPTU vence em 3 dias:
            R$ {{ states('sensor.valores_totais_sem_juros') }}

A consulta é feita a cada 12 horas.

Privacidade

O CPF é gravado na entrada de configuração (é preciso, para consultar), mas não circula pelo resto do Home Assistant: os identificadores das entidades derivam do entry_id, e o título da integração, o nome do dispositivo e o sensor de CPF exibem apenas a forma mascarada. Isso mantém o dado fora do registro de entidades, do histórico do recorder e dos backups.

Atualizações

Versão 2.0.1

• O CPF sai também do título da entrada. A 2.0.0 passou a mascará-lo, mas só nas entradas novas: quem já tinha a integração continuava vendo o número inteiro na tela de Integrações, e ele seguia indo para os logs e os backups. Agora o título é migrado na atualização. Se você renomeou a entrada, o nome é preservado — só o número é mascarado.

Versão 2.0.0

Reescrita da integração. Nenhuma ação é necessária ao atualizar: os identificadores das entidades são migrados automaticamente e o histórico é preservado.

• Falhas deixam de virar R$ 0,00. Antes, qualquer erro de leitura da página produzia zeros e "sem débito" — visualmente idêntico a estar tudo quitado, então uma mudança no site da prefeitura passaria despercebida indefinidamente. Agora a integração fica indisponível e registra o motivo.
• CPF fora dos identificadores. Os unique_id das entidades continham o CPF em claro; passam a derivar do entry_id, com migração automática.
• Erros distinguíveis na configuração. "CPF não cadastrado", "site fora do ar" e "layout mudou" eram todos reportados como CPF inválido. Os dígitos verificadores agora são conferidos localmente, sem depender da rede.
• Próxima data de vencimento virou uma data de verdade (device_class: date), em vez do texto dd/mm/aaaa. Parcela que vence hoje deixa de ser descartada.
• Valores monetários ganharam device_class: monetary e unidade BRL.
• O status aparece em português no painel ("Com débito" / "Sem débito"), em vez do identificador cru. O valor do estado não mudou: automações existentes seguem funcionando.
• Modalidade que não existe na dívida fica desconhecida, não R$ 0,00. Parcelamento de coleta de lixo, por exemplo, não tem cota única: o sensor Valor Taxa Única fica sem valor em vez de afirmar que dá para quitar tudo à vista de graça. Não havendo débito nenhum, os três valores continuam 0, que aí é a resposta correta.
• Vazamento de conexões corrigido: o cliente HTTP nunca era fechado. Trocado por aiohttp, com sessão dedicada e fechada no unload.
• A análise do HTML saiu do event loop, que ela bloqueava a cada consulta.
• Suíte de testes sobre HTML real do site (tests/).

Versão 1.4.1

• Sensor proxima_data_vencimento, com a data mais próxima entre as futuras.
• Atualização automática uma vez por dia.

Versão 1.4.0

• Correções na captura de valores financeiros.
• Melhorias na formatação do CPF.

Versão 1.3.0

• Sensor de valor total sem desconto.
• Melhorias na captura do nome do proprietário.

Diagnóstico

Para registrar em detalhe o que a integração faz:

logger:
  default: warning
  logs:
    custom_components.iptu_tubarao: debug

Se os sensores ficarem indisponíveis com uma mensagem sobre mudança de layout, o site da prefeitura provavelmente mudou; abra uma issue.

Desenvolvimento

A suíte tem dois níveis. O primeiro cobre a leitura da página e roda em qualquer lugar, sem Home Assistant instalado:

pip install -r requirements-test.txt
pytest

O segundo sobe uma instância do Home Assistant de verdade e exercita o fluxo de configuração, o setup e o unload da entrada, a migração de identificadores e o estado das entidades, sempre com o HTTP mockado sobre as mesmas capturas do site. Esses testes são pulados automaticamente quando o Home Assistant não está disponível. Para rodá-los (Python 3.12 — veja o porquê em requirements-dev.txt):

uv venv --python 3.12 .venv
uv pip install --python .venv/Scripts/python.exe -r requirements-dev.txt
.venv/Scripts/python.exe -m pytest

As respostas do site usadas nos testes ficam em tests/fixtures/ — veja o README de lá antes de acrescentar capturas novas.