Ambiente de Teste e Homologação Multi-CNPJ na API de NFS-e e NF-e: Requisitos de Certificado A1 e Virada para Produção

Na semana passada, auditando as consultas técnicas que trazem engenheiros e arquitetos de ERP até a nossa documentação, uma pergunta apareceu dezenas de vezes com variações quase idênticas: quais são os requisitos reais de Certificado Digital A1 no ambiente de teste (homologação) de uma API de NFS-e e NF-e? E logo atrás dela vem a segunda dor de qualquer CTO de Software House: como testar a automação de onboarding Multi-CNPJ (POST /org/projects) sem ter que assinar um contrato corporativo de R$ 400 por mês antes mesmo de colocar o primeiro cliente no ar?

Eu já estive do outro lado da mesa construindo SaaS B2B e lembro exatamente da frustração. Nas APIs fiscais tradicionais (como Focus NFe, Nuvem Fiscal ou TecnoSpeed), ou você fica preso a um sandbox limitado que não reflete o comportamento real da SEFAZ e da Sefin Nacional, ou o time comercial exige upgrade imediato para um plano "Enterprise / Software House" apenas para liberar o endpoint de criação programática de empresas.

Aqui na Notaas, desenhamos nossa infraestrutura com a filosofia oposta: engenharia primeiro, fricção comercial zero. Quero responder de forma direta e técnica quais são os requisitos criptográficos do Certificado A1 em homologação e mostrar, com código TypeScript completo, como você pode homologar até 5 CNPJs simultâneos gratuitamente na nossa Org API — além de ter 1 CNPJ em produção real com 20 notas grátis por mês — e promover qualquer cliente para produção com um simples PATCH REST.

Homologação fiscal de verdade não pode ser um mock estático nem um refém comercial: o desenvolvedor precisa testar mTLS, assinatura XML e provisionamento Multi-Tenant com código real desde o Dia 1.

Requisitos de Certificado A1 no ambiente de teste da API de NFS-e e NF-e

Quem vem do ecossistema de gateways de pagamento (Stripe, Asaas, Pagar.me) costuma estranhar o conceito de "Sandbox" no sistema tributário brasileiro. Em pagamentos, uma chave sk_test_... aponta para um banco de dados isolado do próprio gateway, onde qualquer cartão fictício 4242 funciona.

No ecossistema fiscal brasileiro — composto pela Sefin Nacional / ADN (NFS-e Padrão Nacional), pelas SEFAZ Estaduais (NF-e Modelo 55 e NFC-e Modelo 65) e por centenas de webservices municipais — o ambiente de homologação (ambiente: 2 ou tag <tpAmb>2</tpAmb>) é operado pelos próprios órgãos governamentais, e a autenticação na camada de transporte ocorre via mTLS (Mutual TLS) combinada com assinatura digital XML-DSig.

Quando o Certificado A1 ICP-Brasil real é obrigatório no ambiente de teste?

Para evitar surpresas durante o desenvolvimento do seu ERP, veja a regra exata de exigência do certificado .pfx / .p12 em homologação (ambiente: 2):

Os 4 requisitos técnicos do arquivo .pfx / .p12 na API

Quando você envia um certificado para um projeto de homologação ou produção na Notaas, nosso motor criptográfico valida quatro requisitos que, se ignorados num emissor próprio, causam os famosos erros de conexão que detalhamos no artigo sobre erro ao gerar chave NFS-e e falha de conexão mTLS:

1. Formato PKCS#12 (.pfx ou .p12) com Chave Privada Exportável: Certificados A3 (token USB ou cartão inteligente) não funcionam em APIs cloud porque a chave privada fica trancada em hardware físico. O arquivo deve ser Tipo A1, contendo tanto o certificado público X.509 quanto a PrivateKey RSA de 2048 bits.
2. Extensão ICP-Brasil OID 2.16.76.1.3.3 (e-CNPJ / e-PJ): O certificado deve conter o CNPJ de 14 dígitos (ou a mesma raiz de 8 dígitos da matriz) codificado na extensão SubjectAltName padrão da ICP-Brasil. A Sefin Nacional e a SEFAZ permitem assinar notas de uma filial usando o certificado A1 da matriz (mesmo CNPJ base de 8 dígitos).
3. Validade Temporal Ativa: Nem a SEFAZ Homologação nem a Produção Restrita do ADN aceitam certificados A1 vencidos ou autoassinados (self-signed gerados via OpenSSL local). A cadeia deve subir até a AC Raiz Brasileira (v5, v10 ou v11).
4. Cifras Legadas (RC2-40-CBC / 3DES) vs. OpenSSL 3: Muitas Autoridades Certificadoras brasileiras ainda exportam arquivos .pfx com algoritmos legados que quebram no Node.js 18/20/22 (ERR_OSSL_EVP_UNSUPPORTED). Na Notaas, você não precisa rodar openssl pkcs12 -legacy manualmente: nosso endpoint POST /api/v1/org/projects/{id}/certificate decodifica e normaliza containers legados e modernos de forma nativa.

