API de Nota Fiscal modular: NFC-e, NF-e, MDF-e e NFS-e
Um motor fiscal para vários negócios
A API de Nota Fiscal da VisionX é o motor fiscal do SoftPay V2, descrito no repositório como uma API fiscal universal. A proposta é atender negócios muito diferentes, como varejo, distribuidora, serviços e comércio eletrônico, com um único núcleo técnico. O produto está em desenvolvimento, o repositório é privado e não há lançamento público, preço ou data confirmados. A descrição do pacote usa a mesma expressão, API fiscal universal, e cita documentos como NF-e, NFC-e, MDF-e e NFS-e.
O motor foi desenhado como multi-tenant: cada empresa é um emitente, com certificado, numeração e chaves de API próprios. Sistemas externos, como um CRM, não embutem o motor; eles chamam a API por REST. Certificado, assinatura, numeração e comunicação com os órgãos fiscais ficam todos centralizados no motor, o que reduz o risco de segredos espalhados. Isso também facilita a manutenção, porque uma correção feita no motor vale para todos os sistemas conectados a ele.
Módulos ativáveis por cliente
Cada documento ou imposto é um módulo isolado, ativado por cliente por meio de feature flags, que são chaves de ativação. O questionário de entrada do SoftPay V2 identifica o nicho do cliente e liga apenas os módulos relevantes, de modo que ele não vê funções que não usa. Um registro de módulos organiza o conjunto no código. Essa divisão torna o sistema mais fácil de manter e de testar.
Os módulos previstos são NFC-e modelo 65, NF-e modelo 55, MDF-e modelo 58 e NFS-e, além de Substituição Tributária do ICMS, IPI, FECOEP e romaneio de entrega com frota. Uma distribuidora, por exemplo, depende da substituição tributária, enquanto um varejo de balcão depende da NFC-e. Essa lógica evita sobrecarregar a interface de quem só precisa de um tipo de nota. Cada módulo é independente e pode evoluir sem alterar os demais.
Integração por API REST
Um guia do repositório descreve como sistemas externos integram a emissão de NFS-e. O setup é feito uma vez por empresa: cadastra-se o emitente com CNPJ, razão social, regime, endereço e inscrição municipal, envia-se o certificado A1 e gera-se uma chave de API para o sistema chamador. A chave deve ficar apenas no backend de quem chama, nunca no front.
A emissão usa o Padrão Nacional da NFS-e, em comunicação segura com o gov.br/nfse. O chamador informa tomador, serviço e valores, junto de uma chave de idempotência, que impede nota duplicada se a requisição for repetida por falha de rede ou clique duplo. A resposta traz a chave de acesso e a nota, ou o motivo da recusa para que se corrija e reenvie.
Consulta, cancelamento e arquivos
Depois da emissão, o motor oferece consulta da nota pela chave. Se uma falha de rede deixou a nota como rejeitada localmente, mas ela foi autorizada no órgão fiscal, a consulta corrige o status, comportamento descrito no guia como autocorreção. Também há cancelamento por evento, com motivo de 15 a 255 caracteres e códigos para erro de emissão, serviço não prestado e outros.
Cada tentativa de cancelamento fica registrada, com numeração sequencial automática, e repetir o pedido numa nota já cancelada é seguro. Para obter os documentos, existem rotas que entregam o PDF da nota e o XML autorizado. Um SDK em TypeScript, sem dependências e baseado em fetch nativo, pode ser copiado para o backend do chamador e expõe operações de emitir, consultar e cancelar.
Pacotes para os produtos da VisionX
Um plano do repositório propõe empacotar o motor em dois pacotes instaláveis. O fiscal-core reúne cálculo de imposto, tabelas e validação, funciona offline e não carrega segredos. O fiscal-sdk é o cliente tipado que se comunica com o motor central para o que depende de estado ou segredo, como emitir, assinar, numerar e consultar a SEFAZ. Essa divisão torna o sistema mais fácil de manter e de testar.
O objetivo declarado é permitir que produtos próprios da VisionX, como SoftPay, FroX e Cortex, usem o mesmo motor sem duplicá-lo e sem que cada um vire dono de certificado, numeração ou comunicação fiscal. Certificado A1, assinatura, numeração sequencial e atualização da legislação nunca são embutidos offline. Segundo o plano, a numeração é um ponto sensível, pois pode colidir entre processos. Isso mostra a preocupação do projeto em separar o que pode rodar localmente do que precisa de proteção central.
Piloto em homologação
O repositório traz um roteiro de implantação do piloto em ambiente de homologação, no qual as notas não têm valor fiscal e servem para provar o fluxo sem risco. O roteiro pede configuração de ambiente, instalação, uma verificação chamada doctor que confere chave mestra, banco, certificado e resposta da SEFAZ, cadastro de um emitente de teste e um teste de fumaça que emite uma NF-e e, havendo CSC, uma NFC-e.
O sucesso do teste é uma nota autorizada com código de status 100 e protocolo. O documento prevê ainda subir o motor numa VPS Ubuntu com PM2 e nginx. Enquanto o teste não autorizar, a orientação é não liberar o motor para ninguém de fora. A produção exige que cada empresa esteja credenciada na SEFAZ, etapa que depende das próprias empresas.
O que ainda não está pronto
O próprio roteiro lista o que não está pronto. O aplicativo V1 do SoftPay ainda não fala com o motor, e sua tela de notas é uma maquete. Não há contingência de NFC-e em modo offline caso a SEFAZ do Maranhão fique fora do ar. Quanto à escala, o piloto usa SQLite e uma única instância, solução considerada adequada para teste, mas não para grande volume.
O código inclui scripts de apoio, como testes de fumaça para MDF-e e NFS-e nacional, monitoramento do TLS da SEFAZ e backup, além de uma suíte de testes automatizados com arquivos para chave de acesso, cálculo de tributos, manifestação do destinatário e fila de reenvio. Por estar em desenvolvimento, nada aqui deve ser lido como promessa de funcionalidade disponível ao público.
Veja também: PDF sem Cadastro, BrasilVisto, Urnômetro. Página inicial da VisionX.