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. Consultar os dados cadastrais do CNPJ na Receita Federal 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.

Aqui na Notaas, nós resolvemos esse gargalo na raiz com o lançamento do @notaas/mcp v0.2.1 e a expansão dos endpoints de configuração da 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, 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.

Ao lançarmos a versão v0.2.1 do pacote oficial @notaas/mcp (nosso servidor Model Context Protocol), adicionamos a família completa de tools organizacionais (org_*) e 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.1): Seu analista de implantação (ou você mesmo no Claude Desktop / Cursor) digita apenas "Implantar o cliente CNPJ 12.345.678/0001-99 que parou na NFS-e 845 Série 1 no sistema antigo", e o agente executa autonomamente a consulta cadastral, valida a cobertura municipal, cria o projeto, ajusta a numeração com trava de auditoria, sobe o logotipo, gera o link seguro de certificado 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):

• 1. Descoberta Cadastral & Municipal: Executa notaas_lookup_cnpj e notaas_check_city_coverage para validar Razão Social, CNAEs, código IBGE e requisitos do provedor da prefeitura.
• 2. Provisionamento do Tenant: Chama org_create_project (POST /api/v1/org/projects) criando o ambiente isolado do cliente e gerando sua Project API Key.
• 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 e Gate de Prontidão: Gera o deep-link /certificates?projectId=... via org_get_project_certificate_status 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.1

Para conectar seu ambiente de IA (Claude Desktop, 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@latest"],
      "env": {
        "NOTAAS_API_KEY": "ntaas_org_live_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. Enriquecimento de CNPJ e Cobertura Municipal (notaas_lookup_cnpj + notaas_check_city_coverage)

O agente nunca pede para o humano digitar endereço, CEP ou código IBGE manualmente. Com apenas os 14 dígitos do CNPJ:

• A tool notaas_lookup_cnpj consulta a base cadastral atualizada, retornando Razão Social, Nome Fantasia, situação cadastral ativa, CNAE principal, optante pelo Simples Nacional/MEI e o codigoMunicipio IBGE de 7 dígitos.
• Em seguida, a tool notaas_check_city_coverage consulta em tempo real nossa malha de 4.782+ municípios atendidos e informa qual engine atende aquela cidade (ex.: snnfse_nacional, equiplano, issnet_nacional, speedgov), se exige certificado A1 e quais operações estão ativas.

2. Criação do Projeto e Controle de Numeração com Proteção Auditável (org_configure_project_numbering)

Após criar o projeto isolado com org_create_project, 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.1, o par org_get_project_numbering e org_configure_project_numbering opera com dois modos de segurança:

• Modo Padrão (modo: "avancar"): Permite apenas aumentar o próximo número da série (por exemplo, avançar de 1 para 846 na implantação inicial de um cliente vindo de outro sistema). Qualquer tentativa de configurar um número menor ou igual ao já emitido na Notaas é bloqueada.
• Modo de Exceção Auditável (modo: "forcar"): Caso um analista sênior precise redefinir ou retroceder uma série após estorno/inutilização ou ajuste de homologação para produção, a API e o MCP exigem três travas simultâneas: modo: "forcar", a flag explícita confirmForceMode: true e o campo obrigatório motivo (mínimo de 10 caracteres descrevendo a razão técnica, que fica gravada no log de auditoria imutável do projeto).

3. Upload de Logomarca (org_upload_project_logo) e Deep-Link de Certificado A1 (org_get_project_certificate_status)

Ninguém quer receber uma nota fiscal genérica sem a identidade visual do prestador. A tool org_upload_project_logo recebe a imagem (PNG, JPEG ou WebP em Base64 ou URL) e já a vincula ao renderizador local de DANFE e DANFSe v2.0 no padrão NT-008.

E quando o cliente não quer enviar o arquivo .pfx e a senha para o analista de suporte no WhatsApp? Basta chamar org_get_project_certificate_status. Quando o projeto ainda não possui certificado válido, a tool retorna o status detalhado e gera automaticamente a URL direta com o projeto pré-selecionado:

https://platform.notaas.com.br/certificates?projectId=proj_01J9XYZ...

Você (ou seu portal) pode usar o upload direto via API (org_upload_project_certificate) ou guiar a operação com essa URL pré-filtrada sem risco de subir o .pfx na empresa errada.

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 de um serviço de onboarding que cria o tenant, sincroniza a última numeração do ERP antigo, sobe o logotipo e valida a prontidão:

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

interface ErpOnboardingInput {
  cnpj: string;
  razaoSocial: string;
  nomeFantasia: string;
  inscricaoMunicipal: string;
  codigoMunicipio: string;
  uf: string;
  regimeTributario: number;
  ultimoRpsSistemaAntigo: number;
  serieRps: string;
  logoBase64?: string;
}

export async function runAutomatedErpOnboarding(input: ErpOnboardingInput) {
  const headers = {
    "Authorization": `Bearer ${ORG_TOKEN}`,
    "Content-Type": "application/json"
  };

  // 1. Cria o projeto isolado do cliente (iniciando em Homologação = 2)
  const projectRes = await fetch(`${API_URL}/org/projects`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      name: input.nomeFantasia,
      cpfCnpj: input.cnpj.replace(/\D/g, ""),
      razaoSocial: input.razaoSocial,
      nomeFantasia: input.nomeFantasia,
      inscricaoMunicipal: input.inscricaoMunicipal,
      codigoMunicipio: input.codigoMunicipio,
      uf: input.uf,
      regimeTributario: input.regimeTributario,
      ambiente: 2
    })
  });
  const project = await projectRes.json();

  // 2. Configura a numeração de RPS a partir do último número emitido no ERP legado
  const proximoNumero = input.ultimoRpsSistemaAntigo + 1;
  await fetch(`${API_URL}/org/projects/${project.id}/numbering`, {
    method: "PUT",
    headers,
    body: JSON.stringify({
      documento: "nfse",
      serie: input.serieRps,
      proximoNumero,
      modo: "avancar", // Seguro: só permite avançar a sequência
      motivo: `Migração de ERP legado (último RPS emitido: ${input.ultimoRpsSistemaAntigo})`
    })
  });

  // 3. Faz upload do logotipo da empresa para sair no DANFSe v2.0 e DANFE
  if (input.logoBase64) {
    await fetch(`${API_URL}/org/projects/${project.id}/logo`, {
      method: "POST",
      headers,
      body: JSON.stringify({
        logoBase64: input.logoBase64,
        mimeType: "image/png"
      })
    });
  }

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

  return {
    projectId: project.id,
    tenantApiKey: apiKey,
    nextRpsConfigured: proximoNumero,
    certificateUploadUrl: `https://platform.notaas.com.br/certificates?projectId=${project.id}`
  };
}

Caso em algum cenário específico de migração assistida sua equipe precise forçar uma redefinição de numeração (modo: "forcar"), o payload exige o contrato explícito de segurança:

// Exemplo de redefinição auditável com modo "forcar"
await fetch(`${API_URL}/org/projects/${projectId}/numbering`, {
  method: "PUT",
  headers,
  body: JSON.stringify({
    documento: "nfse",
    serie: "1",
    proximoNumero: 500,
    modo: "forcar",
    confirmForceMode: true,
    motivo: "Ajuste auditado pós-homologação autorizado pelo contador responsável"
  })
});

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.1 + 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 da Org API e MCP para colocar seu Agentic Onboarding no ar hoje mesmo.