Como funciona o Plano Gratuito da Notaas para Software Houses e SaaS

Quando criamos a arquitetura Multi-CNPJ da Org API, fizemos uma pergunta simples: por que obrigar uma Software House a pagar mensalidade enquanto o desenvolvedor ainda está escrevendo o código de integração e homologando os primeiros clientes?

Na Notaas, qualquer conta criada gratuitamente já nasce com acesso total à Org API sob um modelo claro e generoso:

• Até 3 Organization Tokens (ntaas_org_...) gratuitos: Credenciais mestras de nível organizacional para o backend do seu ERP gerenciar projetos, certificados e chaves via API.
• Até 5 Projetos (CNPJs/CPFs) simultâneos em Homologação (ambiente: 2) a R$ 0/mês: Você pode provisionar até 5 empresas de clientes em ambiente de teste via POST /api/v1/org/projects, subir certificados A1, configurar séries de RPS/NF-e e disparar emissões de homologação ilimitadas sem pagar um centavo.
• 1 Projeto (CNPJ) em Produção Real (ambiente: 1) com 20 notas fiscais gratuitas por mês: Permite validar notas reais com valor jurídico na SEFAZ e nas prefeituras desde o primeiro dia, sem cartão de crédito e sem trial que expira em 7 dias.

⚡ Fluxo Arquitetural do Ciclo de Vida Multi-CNPJ na Org API:

• 1. Provisionamento Sandbox (ambiente: 2): O ERP chama POST /api/v1/org/projects com o ntaas_org_... e cria o tenant isolado do cliente em homologação (até 5 projetos grátis).
• 2. Upload de Certificado A1: O backend envia o .pfx em Base64 para POST /api/v1/org/projects/{id}/certificate, que extrai o CNPJ do X.509 e armazena no cofre AES-256-GCM.
• 3. Credencial Isolada por Tenant: O ERP gera a chave dedicada do cliente (POST /api/v1/org/projects/{id}/api-keys) e realiza os disparos de teste de NFS-e e NF-e.
• 4. Virada para Produção (PATCH): Com a homologação aprovada, o ERP envia PATCH /api/v1/org/projects/{id} com {"ambiente": 1} — mantendo o mesmo projectId e a mesma Project API Key.

Passo a Passo em TypeScript: Da Homologação Multi-CNPJ à Virada para Produção

Vamos ao código real. Imagine que um novo cliente acabou de se cadastrar no seu ERP ou plataforma SaaS. Veja como implementar as 4 etapas do ciclo de vida usando fetch() nativo em TypeScript:

Passo 1: Criar o projeto do cliente em Homologação (POST /api/v1/org/projects)

Durante o onboarding inicial, criamos o projeto especificando "ambiente": 2 (Homologação). Dessa forma, ele consome um dos seus 5 slots gratuitos de sandbox e bloqueia qualquer emissão acidental com validade jurídica enquanto a implantação está sendo testada:

const ORG_TOKEN = process.env.NOTAAS_ORG_TOKEN!; // ex: ntaas_org_live_...
const BASE_URL = "https://api.notaas.com.br/api/v1";

export async function createHomologationTenant(customer: {
  cnpj: string;
  razaoSocial: string;
  nomeFantasia: string;
  inscricaoMunicipal: string;
  inscricaoEstadual?: string;
  codigoMunicipio: string;
  uf: string;
  regimeTributario: number; // 1 = Simples Nacional, 3 = Regime Normal
}) {
  const response = await fetch(`${BASE_URL}/org/projects`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${ORG_TOKEN}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: `${customer.nomeFantasia} (Homologação)`,
      cpfCnpj: customer.cnpj.replace(/\D/g, ""),
      razaoSocial: customer.razaoSocial,
      nomeFantasia: customer.nomeFantasia,
      inscricaoMunicipal: customer.inscricaoMunicipal,
      inscricaoEstadual: customer.inscricaoEstadual,
      codigoMunicipio: customer.codigoMunicipio,
      uf: customer.uf,
      regimeTributario: customer.regimeTributario,
      ambiente: 2 // 2 = Homologação (até 5 projetos simultâneos grátis no plano Free)
    })
  });

  if (!response.ok) {
    throw new Error(`Falha ao criar projeto: ${await response.text()}`);
  }

  const project = await response.json();
  // Retorna { id: "proj_01J...", ambiente: 2, cpfCnpj: "...", status: "active" }
  return project;
}

