API de Nota Fiscal: API fiscal modular: NFC-e, NF-e, MDF-e, NFS-e e impostos

A API de Nota Fiscal da VisionX é uma API fiscal universal, organizada em módulos como NFC-e, NF-e, MDF-e e NFS-e. O produto está em desenvolvimento e ainda não foi lançado. API fiscal em módulos que se ativam por cliente: NFC-e, NF-e, MDF-e, NFS-e, substituição tributária, IPI e romaneio de entrega.

Falar com a VisionX
Recursos

O que o API de Nota Fiscal faz

  • NFC-e (modelo 65)

    Cupom fiscal para o varejo de balcão.

  • NF-e (modelo 55)

    Nota fiscal para vendas entre empresas.

  • MDF-e (modelo 58)

    Manifesto de documentos fiscais para transporte.

  • NFS-e

    Nota fiscal de serviço municipal.

  • Substituição Tributária (ICMS-ST)

    Módulo essencial para distribuidoras.

  • IPI e FECOEP

    Módulos para o IPI e o Fundo de Combate à Pobreza.

  • Romaneio de entrega

    Romaneio de entrega com frota.

  • Ativação por cliente

    Módulos ligados por feature flags conforme o nicho.

  • Pacotes fiscal-core e fiscal-sdk

    Cálculo e validação offline, mais um cliente tipado.

Artigo

API de Nota Fiscal modular: NFC-e, NF-e, MDF-e e NFS-e

Por VisionX · Atualizado em

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.

Por que escolher

Por que escolher o API de Nota Fiscal

  • Um motor para vários nichos

    Varejo, distribuidora, serviço e e-commerce no mesmo motor.

  • Só o que o cliente usa

    Módulos ativados por cliente, sem funções sobrando.

  • Cálculo e validação offline

    O fiscal-core calcula imposto sem rede e sem segredos.

  • Segredo no motor central

    Certificado A1 e numeração ficam fora dos produtos.

  • Reuso nos produtos VisionX

    O mesmo motor serve vários produtos, sem duplicação.

Perguntas

Perguntas frequentes sobre o API de Nota Fiscal

A API de Nota Fiscal já está disponível?

Não. O produto está em desenvolvimento, em repositório privado, e ainda não foi lançado. Não há data de lançamento, preço ou condições comerciais confirmados no material consultado. Esta página descreve o que o projeto prevê, e não um serviço já disponível, e as informações podem mudar durante o desenvolvimento.

Quais documentos fiscais a API prevê?

Os módulos previstos são NFC-e (modelo 65), NF-e (modelo 55), MDF-e (modelo 58) e NFS-e, além de ICMS-ST, IPI, FECOEP e romaneio de entrega. Todos fazem parte do desenho do projeto em desenvolvimento. Os demais módulos, como Substituição Tributária, IPI, FECOEP e romaneio de entrega, completam o desenho previsto para atender diferentes nichos de negócio.

O que significa módulo ativável por cliente?

Cada documento ou imposto é um módulo isolado, ligado por feature flags apenas para os clientes que precisam dele. O quiz de onboarding do SoftPay V2 detecta o nicho e ativa os módulos relevantes. Dessa forma, um varejista, uma distribuidora e uma empresa de serviços usam o mesmo motor, cada um com apenas os módulos de que precisa.

Quem usará a API?

O motor é a base fiscal do SoftPay V2. Um plano do repositório prevê pacotes npm para que outros produtos da VisionX usem o mesmo motor, sem cada um cuidar de certificado, numeração e SEFAZ. O objetivo declarado no plano é evitar duplicar o motor, mantendo um único ponto central para as regras e os segredos da emissão fiscal.

O que fica sempre no motor central?

Segundo o plano do projeto, certificado A1, assinatura, numeração sequencial e atualização de legislação não são embutidos offline. Esses itens ficam no motor central e chegam aos produtos por meio do SDK. Já o cálculo de imposto, as tabelas fiscais e a validação ficam no pacote fiscal-core, que funciona offline e sem qualquer segredo embutido.

Quer uma segunda opinião? Pergunte a uma IA.

Faça a pergunta sobre o API de Nota Fiscal direto no assistente que você já usa:

Fiscal para desenvolvedores

Conheça o API de Nota Fiscal

API fiscal modular: NFC-e, NF-e, MDF-e, NFS-e e impostos.