Documentação do notas.dev
Tudo para emitir NFS-e Nacional pelo painel, pela sua IA (MCP) ou por uma integração própria (API REST): certificado A1, créditos, campos da nota, configuração fiscal, cancelamento e códigos de erro.
Começando
- Crie a conta em /login: e-mail e link ou código de acesso, sem senha.
- Suba o certificado A1 (.pfx e senha) no painel. CNPJ, razão social e endereço saem do próprio certificado e do cadastro da Receita.
- Emita pelo painel, pela IA (conectar) ou pela API REST. A nota vai para a SEFIN Nacional na hora; XML e DANFSe ficam na lista de notas.
O painel mostra créditos de notas, não um saldo em dinheiro. Cadastre um cartão e autorize o reabastecimento para receber 10 notas grátis; nada é cobrado no cadastro.
Certificado A1
O certificado A1 é um arquivo (.pfx ou .p12) protegido por senha, emitido por uma Autoridade Certificadora credenciada na ICP-Brasil, com validade de 1 ano. É ele que assina a NFS-e Nacional em nome do CNPJ. O tipo A3 (cartão ou token físico) não funciona aqui, porque precisa estar plugado no computador na hora de assinar.
- Cifrado com envelope AES-256-GCM; a chave-mestra fica fora do banco e do código.
- Decifrado só em memória, no serviço emissor, no instante de assinar.
- Senha e .pfx nunca aparecem em log.
- Você pode destruir o certificado quando quiser (crypto-shredding), em Configurações.
Preço e créditos
- Cada nota autorizada consome 1 crédito de nota (preço vigente: R$ 0,10).
- Nota rejeitada não cobra: corrija o motivo e reemita.
- Cancelamento não devolve crédito: é uma operação fiscal sobre nota que existiu. Cancelar é grátis.
- Créditos de notas não expiram e não há mensalidade. Tabela completa em Preço.
Campos da nota
- Tomador: CNPJ ou CPF e razão social ou nome. Tomador do exterior usa
tomador_tipo: "exterior"e o país em ISO2 (ex.:SG). - Valor: em reais,
"1250,00"ou"1250.00". - Competência: mês do serviço,
AAAA-MM. Vazio vale o mês atual (horário de Brasília). - Discriminação: descrição do serviço como deve sair impressa, até 2.000 caracteres.
- Código de serviço: item da LC 116, ex.:
17.06(propaganda e publicidade, o aceito pelas plataformas de afiliados). Não é o CNAE.
Configuração fiscal por nota
O cadastro define o padrão, mas cada nota pode usar outro código de serviço, CNAE (7 dígitos), NBS, código de tributação municipal, alíquotas e tributos aproximados. A combinação usada fica congelada naquela emissão: mudar o padrão depois não altera a nota nem um reenvio.
As últimas 20 combinações usadas viram atalhos (configuracao_id) no painel, na API (GET /v1/configuracoes) e na IA (listar_configuracoes). A IA é instruída a perguntar quando houver mais de uma combinação possível, nunca a inventar código fiscal.
Cancelamento
Nota autorizada pode ser cancelada no painel, pela IA (cancelar_nota com confirmar=true) ou pela API. Motivos oficiais: 1 erro na emissão, 2 serviço não prestado, 4 duplicidade. O cancelamento vai para a SEFIN e fica registrado na conta.
MCP
Endereço: https://notas.dev/mcp, com OAuth (Claude, ChatGPT) ou header X-API-Key (Claude Code, Cursor, VS Code). Passo a passo por app em Conectar sua IA.
| Ferramenta | O que faz | Tipo |
|---|---|---|
emitir_nota | Prepara a NFS-e e devolve a prévia com um token de confirmação. Não emite nada. | prévia |
confirmar_emissao | Emite a nota da prévia depois do seu OK. O mesmo token nunca emite duas vezes. | fiscal |
consultar_nota | Situação de uma nota: status, número, chave de acesso e links do DANFSe e do XML. | leitura |
listar_notas | Histórico de notas, com filtro por status e competência. | leitura |
cancelar_nota | Cancela uma NFS-e autorizada, com motivo, só com confirmar=true. | fiscal |
listar_tomadores | Clientes salvos, com busca pelo nome ("acai" acha "Açaí & Cia"). | leitura |
salvar_tomador | Guarda um cliente frequente para não pedir o CNPJ de novo. | escrita |
listar_configuracoes | Combinações recentes de serviço, CNAE, NBS e tributação, para a IA não inventar código fiscal. | leitura |
saldo | Notas disponíveis, preço por nota, ambiente e teto diário. | leitura |
comprar_creditos | Gera o link de pagamento para adicionar notas. Você paga no navegador. | escrita |
Argumento inválido volta como erro argumentos_invalidos com o nome do campo, para a IA corrigir a chamada sozinha. Os links de DANFSe e XML abrem no navegador com a sessão do painel; a IA entrega o link, não o arquivo.
API REST /v1
Autenticação: Authorization: Bearer nmcp_… ou X-API-Key, com a chave gerada em Chaves de API. Respostas em JSON; erro sempre como {"error", "detail"} em português.
| Rota | O que faz |
|---|---|
POST /v1/notas | Emite direto. Header Idempotency-Key obrigatório (8 a 128 caracteres): repetir a mesma chave devolve a mesma resposta, nunca uma segunda nota. |
GET /v1/notas | Lista, com status, competencia, limite (até 100) e offset. |
GET /v1/notas/{id} | Situação de uma nota. |
POST /v1/notas/{id}/cancelar | Corpo {"motivo", "codigo_motivo"} (1, 2 ou 4). |
GET /v1/saldo | Notas disponíveis e preço. |
GET /v1/tomadores · POST /v1/tomadores | Lista e salva tomadores. |
GET /v1/configuracoes | Combinações fiscais recentes. |
curl -X POST https://notas.dev/v1/notas \
-H "Authorization: Bearer nmcp_..." \
-H "Idempotency-Key: pedido-123" \
-H "Content-Type: application/json" \
-d '{"tomador_doc":"11222333000181","tomador_razao":"Acme Digital LTDA",
"valor":"1250,00","discriminacao":"Gestão de tráfego - 09/2026",
"configuracao":{"codigo_servico":"17.06","codigo_cnae":"7490104"}}'
Códigos de erro
| HTTP | error | Quando |
|---|---|---|
| 400 | idempotency_key_obrigatoria | Falta o header ou ele é curto demais. |
| 400 | argumentos_invalidos | Campo com tipo ou tamanho errado; o detail diz qual. Nada é gravado na chave: corrija e repita. |
| 401 | unauthorized | Chave ausente, errada ou revogada. |
| 402 | saldo_insuficiente | Sem crédito para esta emissão. |
| 409 | sem_certificado | Nenhum certificado A1 cadastrado. |
| 409 | emissao_em_andamento | A mesma chave ainda está emitindo. Repita com a MESMA chave. |
| 422 | emissao_recusada | A SEFIN ou a prefeitura recusou; o motivo vem em detail. Não cobra. |
| 429 | teto_diario | Teto diário de emissões atingido. |
| 503 | emissor_indisponivel | Desfecho incerto. Repita com a MESMA chave: a reconciliação não cria outra nota. |
Ambiente
Produção. Toda nota emitida aqui é NFS-e válida, autorizada pela SEFIN Nacional, e consome 1 crédito de nota. Nota autorizada só se desfaz por cancelamento.
Suporte
Abra um chamado no suporte do notas.dev, dentro da sua conta, para acompanhar a conversa e as respostas da equipe.