API NFS-e para software houses: como integrar emissão fiscal ao ERP sem manter dezenas de conectores

Eu já vi muita software house começar uma integração de NFS-e com uma sensação de controle. A ideia parece razoável: criar um conector para a primeira prefeitura, guardar as regras no ERP e repetir o processo quando surgir uma nova cidade. O problema aparece quando o sistema passa a atender vários clientes, cada um com seu CNPJ, certificado, regime tributário, município e forma de emissão.

Um município pode usar o Ambiente Nacional da NFS-e. Outro pode exigir SOAP, XML assinado e certificado A1. Um terceiro pode seguir uma versão específica do padrão ABRASF. Também existem integrações REST, credenciais Basic Auth, códigos municipais próprios, respostas assíncronas e provedores que não oferecem um ambiente público de homologação.

Por isso, a software house precisa decidir se quer manter toda essa borda fiscal dentro do ERP ou consumir uma API NFS-e com contrato estável. A seguir, mostro como isso funciona na realidade da Notaas, incluindo os recursos existentes e os limites que ainda dependem de cada engine municipal.

Por que integrações municipais crescem tão rápido dentro de um ERP?

No começo, um conector próprio pode parecer uma escolha eficiente. Se a software house atende poucos clientes na mesma cidade, o custo inicial é previsível. O problema é que essa arquitetura cresce por multiplicação, não apenas por volume.

Cada novo sistema municipal pode adicionar uma combinação diferente de:

• layout de DPS ou RPS;
• versão de schema XML;
• assinatura XMLDSig ou assinatura de cadeia de caracteres;
• SOAP 1.1, SOAP 1.2 ou REST;
• mTLS com certificado A1;
• usuário e senha municipais;
• código de serviço e inscrição municipal;
• envio individual ou em lote;
• processamento síncrono ou consulta posterior por protocolo;
• consulta, cancelamento e obtenção de documentos.

Também existe o custo operacional. Uma prefeitura pode ficar indisponível, alterar uma regra ou devolver uma rejeição pouco clara. O ERP precisa registrar o estado, evitar uma segunda emissão indevida e dar informação suficiente ao suporte. A primeira nota demonstra que o conector funciona; milhares de notas mostram se a operação é confiável.

O que a API NFS-e da Notaas abstrai atualmente?

A Notaas expõe uma API REST para o ERP, mas não transforma todas as prefeituras no mesmo sistema por baixo. A plataforma mantém engines diferentes e escolhe a estratégia de emissão a partir do município configurado no projeto.

Atualmente, o roteador contempla o Ambiente Nacional e integrações como Prefeitura de São Paulo, Pronim/Cidade360, DSF, Centi, GINFES, WebISS, TBW/SIL, TINUS, COPLAN, EL, SIGEP, Fiorilli, GISSOnline, HM2, Betha, Brasília, ISSNet, Salvador e Barueri.

Essa lista não representa cobertura universal. Uma engine implementada não torna automaticamente compatível todo município que use uma marca semelhante. Endpoint, versão, credenciais e regras locais precisam ser conferidos na documentação de cobertura.

O fluxo interno é, de forma simplificada:

ERP
  → POST /api/v1/emitir
  → validação do projeto e do payload
  → criação da invoice com status queued
  → fila RabbitMQ conforme o plano
  → roteamento para a engine do município
  → prefeitura, provedor municipal ou SNNFSE
  → atualização de status e webhook
  → cache de XML/PDF e evento documents_ready

Para o ERP, o contrato de entrada permanece semelhante. Na borda fiscal, a Notaas decide se precisa gerar DPS, RPS, XML ABRASF, envelope SOAP, JSON compactado ou outro formato aceito pelo destino.

Como funciona o multi-tenant na realidade da Notaas?

Na API de emissão, o tenant não é enviado dentro do JSON. A identidade fiscal é determinada pela API key.

Cada Project API Key começa com ntaas_ e está vinculada a um projeto. O projeto representa a empresa emissora e contém informações como CNPJ, razão social, município, regime tributário, inscrição municipal, ambiente, código de tributação padrão e configurações específicas da engine.

Por isso, o payload de emissão não deve conter campos inventados como tenant_id, company_id ou cnpj_emitente. O ERP escolhe o emissor usando a Project API Key correspondente no header x-api-key.

Para uma software house com muitos clientes, existem dois caminhos:

