Desenvolvedores
Integre a emissão de NFS-e no seu sistema.
Uma API REST com JSON, autenticação por header e a nota aprovada na resposta. Abaixo está o caminho completo, do primeiro cadastro à primeira nota, um guia para integrar com um agente de IA e o servidor MCP.
Como funciona
Do seu sistema à prefeitura.
Numa chamada só.
Uma chamada para emitir
O corpo leva uma lista de RPS. Cada RPS tem um id gerado por você, que funciona como chave de idempotência: se a conexão cair e você reenviar, a API devolve a nota que já foi emitida em vez de criar outra.
curl -X POST https://api.selfnotas.com.br/v1/nfse/emitir \
-H "Authorization: Bearer $SELFNOTAS_TOKEN" \
-H "x-company-id: $COMPANY_ID" \
-H "Content-Type: application/json" \
-d '{
"rps": [{
"id": "8f6c2b1e-4d3a-4c9b-a1e2-3f4d5c6b7a89",
"tomador": {
"cpf_cnpj": "98765432000110",
"razao_social": "Cliente Exemplo Comercio Ltda"
},
"servico": {
"valor_servicos": 180.00,
"aliquota": 5,
"item_lista_servico": "11.01",
"discriminacao": "Mensalidade de estacionamento",
"codigo_municipio": "3550308"
}
}]
}'
import { randomUUID } from "node:crypto";
const res = await fetch("https://api.selfnotas.com.br/v1/nfse/emitir", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.SELFNOTAS_TOKEN}`,
"x-company-id": process.env.COMPANY_ID,
"Content-Type": "application/json",
},
body: JSON.stringify({
rps: [{
id: randomUUID(), // chave de idempotência
tomador: { cpf_cnpj: "98765432000110", razao_social: "Cliente Exemplo Comercio Ltda" },
servico: {
valor_servicos: 180.0,
aliquota: 5,
item_lista_servico: "11.01",
discriminacao: "Mensalidade de estacionamento",
codigo_municipio: "3550308",
},
}],
}),
});
const { success, data } = await res.json();
const nota = data.notas[0]; // nota.pdf_nfse, nota.xml_nfse
import os, uuid, requests
res = requests.post(
"https://api.selfnotas.com.br/v1/nfse/emitir",
headers={
"Authorization": f"Bearer {os.environ['SELFNOTAS_TOKEN']}",
"x-company-id": os.environ["COMPANY_ID"],
},
json={
"rps": [{
"id": str(uuid.uuid4()), # chave de idempotência
"tomador": {"cpf_cnpj": "98765432000110", "razao_social": "Cliente Exemplo Comercio Ltda"},
"servico": {
"valor_servicos": 180.00,
"aliquota": 5,
"item_lista_servico": "11.01",
"discriminacao": "Mensalidade de estacionamento",
"codigo_municipio": "3550308",
},
}],
},
)
nota = res.json()["data"]["notas"][0] # nota["pdf_nfse"], nota["xml_nfse"]
<?php
$ch = curl_init("https://api.selfnotas.com.br/v1/nfse/emitir");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("SELFNOTAS_TOKEN"),
"x-company-id: " . getenv("COMPANY_ID"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"rps" => [[
"id" => "8f6c2b1e-4d3a-4c9b-a1e2-3f4d5c6b7a89", // chave de idempotência
"tomador" => ["cpf_cnpj" => "98765432000110", "razao_social" => "Cliente Exemplo Comercio Ltda"],
"servico" => [
"valor_servicos" => 180.00,
"aliquota" => 5,
"item_lista_servico" => "11.01",
"discriminacao" => "Mensalidade de estacionamento",
"codigo_municipio" => "3550308",
],
]],
]),
]);
$nota = json_decode(curl_exec($ch), true)["data"]["notas"][0];
{
"success": true,
"message": "1 nota(s) emitida(s) com sucesso",
"data": {
"notas": [{
"id": "019a8f2e-6c1d-7b3a-9f10-2d4e5a6b7c8d",
"numero": 412,
"serie": "1",
"status": "aprovado",
"chave": "3550308221234567800019…",
"pdf_nfse": "…/consultar/pdf/019a8f2e…",
"xml_nfse": "…/consultar/xml/019a8f2e…"
}],
"erros": [],
"sucesso": 1,
"falhas": 0
}
}
Antes da primeira nota
- Cadastre a empresa (CNPJ, endereço e inscrição municipal) em
POST /v1/empresas. - No mesmo cadastro, envie o certificado A1 em base64 e a senha.
- Vindo de outro emissor? Informe a série e o último número em
POST /v1/nfse/series.
Erros de validação voltam com HTTP 200 e "success": false. Confira sempre o campo success.
Integre usando IA
Escrevemos um guia em Markdown para agentes de código como Claude Code, Codex e Cursor. Ele tem autenticação, payloads, erros e os cuidados que o agente precisa tomar. Passe o link para o agente e peça a integração.
-
selfnotas.mdGuia completo para o agente. Pode salvar comoAGENTS.md(Codex) ouCLAUDE.md(Claude Code) na raiz do projeto. -
llms.txtÍndice curto com os links principais, no formato que ferramentas de IA procuram. -
selfnotas-mcpServidor MCP para o agente consultar notas e municípios direto na conversa. Instalação logo abaixo.
O guia manda o agente usar mocks nos testes, porque cada emissão aprovada gera uma nota fiscal válida.
Leia https://selfnotas.com.br/ai/selfnotas.md e integre a emissão de NFS-e da SelfNotas neste projeto.
- Credenciais nas variáveis SELFNOTAS_TOKEN e SELFNOTAS_COMPANY_ID.
- Gere um id (UUID) por RPS e guarde junto do pedido, para reenviar com o mesmo id em caso de falha.
- Salve id, número, chave e os links de PDF e XML da nota.
- Nos testes, use mock. Não chame /v1/nfse/emitir de verdade.
Servidor MCP
Com o selfnotas-mcp, agentes como Claude Code, Claude Desktop, Codex e Cursor consultam notas, links de PDF e XML, a série, a empresa e os requisitos de cada município direto na conversa. Roda na sua máquina com npx, sem instalar mais nada.
consultar_nfselinks_nfserequisitos_municipiobuscar_municipio_homologadoconsultar_seriesincronizar_serieconsultar_empresa
Começa só com consultas. emitir_nfse e cancelar_nfse só aparecem com SELFNOTAS_ALLOW_WRITE=true, porque cada emissão aprovada é uma nota fiscal válida.
claude mcp add selfnotas --scope user \
-e SELFNOTAS_TOKEN=seu_token \
-e SELFNOTAS_COMPANY_ID=sua_empresa \
-- npx -y selfnotas-mcp
codex mcp add selfnotas \
--env SELFNOTAS_TOKEN=seu_token \
--env SELFNOTAS_COMPANY_ID=sua_empresa \
-- npx -y selfnotas-mcp
{
"mcpServers": {
"selfnotas": {
"command": "npx",
"args": ["-y", "selfnotas-mcp"],
"env": {
"SELFNOTAS_TOKEN": "seu_token",
"SELFNOTAS_COMPANY_ID": "sua_empresa"
}
}
}
}
Pronto para emitir?
Crie a conta, cadastre a empresa e o certificado, e faça a primeira chamada.