Documentação

Visão geral

O NotaLeve emite NFS-e no padrão nacional (Sistema Nacional NFS-e, gov.br/nfse), transmitindo direto ao Sefin Nacional com o certificado digital da sua empresa. Você usa pelo painel, pela API REST ou por um agente de IA via MCP — é o mesmo motor nos três caminhos.

• Reenvio automático: se o governo estiver fora do ar, a nota fica pendente e é reenviada a cada minuto até emitir.
• DANFSe em PDF no leiaute oficial, com QR de verificação.
• IBS/CBS da reforma tributária preenchido pela correlação oficial do seu serviço.
• Trilha de auditoria completa e medição da disponibilidade do Sefin a cada 5 minutos.

Ambiente atual: Homologação (produção restrita do Sefin). As notas emitidas não têm validade fiscal até a virada para produção — confira o badge no topo do painel.

Começando

1. Crie a conta da empresa em app.notaleve.com.br/registro: CNPJ, razão social, inscrição municipal, município e regime tributário. Você recebe um e-mail de boas-vindas com os próximos passos.
2. Envie o certificado digital A1 (.pfx) em Configurações → Certificado. Ele assina suas notas e fica cifrado num cofre; a senha nunca é exibida de volta. Nesse momento também conferimos se o seu município emite pelo Emissor Nacional.
3. Emita a primeira nota em Notas → Emitir nota: descrição do serviço, código de tributação (LC 116), valor e tomador. A numeração é automática.

Vai integrar um sistema? Crie uma chave de API em Integração → Chaves e pule para a seção da API.

O painel

Esqueceu a senha? Recupere por e-mail — o link vale por 1 hora e encerra as sessões antigas ao trocar.

API REST

JSON sobre HTTPS em https://notaleve.com.br. Autentique com o header x-api-key usando uma chave criada no painel (prefixo fk_). A chave enxerga apenas os recursos da sua conta.

Erros vêm no formato {"erro": "mensagem"} ou, quando o Sefin rejeita, {"erros": [{"codigo", "descricao", "complemento"}]} com os códigos oficiais.

Emitir uma nota

curl -X POST https://notaleve.com.br/invoices \
  -H "x-api-key: fk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "servico": {
      "codTributacaoNacional": "010101",
      "codNbs": "111032200",
      "descricao": "Desenvolvimento de sistema"
    },
    "valorServico": 5289.00,
    "aliquotaIss": 2.01,
    "issRetidoPeloTomador": true,
    "tomador": {
      "cnpj": "10716370000183",
      "nome": "CLIENTE LTDA",
      "endereco": {
        "logradouro": "RUA X", "numero": "100",
        "bairro": "CENTRO", "codMunicipio": "4211306", "cep": "88370114"
      }
    }
  }'

Resposta:

HTTP 201 (emitida) · 202 (pendente — reenvio automático) · 422 (rejeitada)
{
  "id": 42, "serie": "1", "numero": 12,
  "status": "emitida",
  "chaveAcesso": "NFS...",
  "erros": null
}

• 202 pendente é sucesso provisório: a nota existe e será emitida — não reenvie. Acompanhe por GET /invoices/{id} ou receba o resultado por webhook.
• aliquotaIss em branco: o Sefin aplica a alíquota do município.
• "ibsCbs": {} inclui o grupo da reforma tributária (detalhes).
• Código IBGE do município: GET /municipios?q=nome (público, sem acento).

Endpoints

Upload de XML (DPS pronta)

Para sistemas que já geram a DPS (leiaute nacional v1.01) e só precisam da transmissão: POST /invoices/xml com o XML no corpo (Content-Type: application/xml).

• O CNPJ do prestador no XML precisa ser o da sua conta (senão, 403).
• Sem assinatura? Assinamos com o certificado do cofre (RSA-SHA256, C14N exclusivo, enveloped).
• Série e número vêm do XML — use uma série diferente da usada no fluxo JSON; duplicata leva 409.
• Sefin fora do ar → 202 pendente com reenvio automático do XML já assinado.

Webhooks

Cadastre uma URL https no painel (ou via API) e receba um POST em JSON a cada mudança de status: nota.emitida, nota.rejeitada, nota.cancelada, nota.pendente. É assim que seu sistema descobre quando uma nota 202 pendente finalmente emitiu.

POST (para a sua URL)
X-NotaLeve-Evento: nota.emitida
X-NotaLeve-Assinatura: hex(hmac_sha256(segredo, corpo))

{
  "evento": "nota.emitida",
  "notaId": 42, "serie": "1", "numero": 12,
  "status": "emitida",
  "chaveAcesso": "NFS...",
  "valor": 5289.00,
  "erros": null,
  "em": "2026-08-19T18:00:00Z"
}

• O segredo (whsec_...) aparece uma única vez, na criação — valide a assinatura antes de confiar no payload.
• Responda 2xx para confirmar. Falhou? Tentamos de novo com intervalo crescente, por até 8 vezes.
• Entrega é ao menos uma vez: deduplique por notaId + status.

MCP — agentes de IA

O NotaLeve fala MCP: conecte Claude, Cursor e outros agentes à sua conta e peça em português — "emite uma nota de R$ 1.500 pro CNPJ tal". Servidor remoto em https://notaleve.com.br/mcp, autenticado pela mesma chave x-api-key.