1. Cadastrar projetos, certificados e chaves pelo dashboard e guardar a associação entre cliente e Project API Key.
2. Usar a Org API Enterprise para criar projetos, chaves, certificados e configurações programaticamente.

A Org API usa tokens ntaas_org_ com escopos granulares. Eles administram a organização, mas não substituem a Project API Key no POST /api/v1/emitir.

O ERP não deve colocar essas chaves no frontend nem compartilhar uma Project API Key entre CNPJs. Cada credencial deve permanecer no backend, protegida por variáveis de ambiente ou cofre de segredos.

Certificado A1 e configurações por empresa

O certificado A1 é cadastrado no projeto e processado pela infraestrutura da Notaas durante a emissão. O ERP não envia o arquivo PFX nem sua senha a cada nota.

Algumas engines exigem configurações adicionais. São Paulo pode pedir inscrição municipal e código de serviço; GINFES pode depender de CNAE; Centi, HM2, SIGEP e Fiorilli possuem credenciais próprias; e municípios TBW podem exigir NBS.

Antes de criar a invoice, a API valida o cadastro conforme a engine. Se faltarem campos, responde 422 com as configurações necessárias, sem enfileirar uma emissão inviável.

O payload correto do POST /api/v1/emitir

O endpoint público de emissão é:

POST https://platform.notaas.com.br/api/v1/emitir
Content-Type: application/json
x-api-key: ntaas_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

Um exemplo compatível com o contrato atual é:

{
  "referencia": "FATURA-2026-000845",
  "tomador": {
    "nome": "Empresa Cliente Ltda",
    "cnpj": "12345678000195",
    "email": "financeiro@cliente.com.br",
    "endereco": {
      "logradouro": "Rua das Flores",
      "numero": "100",
      "bairro": "Centro",
      "cidade": "Londrina",
      "uf": "PR",
      "cep": "86010010"
    }
  },
  "servico": {
    "codigo": "010700",
    "descricao": "Suporte técnico em software"
  },
  "valores": {
    "total": 1290.00,
    "aliquotaIss": 2.0,
    "issRetido": false
  },
  "competencia": "2026-08"
}

O exemplo é ilustrativo. O código de tributação, a alíquota e a retenção devem refletir o serviço, o município e a orientação fiscal aplicável à empresa.

Alguns detalhes do contrato merecem atenção:

• tomador.nome, servico.descricao, valores.total e valores.aliquotaIss fazem parte do conjunto mínimo esperado.
• servico.codigo usa o Código de Tributação Nacional com seis dígitos, como 010700. Não use formatos como 1.07 ou 0701.
• O código pode ser omitido quando existe um cTribNac padrão configurado no projeto.
• servico.nbs possui nove dígitos e é obrigatório em engines TBW/SIL.
• servico.codigoTributacaoMunicipal é um desdobro municipal de três dígitos quando aplicável.
• referencia é aceita como identificador externo opcional, mas não é devolvida hoje nas consultas da invoice.

É importante não tratar referencia como garantia de idempotência ou mecanismo completo de rastreabilidade. No fluxo atual, ela é aceita no request, mas não bloqueia uma segunda emissão nem aparece na resposta de status. A software house deve persistir no próprio ERP a relação entre sua fatura, a referência enviada e o invoiceId retornado pela Notaas.

Resposta assíncrona e estados reais

Quando a solicitação é aceita, a API responde com HTTP 202 Accepted:

{
  "queued": true,
  "invoiceId": "uuid-da-invoice",
  "status": "queued",
  "pollUrl": "/api/v1/invoices/uuid-da-invoice/status"
}

O 202 não significa que a NFS-e foi autorizada. Ele confirma apenas que a solicitação foi validada, registrada e enfileirada.

Os principais estados são:

• queued: aguardando processamento;
• processing: em processamento;
• issued: emitida;
• error: emissão rejeitada ou encerrada com erro;
• cancelling: cancelamento em andamento;
• cancelled: cancelada.

O ERP pode consultar:

GET /api/v1/invoices/{invoiceId}/status
x-api-key: ntaas_...

Quando a nota está emitida, a resposta pode conter chave, número, ambiente e, depois que os documentos forem armazenados, xmlUrl, pdfUrl e documentsCached: true. Se o documento ainda estiver sendo buscado ou gerado, essas URLs podem não aparecer imediatamente.

Webhooks: quais eventos existem?

A Notaas permite webhooks vinculados ao projeto. Sem uma configuração específica, a plataforma pode usar o endpoint da organização.

