Um sistema de IA pode processar e arquivar uma declaração de imposto de autoavaliação ao HMRC automaticamente?

Este é o mergulho profundo de formato longo. Para um acompanhamento mais rápido, consulte o postagem no blog. Não é aconselhamento fiscal. Sempre peça uma revisão de um contador do Reino Unido antes de enviar um HMRC ao vivo.

1. Introdução: a IA pode arquivar a autoavaliação automaticamente?

A resposta honesta é principalmente sim para preparação, não para submissão autônoma. Um sistema de IA pode ingerir um extrato bancário em PDF, extrair centenas de transações, classificá-las em categorias de despesas de autoavaliação do HMRC, reconciliar saldos, calcular imposto de renda e seguro nacional para um ano fiscal como 2025-26 e chamar a API HMRC Making Tax Digital (MTD) para arquivar - mas somente depois que um humano (ou contador) revisou as classificações, a reconciliação e o retorno calculado, e somente depois que o contribuinte tiver concluído o HMRC OAuth com seu gateway governamental credenciais.

Este artigo documenta ArquivoMeuTax, um pipeline de demonstração desenvolvido por Estação de trabalho para CognoAI, que possui a propriedade intelectual do sistema subjacente e concedeu permissão para publicar como ele funciona. FileMyTax é o nome da publicação usado aqui; não é o mesmo nome de produto de outras ofertas da CognoAI. Estação de trabalho construída e documentada a implementação; CognoAI possui o IP.

Examinaremos o pipeline de seis APIs, a arquitetura, onde a IA ajuda na análise financeira, onde o código determinístico deve assumir o controle, o arquivamento HMRC OAuth e MTD, as limitações aprendidas nos testes de extratos bancários dos proprietários e por que o arquivamento totalmente autônomo não é recomendado.

2. Quem construiu isso e por quê

CognoAI encomendou a plataforma subjacente para reduzir a dor da autoavaliação do Reino Unido para proprietários, comerciantes individuais e equipes financeiras que se afogam em extratos bancários em PDF e cola de planilhas. O objetivo não é substituir os contadores – é automatizar os tediosos 90% (extração, categorização, reconciliação, cálculo preliminar) para que a revisão profissional se concentre em decisões de julgamento e não na entrada de dados.

Estação de trabalho projetou a pilha: roteamento nginx Dockerizado, front-end Next.js, FastAPI para operações pesadas de IA, opsapi (Lua Lapis) para autenticação e CRUD fiscal, PostgreSQL, armazenamento de objetos MinIO e monitoramento de integridade Gatus. Este artigo explica essa arquitetura sob o nome de demonstração FileMyTax com atribuição CognoAI por toda parte.

3. O problema: PDFs, planilhas e MTD

Proprietários e comerciantes individuais geralmente recebem pacotes anuais de PDFs bancários – contas múltiplas, linhas pessoais e comerciais mistas, juros de hipotecas, reparos, taxas de agentes e transferências que são difíceis de classificar em escala. No desenvolvimento, testamos o pipeline em relação a luminárias fictícias de declarações de proprietários no estilo HSBC (apenas dados sintéticos, não registros reais de clientes) com cenários de rotatividade em torno de £500 mil e £700 mil para validar a extração sob carga. Os pacotes do mundo real são confusos: páginas digitalizadas, layouts de tabelas onde a coluna de saldo é confundida com valores pagos e descrições como “RENT REC” ao lado de “TRANSFER” que precisam de contexto.

As planilhas funcionam até que não funcionem: desvio de fórmula, nenhuma trilha de auditoria, nenhum envio direto de MTD e nenhum mapeamento consistente para categorias de despesas do HMRC (costOfGoods, facilitiesRunningCosts, professionalFees e o resto). O SaaS empacotado pode ajudar, mas as equipes com necessidades personalizadas de residência de dados ou formatos de declaração estranhos ainda se beneficiam de um pipeline que controlam.

4. Visão geral do FileMyTax

Em inglês simples, FileMyTax faz o seguinte:

