# notas.dev: documentação completa > Emissão de NFS-e Nacional pela sua IA (MCP) ou por API REST. R$ 0,10 por nota autorizada, > sem mensalidade. Versão em HTML: https://notas.dev/docs ## Começando - Crie a conta em /login (https://notas.dev/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 (https://notas.dev/mcp)) 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 (https://notas.dev/precos). ## 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 (https://notas.dev/mcp). - 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 (https://notas.dev/app/chaves). 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 (https://notas.dev/app/suporte), dentro da sua conta, para acompanhar a conversa e as respostas da equipe.