[vitormattos]

Objetivo

Avançar a paridade efetiva entre a API fiscal do Akaunting e o MCP. Esta entrega torna cinco operações nativas descobríveis e utilizáveis via ferramentas genéricas, respeitando a autenticação do usuário e a aprovação independente quando há efeitos financeiros.

Rotas implementadas

Consultas de POST comprovadamente sem persistência:

• api.nfse.settings.vault.diagnostics: diagnóstico do Vault/OpenBao, sem retorno de segredos, com validação estrita dos estados/motivos e booleanos.
• api.nfse.bulk.plan: prévia de até 100 IDs de faturas distintos, sem enfileirar ou emitir notas, com resposta JSON tipada e isolamento por empresa.

Mutações sob aprovação pessoal no navegador:

• api.nfse.dps.advance: avanço monotônico excepcional da sequência DPS com próximo número esperado, número novo, motivo e confirmação explícitos; estado de autoridade revalidado antes da execução.
• api.nfse.invoices.refresh: reconciliação de recibo fiscal atual, mediante identificação exata da fatura/recibo e verificação de empresa, sem criar NFS-e nova.
• api.nfse.bulk.dispatch: despacho para fila nativa exclusivamente em produção restrita, com MCP_NFSE_FISCAL_WRITES_ENABLED=true, 1–100 faturas verificadas, ambiente/DPS prontos e confirmação independente. Os workers fazem o preflight fiscal real; uma resposta incerta não deve ser repetida sem conciliação.

A camada Api::postReadOnly restringe os POSTs de leitura aos dois endpoints acima; não cria proxy HTTP genérico, não habilita emissão fiscal por GET e não executa mutações diretamente por ferramenta MCP.

Validação executada

• PHPUnit PHP 8.5: 189 testes, 863 asserções, com testes sintéticos de transporte real e autorização/negação.
• PHPStan: sem erros; PHP-CS-Fixer: sem alterações; release-scope checker: aprovado; git diff --check: aprovado.
• Auditoria da API efetivamente instalada: 198 combinações de verbo e rota; 164 cobertas; 34 operações pendentes; nenhuma divergência (antes: 159 cobertas e 39 pendentes).
• Auditoria do módulo akaunting-nfse atual: 47 rotas, 35 cobertas, 12 pendentes, nenhuma divergência.
• Três commits incrementais, com assinatura criptográfica verificada e DCO.

Limites

Não houve alteração real de dados financeiros, transmissão de NFS-e, mudança de DPS nem teste com certificados de cliente. Os testes são sintéticos e isolados, sem credenciais de produção. As 34 operações restantes continuam indisponíveis, inclusive fluxo seguro de criação de perfil/PFX, downloads e outras ações fiscais/Core. O objetivo final de configuração integral ainda não está concluído.

O novo parâmetro post_body na ferramenta genérica akaunting_api_read exige atualização do catálogo do aplicativo ChatGPT após merge e deploy. Nesta conversa, o esquema ainda foi observado desatualizado também para module_filters, apesar da atualização solicitada; não declarar esse detalhe corrigido sem testar o cliente.

Sem merge nem deploy antes da revisão exigida pelo repositório.