Os eventos públicos de NFS-e incluem:

• nfse.issued;
• nfse.error;
• nfse.cancelled;
• nfse.documents_ready;
• batch.completed para emissões em lote.

O webhook pode ser assinado com HMAC-SHA256. Quando um secret é configurado, a Notaas envia X-Notaas-Signature; o ERP deve validar a assinatura usando o corpo bruto da requisição. A entrega possui um identificador em X-Notaas-Delivery, que deve ser persistido para que o consumidor não processe o mesmo evento duas vezes.

A plataforma tenta entregar o webhook até cinco vezes. Mesmo assim, o ERP deve combinar webhook com consulta: webhook é notificação, enquanto o status permite reconciliar entregas ausentes.

XML, PDF e cancelamento têm o mesmo suporte em todas as engines?

Não. Esse é um ponto que precisa aparecer com clareza em qualquer avaliação.

O XML de emissão pode ser obtido por:

GET /api/v1/invoices/{invoiceId}/xml

Para notas emitidas ou canceladas, a rota prioriza o documento armazenado no CDN e pode redirecionar para a URL pública. Também existe ?type=cancel para o XML de cancelamento quando disponível.

O PDF pode ser solicitado por:

GET /api/v1/invoices/{invoiceId}/pdf

O comportamento varia por engine. No SNNFSE, a plataforma consulta o ADN; no Pronim/Cidade360, usa o fluxo do provedor; em São Paulo, pode redirecionar ao portal municipal; em Salvador, existe geração e cache próprios. Portanto, PDF não deve ser prometido de forma uniforme sem conferir a cobertura do sistema municipal.

O cancelamento também é assíncrono:

POST /api/v1/cancelar
Content-Type: application/json
x-api-key: ntaas_...{
  "invoiceId": "uuid-da-invoice"
}

Ele está implementado para um conjunto de engines, incluindo SNNFSE, São Paulo, DSF, Centi, WebISS, EL, Brasília, ISSNet, TBW e Pronim/Cidade360. Para outras engines, a API pode responder 501 porque o cancelamento ainda não está disponível naquele sistema.

O que a software house ainda precisa implementar no ERP?

Usar uma API fiscal não elimina responsabilidades do produto. O ERP ainda precisa de:

• uma relação entre cliente, projeto Notaas e Project API Key;
• armazenamento seguro de credenciais;
• vínculo único entre fatura interna e invoiceId;
• prevenção local de reenvio da mesma fatura;
• máquina de estados compatível com o fluxo assíncrono;
• consumidor de webhook com validação HMAC;
• deduplicação por X-Notaas-Delivery;
• polling de reconciliação para eventos ausentes;
• tratamento separado para erro fiscal e falha transitória;
• interface de suporte com errorCode, errorMessage e erros estruturados;
• atualização posterior das URLs de XML e PDF após nfse.documents_ready.

O erro mais perigoso é reenviar automaticamente um POST /emitir apenas porque o ERP perdeu a resposta HTTP. Como referencia ainda não é uma chave idempotente, primeiro é necessário verificar se o invoiceId foi persistido, consultar o histórico interno e reconciliar o estado antes de criar uma nova emissão.

Build versus buy: como decidir?

Construir internamente pode fazer sentido em uma operação restrita, com poucos municípios, equipe fiscal especializada e razão estratégica para controlar o protocolo. Fora disso, a conta inclui mais do que desenvolvimento:

• criação e manutenção das engines;
• homologação por provedor e município;
• atualização de schemas e notas técnicas;
• armazenamento e renovação dos certificados;
• plantão para indisponibilidade externa;
• observabilidade, filas e reprocessamento;
• consulta, cancelamento, XML e PDF;
• documentação e onboarding;
• suporte de segundo nível;
• custo de oportunidade do roadmap.

Uma API NFS-e é especialmente interessante quando a software house quer transformar emissão fiscal em parte permanente do produto, sem transformar sua equipe em mantenedora de protocolos municipais.

Checklist para avaliar a Notaas no seu cenário

Antes de contratar ou migrar, eu faria uma prova controlada:

1. Liste municípios, regimes e serviços da carteira.
2. Consulte a cobertura de cada município.
3. Identifique IM, CNAE, códigos, NBS e credenciais adicionais.
4. Crie um projeto, uma Project API Key e cadastre o A1.
5. Emita em homologação quando a engine oferecer esse ambiente.
6. Teste estados, webhook com HMAC e uma rejeição realista.
7. Confirme XML, PDF e cancelamento para a engine.
8. Avalie a Org API Enterprise se o onboarding for automatizado.
9. Confirme preços, créditos e limites antes de projetar a margem.

