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ó.

Seu sistema API REST Agente de IA valida e numera assina e envia S SEFIN Nacional Prefeituras PDF e XML na resposta
2.068municípios homologados
27 UFstodos os estados e o DF
Síncronaa nota volta na mesma chamada

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.

Requisição
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"
      }
    }]
  }'
Resposta200
{
  "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

  1. Cadastre a empresa (CNPJ, endereço e inscrição municipal) em POST /v1/empresas.
  2. No mesmo cadastro, envie o certificado A1 em base64 e a senha.
  3. 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.md Guia completo para o agente. Pode salvar como AGENTS.md (Codex) ou CLAUDE.md (Claude Code) na raiz do projeto.
  • llms.txt Índice curto com os links principais, no formato que ferramentas de IA procuram.
  • selfnotas-mcp Servidor 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.

Prompt
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.

npm · selfnotas-mcp

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_nfse
  • links_nfse
  • requisitos_municipio
  • buscar_municipio_homologado
  • consultar_serie
  • sincronizar_serie
  • consultar_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.

Ver no npm
Instalar
claude mcp add selfnotas --scope user \
  -e SELFNOTAS_TOKEN=seu_token \
  -e SELFNOTAS_COMPANY_ID=sua_empresa \
  -- npx -y selfnotas-mcp

Pronto para emitir?

Crie a conta, cadastre a empresa e o certificado, e faça a primeira chamada.