1. Você carrega um extrato bancário em PDF.
2. AI e pdfplumber extraem transações estruturadas.
3. Um LLM classifica cada linha em categorias de autoavaliação com pontuações de confiança.
4. O sistema reconcilia débitos, créditos e saldos correntes.
5. Um mecanismo fiscal determinístico calcula o retorno para um ano fiscal escolhido.
6. Após aprovação humana e HMRC OAuth, a plataforma pode arquivar via MTD.

Tudo funciona atrás de um único ponto de entrada nginx no host local (ou IP da LAN para testes móveis). A autenticação JWT é compartilhada entre FastAPI e opsapi. Campos confidenciais, como números de Seguro Nacional, são criptografados em repouso.

5. O pipeline de API de seis etapas

O pipeline de demonstração completo consiste em seis chamadas de API autenticadas (exemplos usam nginx em http://localhost; ajuste a porta se NGINX_HOST_PORT está definido). Obtenha um JWT por meio de POST /opsapi/auth/login primeiro.

Cada etapa é atualizada ProcessingStatus e ValidationStatus linhas para que a interface do usuário e as ferramentas de operações adjacentes ao Gatus possam ver se uma instrução está presa na extração ou pronta para cálculo. Essa máquina de estado é fácil de ignorar ao ler exemplos de curl isoladamente, mas é o que torna os uploads paralelos seguros: os IDs das instruções são independentes e calculam sempre chaves de um único statement_id mais explícito tax_year parâmetro de consulta (por exemplo 2025-26).

Swagger para FastAPI reside em http://localhost/fastapi/docs; opsapi expõe http://localhost/opsapi/swagger. Quando a porta 80 do nginx for usada (comum com Rancher Desktop ou Apache), defina NGINX_HOST_PORT=8080 em .env e repita ./start.sh - todos os exemplos então usam localhost:8080 em vez disso.

5.1 Carregar extrato em PDF

curl -F "file=@bank_statement.pdf" \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost/fastapi/api/upload

5.2 Extrair transações

curl -X POST http://localhost/fastapi/api/extract \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statement_id": 1}'

PDFs nativos usam pdfplumber; PDFs digitalizados recorrem ao OCR Claude Vision. O provedor do classificador é selecionado por LLM_PROVIDER (OpenAI ou Anthropic) na inicialização — não há fallback automático entre provedores em caso de falha; classificações com falha retornam sem categoria com confidence: 0.0.

5.3 Classificar transações

curl -X POST http://localhost/fastapi/api/classify \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statement_id": 1}'

5.4 Declaração de reconciliação

curl -X POST http://localhost/fastapi/api/reconcile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statement_id": 1}'

5.5 Calcular declaração de imposto

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost/fastapi/api/calculate/1?tax_year=2025-26

A calculadora de impostos aplica as regras de 2025/26: subsídio pessoal £ 12.570 com redução gradual acima de £ 100k, faixas de imposto de renda de 20%, 40%, 45% e NI Classe 4 de 8% e 2%. Esta etapa é Python determinístico - nenhum LLM em aritmética.

5.6 Arquivo para HMRC

curl -X POST http://localhost/fastapi/api/file \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "statement_id": 1,
    "nino": "AB123456C",
    "access_token": "your_hmrc_token",
    "tax_year": "2025-26"
  }'

Não chame esse endpoint de autônomo. Trate-o como a porta final após a revisão e aprovação do contador.

6. Arquitetura