O avanço do padrão nacional muda a decisão?

O padrão nacional reduz a fragmentação, mas não elimina roteamento e validação. O monitoramento oficial registrava 5.565 entes aderentes, 99,95% da população e praticamente toda a arrecadação de serviços. Adesão, porém, não garante que o cenário de um CNPJ esteja operacional em determinada API.

Além disso, ME e EPP optantes pelo Simples Nacional deverão usar o Emissor Nacional a partir de 1º de setembro de 2026. A emissão poderá ocorrer pelo portal ou por ERP integrado à API da SEFIN Nacional.

Para uma software house, isso aumenta a importância de uma arquitetura capaz de mudar o destino fiscal sem exigir alteração do contrato principal do ERP.

Conclusão

A realidade da Notaas é mais específica — e mais útil — do que a ideia genérica de uma API que recebe qualquer JSON e resolve tudo de forma uniforme.

O ERP autentica cada empresa emissora com uma Project API Key. O POST /api/v1/emitir recebe tomador, serviço, valores e competência, retorna 202 com invoiceId e processa a emissão em fila. O roteador seleciona uma das engines disponíveis. O resultado pode ser acompanhado por status e webhooks. XML, PDF e cancelamento existem, mas sua disponibilidade depende do sistema municipal.

Para operações multiempresa, a Org API Enterprise permite automatizar projetos, chaves, certificados e configurações. A correlação entre a fatura do ERP, a referencia enviada e o invoiceId precisa ser persistida pela software house, assim como a prevenção de duplicidades.

Essa transparência é importante porque a melhor integração fiscal não é a que promete apagar toda a complexidade. É a que define um contrato claro, informa os limites e permite que o ERP trate corretamente cada estado da operação.

Se você quer avaliar esse caminho, escolha um CNPJ e alguns municípios representativos da sua carteira. Confira a cobertura, faça uma emissão de teste, configure um webhook, consulte o XML e valide o comportamento de erro. Essa prova mostra com muito mais precisão quanto trabalho a API NFS-e pode retirar do seu roadmap.

Perguntas frequentes

O que é uma API NFS-e?

É uma interface que permite ao ERP solicitar, acompanhar e gerenciar a emissão de Nota Fiscal de Serviço eletrônica por chamadas padronizadas. Na Notaas, a API REST abstrai diferentes engines municipais e o Ambiente Nacional, mantendo um contrato de entrada comum para o ERP.

Como escolher o CNPJ emissor na API Notaas?

O CNPJ não é escolhido por um campo company_id no payload. Ele vem do projeto associado à Project API Key enviada no header x-api-key. Para vários CNPJs, a software house mantém projetos e chaves separados. No plano Enterprise, esse onboarding pode ser automatizado pela Org API.

A API Notaas possui idempotência nativa?

O payload aceita referencia, mas o contrato atual não deduplica por esse campo nem o devolve na consulta de status. O ERP deve persistir a relação entre sua referência e o invoiceId, impedir o reenvio da mesma fatura e deduplicar webhooks pelo identificador da entrega.

O retorno 202 significa que a nota foi emitida?

Não. 202 Accepted significa que a requisição foi aceita e enfileirada. A autorização deve ser confirmada quando o status mudar para issued, por consulta ou pelo evento nfse.issued.

XML, PDF e cancelamento funcionam em todas as cidades?

Não de maneira uniforme. O XML possui uma rota pública para notas emitidas, mas PDF e cancelamento dependem do suporte da engine municipal. A cobertura deve ser validada para os municípios e cenários usados pela software house.

Preciso administrar um certificado para cada cliente?

Cada empresa emissora precisa das credenciais exigidas pelo seu fluxo. Na Notaas, o certificado A1 é cadastrado no projeto correspondente e usado pela infraestrutura durante a emissão. A software house não precisa enviar o PFX a cada requisição.

Posso usar a Notaas em um produto white-label?

A Org API Enterprise oferece gestão programática de projetos, API keys, certificados e configuração de domínio white-label para documentos. O escopo comercial e visual desejado deve ser confirmado com o plano vigente, sem presumir que toda a interface da plataforma será automaticamente personalizada.