Passo 2: Enviar o Certificado A1 em Base64 (POST /api/v1/org/projects/{id}/certificate)

Com o projectId em mãos, o cliente faz upload do arquivo .pfx na tela de configurações do seu ERP e seu backend repassa o binário em Base64 para o cofre isolado daquele projeto:

export async function uploadTenantCertificate(
  projectId: string,
  pfxBuffer: Buffer,
  pfxPassword: string
) {
  const response = await fetch(`${BASE_URL}/org/projects/${projectId}/certificate`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${ORG_TOKEN}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      certificateBase64: pfxBuffer.toString("base64"),
      password: pfxPassword
    })
  });

  if (!response.ok) {
    throw new Error(`Certificado A1 inválido: ${await response.text()}`);
  }

  return await response.json();
  // Retorna { validFrom, validTo, subjectCnpj, issuer, status: "VALID" }
}

Passo 3: Gerar a Project API Key isolada (POST /api/v1/org/projects/{id}/api-keys)

A melhor prática de segurança Multi-Tenant é nunca usar o seu Organization Token para emitir notas diretamente. Em vez disso, provisionamos uma Project API Key exclusiva para o tenant recém-criado e salvamos no banco de dados do ERP associada ao tenant_id do cliente:

export async function provisionTenantApiKey(projectId: string, tenantId: string) {
  const response = await fetch(`${BASE_URL}/org/projects/${projectId}/api-keys`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${ORG_TOKEN}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: `erp-tenant-${tenantId}-key`
    })
  });

  const { apiKey } = await response.json();
  // Salve `apiKey` criptografada no registro do cliente no banco do seu SaaS
  return apiKey;
}

A partir desse instante, qualquer chamada para POST /api/v1/nfse ou POST /api/v1/nfe autenticada com essa apiKey será roteada para a Produção Restrita do ADN ou para a SEFAZ Homologação, gerando o XML assinado e o PDF de teste com a marca d'água de homologação (construído sobre a mesma engine que detalhamos no guia técnico do DANFSe v2.0 e NT-008).

Passo 4: Promover o cliente para Produção Real via PATCH /api/v1/org/projects/{id}

Aqui está a beleza arquitetural da Notaas. Em muitas APIs antigas, mudar um cliente de homologação para produção obriga você a recriar o cadastro em outra URL base (sandbox.api... para producao.api...), reenviar o certificado A1 e substituir o token no banco de dados.

Na Notaas, a URL base é única (https://api.notaas.com.br/api/v1), o certificado A1 já está validado no cofre do projeto e a Project API Key continua exatamente a mesma. Para virar a chave do cliente para Produção (ambiente: 1), basta disparar um PATCH:

export async function promoteTenantToProduction(projectId: string, nomeFantasia: string) {
  const response = await fetch(`${BASE_URL}/org/projects/${projectId}`, {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${ORG_TOKEN}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: nomeFantasia,
      ambiente: 1 // Promove instantaneamente o projeto de Homologação (2) para Produção (1)
    })
  });

  if (!response.ok) {
    throw new Error(`Erro ao promover projeto para produção: ${await response.text()}`);
  }

  return await response.json();
}

Assim que o PATCH retorna 200 OK, o slot de homologação daquele projeto é liberado para você testar o próximo cliente da fila, e o cliente promovido passa a emitir documentos com validade fiscal plena nos 4.782+ municípios atendidos pela nossa cobertura nacional ou nas SEFAZ estaduais.

Escada de Planos Transparente: Do Free ao SaaS Pro sem pegadinhas

Um ponto de honra para nós na Notaas é a previsibilidade financeira para quem constrói software, seja uma Software House consolidada ou um fundador criando um Micro-SaaS com Vibe Coding fiscal em Next.js, Cursor e Lovable.

Veja exatamente como funciona a progressão de limites de projetos conforme sua operação cresce:

Perceba a diferença estrutural: você desenvolve toda a integração com a API de NFS-e Nacional e Municipal, testa o onboarding automatizado com 5 empresas simultâneas em homologação e valida o primeiro CNPJ em produção gastando R$ 0. Quando o seu 2º ou 3º cliente precisa ser promovido via PATCH para ambiente: 1, você sobe para o Plano Dev (R$ 99/mês); e quando sua carteira escala para dezenas ou centenas de clientes, o Plano SaaS Pro (R$ 249/mês) libera CNPJs ilimitados sem cobrar pedágio por empresa cadastrada.

👉 Crie sua conta gratuita na Notaas agora, gere seu primeiro Organization Token em 30 segundos e consulte a referência completa da Org API na nossa Documentação Oficial.