O tráfego flui através do nginx: / para Next.js, /fastapi/* para FastAPI, /opsapi/* para opsapi. PostgreSQL contém extratos, transações, declarações fiscais e status de processamento. MinIO armazena PDFs carregados. Gatus na porta 8085 pesquisa endpoints de integridade a cada 10-30 segundos. Existem portas de depuração direta (FastAPI 8847, frontend 3847), mas os testes de estilo de produção usam apenas caminhos nginx.

7. Diagrama de fluxo de trabalho

As raias separam preocupações: revisão do cliente, ingestão, extração e classificação de IA, mecanismo de imposto determinístico, HMRC OAuth e arquivamento e auditoria (JWT, NINO criptografado, logs). A matriz de decisão compara o fluxo assistido por IA do FileMyTax com planilhas manuais e preparação apenas do contador em termos de prazo, precisão, trilha de auditoria, custo, conformidade com HMRC e supervisão humana.

8. IA para análise financeira – benefícios

8b. Pilha e serviços (detalhe técnico)

Atrás do FileMyTax está uma pilha Docker Compose orquestrada por ./start.sh, que pode ser executado nos modos local, LAN, teste, preparação ou produção. O backend usa FastAPI com SQLModel no PostgreSQL; PDFs carregados chegam ao MinIO sem armazenamento em disco local nos contêineres da API. O front-end é Next.js com NEXT_PUBLIC_* variáveis preparadas em tempo de construção a partir da raiz .env.

A autenticação é dividida deliberadamente. opsapi (Lua Lapis) emite tokens de acesso JWT e tokens de atualização opacos (cookies seguros somente Http para web, corpo JSON para dispositivos móveis). FastAPI verifica o mesmo JWT_SECRET_KEY. Os serviços incluem StorageService, PDFProcessorService, LLMService, ClassificationService, ReconciliationService, TaxCalculatorService e HMRCClient – ​​cada um com um limite estreito para que as falhas de IA não corrompam a aritmética fiscal.

Os analisadores bancários suportados têm como alvo layouts comuns do Reino Unido (HSBC, Barclays, Lloyds, Santander e PDFs de tabelas semelhantes). O analisador detecta colunas de data, descrição, débito/crédito ou valor e saldo de forma flexível — o que é poderoso até que a coluna errada seja escolhida; veja as limitações abaixo.

9. HMRC Tornando os Impostos Digitais

A autoavaliação MTD requer OAuth autorizado pelo usuário – apenas um NINO não é suficiente. O fluxo típico:

1. Salve Nino — POST /opsapi/api/v2/tax/profile/nino (criptografado em repouso, mascarado nas respostas).
2. Conecte o HMRC — GET /opsapi/auth/hmrc/initiate retorna auth_url; o usuário faz login via Gateway do Governo; callback troca código por tokens armazenados no lado do servidor.
3. Buscar empresas — POST /fastapi/api/hmrc/businesses/fetch armazena em cache nomes comerciais e IDs.
4. Buscar obrigações — POST /fastapi/api/hmrc/obligations/fetch para períodos trimestrais e datas de vencimento.
5. Arquivo — POST /fastapi/api/file após revisão.

Definir HMRC_ENVIRONMENT=sandbox para o desenvolvimento; mudar para production sem alterações de código quando estiver pronto. O backend envia cabeçalhos obrigatórios de prevenção de fraude; os clientes devem fornecer estável X-Device-ID e preciso User-Agent valores. Usuários de teste sandbox podem ser criados via POST /fastapi/api/hmrc/sandbox/create-test-user quando o modo sandbox está ativado.

Os tokens de acesso HMRC expiram após aproximadamente quatro horas; o back-end gerencia a atualização – os clientes móveis e da web usam tokens armazenados no opsapi em vez de incorporar segredos no navegador além do redirecionamento OAuth.

9.1 Salve NINO e verifique o perfil

curl -X POST http://localhost/opsapi/api/v2/tax/profile/nino \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "nino": "QQ123456C" }'

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost/opsapi/api/v2/tax/profile

As respostas mascaram o NINO (****456C) enquanto confirma hmrc_connected e expiração do token após OAuth.

9.2 Início do OAuth

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost/opsapi/auth/hmrc/initiate?source=settings"

Abrir auth_url em um navegador do sistema ou ASWebAuthenticationSession - não em um WebView cheio de credenciais. Os aplicativos móveis devem registrar um link direto ou link universal como HMRC_REDIRECT_URI.

9.3 Negócios e obrigações

curl -X POST http://localhost/fastapi/api/hmrc/businesses/fetch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST http://localhost/fastapi/api/hmrc/obligations/fetch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "business_id": "XAIS12345678910" }'

As leituras armazenadas em cache posteriormente evitam atingir o HMRC em cada carregamento de página: GET /fastapi/api/hmrc/businesses e GET /fastapi/api/hmrc/obligations?tax_year=2024-25.

9.4 Desconexão e status

curl -X DELETE http://localhost/opsapi/auth/hmrc/disconnect \
  -H "Authorization: Bearer $TOKEN"

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost/fastapi/api/hmrc/status

8c. IA para análise financeira — visão mais aprofundada

Além da tabela de resumo, três padrões são importantes para as equipes de FinOps que avaliam construir versus comprar.

Primeiro, rendimento. Um empresário individual com doze meses de transações em duas contas de aluguel pode passar um dia em tabelas dinâmicas do Excel; o pipeline FileMyTax conclui extração + classificação + reconciliação no tempo que leva para fazer o café, deixando a hora humana para julgamento. Essa mudança move a economia contábil da entrada de dados para a consultoria – o valor faturável que os contadores preferem de qualquer maneira.

Em segundo lugar, explicabilidade. Cada classificação carrega uma pontuação de confiança e pode ser substituída por um motivo armazenado junto com a transação. Isso é mais fraco do que um registro de auditoria de cadeia completa de pensamentos, mas mais forte do que uma exportação SaaS de caixa preta, onde você não consegue ver por que a linha 417 era "reparos".

Terceiro, curva de custos. Executando localmente, o custo marginal por retorno são tokens de API para classificação mais eletricidade – e não taxas de SaaS por assento escalonadas com a contagem de entidades. Para proprietários de portfólio ou equipes de operações financeiras com muitas declarações, essa curva é importante. O custo inicial de engenharia é real; A CognoAI absorveu isso por meio da entrega da estação de trabalho, em vez de enviar planilhas para cada usuário todos os anos.

As organizações sensíveis à privacidade também se preocupam com que as linhas de PDFs e Postgres permaneçam dentro de sua rede Docker até o arquivamento do HMRC – não há etapa de ingestão de nuvem multilocatário na arquitetura de demonstração. O fortalecimento da produção ainda requer backups, controle de acesso e documentação DPIA; o artigo não pretende que a conformidade com o GDPR seja automática porque a pilha é local.

10. Vídeo de demonstração

Demonstração completa do FileMyTax: PDF do banco por meio de classificação e cálculo para arquivamento em sandbox HMRC MTD, com portas de revisão mostradas na IU.

11. Humano no circuito

A IA pode interpretar mal uma coluna digitalizada, confundir uma transferência com receita ou atribuir a categoria de despesa errada quando a descrição for vaga. A IU foi projetada para revisão: aceitar, substituir ou dividir transações com os motivos capturados. O cálculo do imposto é determinístico e testável; o LLM nunca calcula o imposto devido.

Aprovação do contador antes que qualquer envio ao vivo do HMRC seja obrigatório. Este artigo é não aconselhamento fiscal. FileMyTax demonstra capacidade de engenharia para CognoAI; suas circunstâncias podem diferir em subsídios, divisões de renda de propriedade, parcerias e outras programações de SA.

11b. Monitoramento com Gatus

O painel Gatus incluído (http://localhost:8085 por padrão) pesquisa o frontend via nginx, FastAPI /fastapi/health, opsapi /opsapi/health?detailed=true, acessibilidade Swagger e portas diretas de contêiner para diagnósticos de desvio. O intervalo é de 10 a 30 segundos por verificação. Adicionar um serviço significa editar monitoring/gatus/config.yaml e reiniciar o contêiner Gatus – um hábito operacional pequeno, mas importante, antes de você confiar no pipeline para obter dados financeiros reais.

As verificações de integridade não substituem os testes ponta a ponta: o repositório também oferece suporte ao Playwright E2E em uma pilha em execução e pytest no back-end. Um tabuleiro Gatus verde mais uma reconciliação falhada ainda é um dia falhado.

12. Limitações

• Extração de PDF: pdfplumber assume layouts de tabela; As declarações no estilo HSBC nos ensinaram a validar explicitamente as colunas de saldo versus pagas - o mapeamento incorreto de colunas corrompe silenciosamente a reconciliação.
• OCR: As declarações digitalizadas dependem de Claude Vision; varreduras ruins precisam de correção humana.
• Guarda-corpos LLM: As classificações de baixa confiança não devem ser arquivadas automaticamente; padrão não categorizado por falha do provedor, em vez de adivinhação.
• Separação determinística: As faixas fiscais e as taxas de NI residem em tax_calculator.py com precisão DECIMAL - nunca projetada imediatamente.
• Escopo de conformidade: Aplicam-se as regras do GDPR, da Lei de Proteção de Dados de 2018 e do HMRC; a produção precisa de backups, gerenciamento de segredos e monitoramento além da composição do Docker de desenvolvimento.
• Alinhamento JWT: FastAPI e opsapi devem compartilhar JWT_SECRET_KEY; a incompatibilidade aparece como erros de assinatura 401 opacos – verifique ambos os contêineres se a autenticação for interrompida repentinamente após a reimplantação.
• Aprisionamento do provedor na inicialização: LLM_PROVIDER é openai ou antrópico sem failover cruzado; planeje janelas de manutenção se um provedor sofrer uma interrupção.

Ao testar cenários de proprietários, trate os deltas de reconciliação como sinais de primeira classe, não como incômodos. Uma incompatibilidade de £ 12 mil geralmente significa mapeamento incorreto de coluna, não um inquilino desobediente. Corrigir regras de extração e executar novamente o pipeline idempotente é mais barato do que substituir centenas de linhas manualmente.

12b. Como isso se compara ao pacote de software fiscal

FreeAgent, Xero Tax e ferramentas semelhantes são o padrão certo para a maioria dos usuários: conectores MTD certificados, balcões de suporte e contadores já treinados. As plataformas estilo FileMyTax fazem sentido quando você precisa de regras de categorização personalizadas, implantação local ou VPC, integração com um plano de identidade opsapi existente ou publicação de um fluxo de trabalho vertical (como CognoAI faz para contabilidade assistida por IA). A matriz de decisão no fluxo de trabalho SVG é intencionalmente honesta: as planilhas são lentas e propensas a erros; somente contador é seguro, mas caro na preparação recorrente; Os pipelines locais assistidos por IA só ganham em auditabilidade e custo marginal se você investir em engenharia e ainda pagar pela aprovação profissional.

13. O que vem a seguir para FileMyTax / CognoAI

Os itens do roteiro visíveis nos documentos da plataforma incluem viagens de ida e volta de cálculo de visualização MTD ITSA mais profundas, dados de treinamento expandidos no estilo RAG de correções contábeis, domínios de cookies de autenticação multilocatários para implantações de SaaS e fluxos OAuth móveis mais rígidos. A estação de trabalho continua a engenharia em nome da CognoAI; a direção do produto e o IP permanecem com a CognoAI.

Os leitores de engenharia devem assistir a três documentos de integração no repositório upstream: Integração HMRC MTD (fases AD para cálculo de visualização), Autenticação compartilhada (JWT + rotação de atualização) e Pipeline de dados de treinamento de IA (incorporações de pgvector mais exportações de redução de MinIO de correções contábeis). Juntos, eles mostram como o pipeline de demonstração atual se torna um sistema de aprendizagem: as classificações melhoram quando os profissionais corrigem erros, sem precisar treinar novamente o calculador de impostos.

Para os operadores, a implantação da produção significa ENVIRONMENT=production, terminação HTTPS na frente do nginx, backups de banco de dados, segredos externos .env arquivos e alertando além das luzes verdes de Gatus. Nada disso diminui a história central: a IA elimina o atrito das planilhas; o código determinístico contém a legislação tributária; os humanos mantêm a responsabilidade.

13b. Perguntas frequentes

O FileMyTax substitui meu contador? Não. Reduz o trabalho de preparação; os contadores ainda validam tratamento, isenções e outras fontes de renda que não estão no PDF do banco.

Posso executar isso em um telefone? O modo LAN reescreve CORS e URLs de API em seu IP Wi-Fi para que você possa testar a IU Next.js em um telefone na mesma rede - útil para demonstrações, não um substituto para engenharia de lançamento móvel reforçada.

E se o LLM estiver inativo? A classificação retorna linhas não categorizadas com confiança zero; o pipeline não muda de provedor silenciosamente. Você corrige a configuração do provedor ou espera – outro motivo pelo qual existe a revisão humana.

O DIY TAX RETURN é mencionado aqui? Não. Esse nome refere-se à marca separada do produto CognoAI. Este artigo usa apenas FileMyTax, de acordo com as regras de publicação.

13c. Instantâneo do cálculo de 2025-26

Para os leitores que verificam o mecanismo determinístico em relação às orientações do HMRC, os parâmetros 2025/26 incluídos na calculadora incluem: subsídio pessoal de £ 12.570, reduzido em £ 1 para cada £ 2 de renda acima de £ 100.000; taxa básica de 20% entre £ 12.571 e £ 50.270; taxa mais alta de 40% até £ 125.140; taxa adicional 45% acima; Classe 4 NI a 8% sobre lucros entre £ 12.571 e £ 50.270 e 2% acima. As categorias de despesas se alinham às caixas de trabalho autônomo do HMRC – costOfGoods, facilitiesRunningCosts, travelCosts, professionalFees e o restante listado no README da plataforma. O mecanismo consome totais classificados; não reinterpreta descrições em linguagem natural. Essa fronteira é o que torna o arquivamento automatizado defensável: o LLM propõe rótulos; a calculadora aplica o estatuto.

14. Conclusão

Um sistema de IA pode processar e registrar um retorno de autoavaliação do Reino Unido ao HMRC automaticamente? Ele pode automatizar quase toda a preparação e expor uma API de arquivo com um clique, mas o uso responsável exige revisão humana, aprovação do contador, teste de sandbox e OAuth do contribuinte. FileMyTax mostra como isso é na prática: seis APIs, arquitetura clara, IA onde o reconhecimento de padrões vence e código determinístico onde a lei exige precisão.

Assista o demonstração no YouTube, visite CognoAI para o contexto do produto, e entre em contato com a estação de trabalho se você precisar dessa classe de engenharia FinOps em sua pilha.

Instantâneo de SEO para este artigo

• Título SEO: A IA pode arquivar a autoavaliação para o HMRC? | ArquivoMeuTax
• Meta descrição: Demonstração FileMyTax: AI extrai PDFs bancários, classifica transações SA, calcula impostos de 2025-26, arquivos via HMRC MTD – com revisão humana. Construído por Workstation para CognoAI.
• Palavras-chave primárias: Autoavaliação de IA, FileMyTax, HMRC MTD, declaração automática de impostos, extrato bancário AI, CognoAI, estação de trabalho
• Twitter / X (menos de 280 caracteres): A AI pode enviar a autoavaliação do Reino Unido ao HMRC? Demonstração FileMyTax: PDF do banco → classificar → calcular → MTD, com portão humano + sandbox primeiro. Construído pela Workstation para @CognoAI. Vídeo + redação de 4 mil palavras. Não é aconselhamento fiscal. #HMRC #MTD #AI #FileMyTax
• Postagem no LinkedIn: Publicamos como FileMyTax - desenvolvido pela Workstation for CognoAI - obtém um PDF de banco de proprietário ou comerciante individual por meio de extração de IA, classificação de categoria HMRC, cálculo determinístico de imposto 2025-26 e arquivamento MTD, com armazenamento NINO criptografado, OAuth e um portão de aprovação humana rígido antes do envio. O longo artigo cobre o pipeline de seis APIs, SVGs de arquitetura, cabeçalhos de prevenção de fraude e limites honestos (armadilhas de coluna pdfplumber, proteções de confiança LLM). Assista ao novo vídeo de demonstração; peça a um contador para assinar antes de qualquer arquivo ativo. Não é aconselhamento fiscal.

Isenção de responsabilidade: dados bancários fictícios quando referenciados; FileMyTax é um nome de demonstração; não aconselhamento fiscal; revisão do contador necessária antes do envio ao HMRC ao vivo.