Ferramentas: emitir_nota, listar_notas, consultar_nota, cancelar_nota, baixar_xml, resumo_dashboard, status_sefin, buscar_municipio.

Emissão e cancelamento têm efeito fiscal real — o servidor já instrui o agente a confirmar com você antes, mas mantenha essa regra nos seus prompts também.

Claude Code (terminal)

claude mcp add --transport http notaleve https://notaleve.com.br/mcp \
  --header "x-api-key: fk_SUA_CHAVE"

Claude Desktop

claude_desktop_config.json — macOS: ~/Library/Application Support/Claude/ · Windows: %APPDATA%\Claude\:

{
  "mcpServers": {
    "notaleve": {
      "command": "npx",
      "args": ["-y", "notaleve-mcp"],
      "env": { "NOTALEVE_API_KEY": "fk_SUA_CHAVE" }
    }
  }
}

Cursor

.cursor/mcp.json no projeto (ou ~/.cursor/mcp.json global):

{
  "mcpServers": {
    "notaleve": {
      "url": "https://notaleve.com.br/mcp",
      "headers": { "x-api-key": "fk_SUA_CHAVE" }
    }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json:

{
  "servers": {
    "notaleve": {
      "type": "http",
      "url": "https://notaleve.com.br/mcp",
      "headers": { "x-api-key": "fk_SUA_CHAVE" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "notaleve": {
      "serverUrl": "https://notaleve.com.br/mcp",
      "headers": { "x-api-key": "fk_SUA_CHAVE" }
    }
  }
}

OpenAI (Agents SDK / Responses API)

{
  "type": "mcp",
  "server_label": "notaleve",
  "server_url": "https://notaleve.com.br/mcp",
  "headers": { "x-api-key": "fk_SUA_CHAVE" }
}

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "notaleve": {
      "httpUrl": "https://notaleve.com.br/mcp",
      "headers": { "x-api-key": "fk_SUA_CHAVE" }
    }
  }
}

n8n e outros

n8n: nó MCP Client Tool → endpoint https://notaleve.com.br/mcp, transporte HTTP Streamable, header x-api-key. Qualquer cliente stdio: npx -y notaleve-mcp com a variável NOTALEVE_API_KEY.

claude.ai (web) e o app do ChatGPT hoje só aceitam conectores remotos com OAuth ou sem autenticação — use Claude Desktop/Code ou a ponte npx enquanto isso. Os formatos de configuração mudam rápido; em caso de erro, confira a doc de MCP do seu cliente.

Adesão do município

Nem toda cidade emite NFS-e pelo Emissor Nacional ainda: algumas aderiram só ao compartilhamento de dados (ADN) e a emissão segue no sistema municipal próprio. Se for o caso do seu município, as emissões pelo NotaLeve serão rejeitadas pelo Sefin até a adesão.

• Verificamos a adesão automaticamente quando você envia o certificado (a consulta ao governo exige o A1) e avisamos no painel e por e-mail.
• Exceção federal: MEI emite pelo Emissor Nacional em qualquer município (Res. CGSN 169/2022) — se você é MEI, ignore o aviso.
• A situação muda com o tempo — a reforma tributária pressiona todos os municípios a migrarem. Reconferimos a cada envio de certificado.

IBS/CBS — reforma tributária

A NFS-e passa a carregar o grupo IBS/CBS (novos tributos da reforma). No NotaLeve:

• Regime normal: o grupo vai automaticamente em toda nota.
• Simples Nacional / MEI: opcional até a obrigatoriedade — inclua com "ibsCbs": {} na API ou pela caixa "Incluir grupo IBS/CBS" no painel.
• Os códigos (CST, classificação tributária, indicador de operação) saem da tabela oficial de correlação do seu código de serviço; quem calcula os valores é o Sefin.
• Com IBS/CBS, o tomador precisa ter endereço (operações com incidência no adquirente — erro E0234 sem isso).

Datas: IBS/CBS obrigatório na NFS-e para regime normal em 01/10/2026; Simples Nacional no emissor nacional em 01/11/2026. O NotaLeve já está pronto.

Erros comuns (e o que fazer)

Todos os códigos E... são os oficiais do Sefin Nacional e chegam com descrição no campo erros da resposta e no detalhe da nota.

Segurança

• Certificado A1: arquivo e senha cifrados com AES-256-GCM num cofre; a chave-mestra vive fora do banco. A senha nunca é exibida de volta.
• Chaves de API: só o hash SHA-256 fica no banco — a chave completa aparece uma única vez. Revogação vale na requisição seguinte.
• Senhas: PBKDF2-SHA256 (100 mil iterações). Sessões de 7 dias revogáveis; trocar a senha derruba as sessões antigas.
• Webhooks: assinados com HMAC-SHA256; segredo cifrado no cofre.
• Papéis: Operador não acessa certificado, chaves, webhooks nem gestão de usuários.
• Auditoria: cada login, emissão, chave e certificado registrados com data e detalhe.
• Backups diários do banco, com os certificados inúteis sem a chave-mestra.

Suporte

Fale com a gente: contato@notaleve.com.br. A disponibilidade do Sefin Nacional aparece em tempo real no topo do painel e em GET /status.