Agentic Onboarding Multi-CNPJ: Como Automatizar a Implantação Fiscal de Clientes no ERP com MCP e Org API

Na semana passada, conversando com o diretor de operações de um ERP vertical para clínicas médicas que acabara de migrar para a nossa Org API, ele me confessou um número que todo fundador de SaaS B2B conhece, mas poucos admitem em público: o time comercial dele levava 20 minutos para fechar uma venda no cartão de crédito, mas a equipe de implantação levava 4 dias úteis para deixar o cliente apto a emitir a primeira NFS-e.

Quando abrimos o checklist de onboarding daquela Software House, o gargalo não estava no código de emissão em si — estava no trabalho braçal de configuração de cada novo CNPJ:

1. Validar o CNPJ/CPF do cliente e descobrir o código IBGE correto do município.
2. Verificar se a prefeitura daquela cidade já operava no Padrão Nacional (SNNFSE) ou exigia provedor municipal próprio (e se precisava de Inscrição Municipal, senha web ou RPS).
3. Perguntar ao contador do cliente qual foi o último número de RPS ou NF-e emitido no sistema antigo para configurar a sequência sem gerar Rejeição de Duplicidade nem abrir buraco fiscal.
4. Subir a logomarca da empresa para sair impressa no DANFE e no DANFSe.
5. Coletar o arquivo .pfx do Certificado Digital A1 e a senha sem trafegar credenciais sensíveis em grupos de WhatsApp e sem exigir que o contador tenha login no painel da Software House.

Aqui na Notaas, nós resolvemos esse gargalo na raiz com o lançamento do @notaas/mcp v0.2.2 (46 Tools) e os novos endpoints de sessão segura de certificado e sincronização de onboarding na Org API. Hoje quero mostrar como funciona o Agentic Onboarding Multi-CNPJ — uma arquitetura que reduz o tempo de implantação fiscal do seu ERP de dias para menos de 3 minutos, operando tanto via Agentes de IA (Claude Desktop, Claude Code, Cursor, Windsurf) quanto diretamente no wizard de ativação do seu backend em Node.js/TypeScript.

Implantar um novo cliente PJ no seu SaaS não deveria exigir um analista fiscal preenchendo planilhas: quando cada etapa do onboarding é exposta via API e MCP, a ativação vira um pipeline determinístico de 90 segundos.

O que é Agentic Onboarding Multi-CNPJ e por que ele muda a operação da Software House

O conceito de Agentic Onboarding nasceu dentro da nossa própria operação de suporte à engenharia. Mesmo oferecendo uma arquitetura Multi-CNPJ completa via Org API, percebemos que muitas Software Houses, escritórios de BPO Fiscal e startups em estágio de tração ainda dependiam de analistas de implantação (CS / Onboarding) executando tarefas repetitivas a cada novo contrato assinado.

Na versão v0.2.2 do pacote oficial @notaas/mcp (nosso servidor Model Context Protocol com 46 Tools), expandimos a família de tools organizacionais (org_*), adicionamos 4 modos seguros para envio do Certificado Digital A1 e integramos 100% de paridade com o Checklist de Onboarding da organização (onboarding_objectives) sob o prompt guiado /onboard-new-company.

Isso abre dois caminhos complementares sobre a mesma infraestrutura REST da Notaas:

1. Caminho Operacional via Agente de IA (@notaas/mcp v0.2.2): Seu analista de implantação (ou você mesmo no Claude Code / Cursor) digita apenas "Implantar o cliente CNPJ 12.345.678/0001-95 que parou na NFS-e 845 Série 1 no sistema antigo", e o agente executa autonomamente a validação do documento, verifica a cobertura municipal e os códigos LC 116, cria o projeto, ajusta a numeração, sobe o logotipo, gera um link descartável sem login (/onboarding/cert#token=...) para o contador do cliente subir o Certificado A1 e roda o diagnóstico final de prontidão.
2. Caminho Self-Service via Backend do ERP (Org API REST): Seu próprio SaaS consome exatamente as mesmas rotas REST nos bastidores do wizard de boas-vindas do usuário final.

⚡ Fluxo Arquitetural do Agentic Onboarding (/onboard-new-company · v0.2.2):

• 1. Validação Documental & Cobertura Municipal: Executa notaas_validate_cpf_cnpj, notaas_check_city_coverage (nos 5.571 municípios) e notaas_lookup_tax_codes para validar o documento (CNPJ numérico/alfanumérico ou CPF), a engine da prefeitura e os códigos de serviço LC 116.
• 2. Provisionamento do Tenant e Sincronização de Onboarding: Chama org_create_project (POST /api/v1/org/projects) criando o ambiente isolado do cliente, marcando automaticamente as etapas company_data e fiscal_config em onboarding_objectives e promovendo/substituindo automaticamente o projeto placeholder inicial ("Projeto Padrão" / CNPJ 00.000.000/0000-00) sem afetar nenhum projeto real existente.
• 3. Sincronização de Numeração e Identidade Visual: Ajusta a sequência fiscal vinda do ERP antigo via org_configure_project_numbering e aplica o logotipo no PDF com org_upload_project_logo.
• 4. Coleta Segura de Certificado A1 (4 Modos) e Gate de Prontidão: Envia o .pfx via org_upload_project_certificate (Zero-Trust pfxFilePath no stdio ou Base64) ou gera uma sessão one-time de 15 minutos com org_create_certificate_upload_session (entregando comando read -s para terminal e link Dropzone sem login /onboarding/cert#token=... para o contador) e valida as 5 dimensões críticas no agregador fail-closed org_check_project_readiness.

Caminho 1: Implantação guiada por IA com o @notaas/mcp v0.2.2

Para conectar seu ambiente de IA (Claude Desktop, Claude Code, Cursor ou agentes internos da sua equipe de CS) à sua organização na Notaas, basta configurar o servidor @notaas/mcp passando o seu Organization Token (ntaas_org_... — lembrando que você pode criar até 3 tokens grátis e homologar até 5 CNPJs sem custo no plano Free):

{
  "mcpServers": {
    "notaas": {
      "command": "npx",
      "args": ["-y", "@notaas/mcp"],
      "env": {
        "NOTAAS_ORG_TOKEN": "ntaas_org_seu_token_organizacional_aqui"
      }
    }
  }
}

Quando você aciona o prompt guiado /onboard-new-company (ou pede em linguagem natural para implantar uma empresa), o agente orquestra uma sequência rigorosa de tools. Vamos dissecar o que cada tool faz sob o capô.

1. Validação de Documento, Cobertura Municipal e Códigos Fiscais (notaas_validate_cpf_cnpj + notaas_check_city_coverage + notaas_lookup_tax_codes)

Antes de criar o projeto, o agente valida determinísticamente os parâmetros fiscais do município:

• A tool notaas_validate_cpf_cnpj valida localmente em < 1ms os dígitos verificadores do CNPJ (tanto numérico tradicional quanto o novo CNPJ Alfanumérico [0-9A-Z]{12}\d{2}) ou CPF.
• Em seguida, a tool notaas_check_city_coverage consulta nossa malha de 5.571 municípios brasileiros e informa qual engine atende aquela cidade (snnfse Nacional ou uma das 26 engines municipais próprias, como sp_prefeitura, equiplano, issnet_nacional, speedgov, gissonline, el_nacional, etc.), se exige certificado A1 ou credenciais municipais e quais operações estão ativas.
• Por fim, notaas_lookup_tax_codes busca o cTribNac (LC 116) e eventuais desdobros municipais (cTribMun) exigidos pelo código IBGE da cidade.

2. Criação do Projeto e Controle de Numeração (org_create_project + org_configure_project_numbering)

Ao criar o projeto isolado com org_create_project, a plataforma realiza automaticamente a sincronização com o funil de onboarding (onboarding_objectives): marca company_data, fiscal_config e nfe_config como concluídos e, caso a organização recém-criada ainda possua apenas o projeto placeholder inicial intocado ("Projeto Padrão" / CNPJ 00.000.000/0000-00), substitui/promove automaticamente esse placeholder para que a conta fique limpa, sem desativar nenhum projeto real.

Em seguida, chegamos ao ponto mais sensível de qualquer migração de ERP: a continuidade da numeração de RPS, NFS-e, NF-e (Mod 55) e NFC-e (Mod 65).

Se o seu cliente já emitiu até o RPS 845 (Série 1) no sistema legado e o novo ERP tentar emitir o RPS 1, a prefeitura vai rejeitar por duplicidade; pior ainda, se alguém reduzir acidentalmente o contador de uma empresa que já está em produção, você cria uma falha fiscal grave.

Por isso, no @notaas/mcp v0.2.2, o par org_get_project_numbering e org_configure_project_numbering (PATCH /api/v1/org/projects/{id}/numeracao) opera com dois modos de segurança:

• Modo Padrão (modo: "avancar"): Permite apenas aumentar o último número emitido da série (por exemplo, informar ultimoNumeroNfse: 845 para que o próximo número seja 846 na implantação inicial de um cliente vindo de outro sistema, protegido por guard GREATEST no banco).
• Modo de Exceção Auditável (modo: "forcar"): Caso um analista sênior precise redefinir uma sequência após ajuste de homologação para produção, exige modo: "forcar", confirmForceMode: true e motivo obrigatório (mínimo de 10 caracteres), limpando atomicamente o pool de números reciclados (nfse_numeros_liberados) e gravando auditoria.

3. Upload de Logomarca (org_upload_project_logo) e os 4 Modos Seguros de Certificado A1 (org_create_certificate_upload_session / org_upload_project_certificate)

A tool org_upload_project_logo recebe a imagem (PNG, JPEG ou WebP até 500 KiB) e já a vincula ao renderizador de DANFE e DANFSe v2.0 no padrão NT-008.

Já para o Certificado Digital A1 (.pfx), o @notaas/mcp v0.2.2 resolve o maior atrito de implantação das Software Houses: quando o arquivo .pfx e a senha estão com o contador ou dono da empresa cliente, que não tem (e não deve ter) login no painel administrativo da Software House.

O agente oferece 4 modos seguros:

1. Opção 1 — Referência Local Zero-Trust (stdio): Se o analista já tem o .pfx na máquina e roda npx -y @notaas/mcp, chama org_upload_project_certificate({ projectId, pfxFilePath: "~/cert.pfx", passwordEnvVar: "NOTAAS_CERT_PASS" }). O processo Node.js local lê o arquivo e a senha direto do disco — nem os bytes nem a senha passam pelo LLM.
2. Opção 2 — One-Liner Silencioso no Terminal (read -s): A tool org_create_certificate_upload_session gera um token descartável (ntaas_cert_up_<64_hex>, TTL 15 min) e devolve um comando read -r -s -p + curl para colar no terminal da IDE.
3. Opção 3 — Link Dropzone Descartável Sem Login (/onboarding/cert#token=...): A mesma chamada org_create_certificate_upload_session retorna a URL:

   https://platform.notaas.com.br/onboarding/cert#token=ntaas_cert_up_9f8e7d...
   

   Você envia esse link no WhatsApp do contador do cliente. O contador abre a tela (que mostra apenas a Razão Social e o CNPJ da empresa, sem pedir login Clerk), arrasta o .pfx e digita a senha. Como o token fica após o # (#token=), ele nunca vaza em headers HTTP Referer. A plataforma valida se o titular X.509 ICP-Brasil pertence ao CNPJ do projeto, ativa o certificado no cofre S3 e destrói o link imediatamente (com lockout automático após 5 tentativas de senha incorreta).
4. Opção 4 — Automação 100% via API / n8n (pfxBase64 + password): Para workflows que buscam o certificado em um cofre corporativo (AWS Secrets Manager, Vault) e provisionam via org_upload_project_certificate.

4. O Gate Final Fail-Closed: org_check_project_readiness

Como ter 100% de certeza de que o cliente está pronto para emitir notas em produção sem descobrir um campo faltando na segunda-feira às 8h da manhã?

Criamos a tool agregadora org_check_project_readiness. Em uma única chamada fail-closed, ela inspeciona cinco dimensões independentes do projeto e só retorna ready: true se todas estiverem verdes:

Caminho 2: Automatizando o Onboarding direto no Backend do seu ERP (TypeScript)

Se você está construindo um wizard de ativação 100% self-service dentro do seu próprio SaaS (inclusive usando stacks modernas de Vibe Coding fiscal com Next.js, Cursor e Lovable), você pode invocar os mesmos endpoints da Org API REST diretamente pelo seu backend.

Veja a implementação completa em TypeScript usando os contratos reais da Org API (https://platform.notaas.com.br/api/v1/org/*) que cria o tenant, sincroniza a última numeração do ERP antigo, gera a sessão Dropzone sem login para o certificado A1 e provisiona a chave isolada do cliente:

const ORG_TOKEN = process.env.NOTAAS_ORG_TOKEN!;
const API_URL = "https://platform.notaas.com.br/api/v1";

interface ErpOnboardingInput {
  cnpj: string;
  razaoSocial: string;
  nomeFantasia: string;
  inscricaoMunicipal: string;
  codigoMunicipio: string;
  uf: string;
  regimeTributario: "1" | "2" | "3" | "3e";
  ultimoRpsSistemaAntigo: number;
  serieNfse?: string;
}

export async function runAutomatedErpOnboarding(input: ErpOnboardingInput) {
  const headers = {
    "x-api-key": ORG_TOKEN,
    "Content-Type": "application/json"
  };

  // 1. Cria o projeto isolado do cliente (iniciando em Homologação = 2)
  // Sincroniza automaticamente company_data e fiscal_config em onboarding_objectives
  const projectRes = await fetch(`${API_URL}/org/projects`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      name: input.nomeFantasia,
      cnpj: input.cnpj,
      razaoSocial: input.razaoSocial,
      inscricaoMunicipal: input.inscricaoMunicipal,
      codigoMunicipio: input.codigoMunicipio,
      regimeTributario: input.regimeTributario,
      serieNfse: input.serieNfse ?? "1",
      endereco: { uf: input.uf },
      ambiente: 2
    })
  });
  const project = await projectRes.json();

  // 2. Sincroniza o último número de RPS emitido no ERP legado (guard GREATEST)
  const numRes = await fetch(`${API_URL}/org/projects/${project.id}/numeracao`, {
    method: "PATCH",
    headers,
    body: JSON.stringify({
      ultimoNumeroNfse: input.ultimoRpsSistemaAntigo
    })
  });
  const numbering = await numRes.json();

  // 3. Gera sessão one-time (TTL 15 min) para o cliente/contador enviar o Certificado A1 sem login Clerk
  const certSessionRes = await fetch(`${API_URL}/org/projects/${project.id}/certificate/upload-session`, {
    method: "POST",
    headers,
    body: JSON.stringify({ ttlMinutes: 15 })
  });
  const certSession = await certSessionRes.json();

  // 4. Provisiona a Project API Key dedicada do cliente (marca api_key em onboarding_objectives)
  const keyRes = await fetch(`${API_URL}/org/projects/${project.id}/api-keys`, {
    method: "POST",
    headers,
    body: JSON.stringify({ name: "erp-production-key" })
  });
  const { key: tenantApiKey } = await keyRes.json();

  return {
    projectId: project.id,
    tenantApiKey,
    nextRpsConfigured: numbering.nfse.proximoNumero,
    // Link Dropzone descartável sem login (/onboarding/cert#token=...) para enviar ao contador
    certificateDropzoneUrl: certSession.uploadSessionUrl,
    // Comando read -s + curl caso prefira enviar pelo terminal
    certificateTerminalCommand: certSession.terminalCommand
  };
}

E caso o seu próprio backend já receba o arquivo .pfx do usuário no checkout do ERP, basta enviá-lo diretamente via multipart/form-data para POST /api/v1/org/projects/${projectId}/certificate com o header x-api-key: ntaas_org_....

Escale sua operação Multi-CNPJ sem aumentar a equipe de implantação

Quando você combina a API de NFS-e Nacional e Municipal, o diagnóstico preventivo de erros de conexão e certificado A1 e o Agentic Onboarding via @notaas/mcp v0.2.2 + Org API, a implantação fiscal deixa de ser um centro de custo humano e passa a ser uma vantagem competitiva do seu software.

E o melhor: você pode testar todo esse fluxo agora mesmo sem custo. Na Notaas, você conta com:

• Até 5 projetos/CNPJs simultâneos grátis em Homologação via Org API + 1 CNPJ em Produção real com 20 notas fiscais gratuitas por mês.
• Plano Dev (R$ 99/mês para até 3 CNPJs em Produção) e Plano SaaS Pro (R$ 249/mês para CNPJs ilimitados em Produção) conforme sua base de clientes escala.

👉 Crie sua conta gratuita na Notaas ou acesse a Documentação Oficial do MCP e Org API para colocar seu Agentic Onboarding no ar hoje mesmo.