Guia de início rápido

A Simplifisca API emite NF-e (modelo 55) e NFS-e no Padrão Nacional a partir de um JSON simples. Você não precisa montar XML, assinar com o certificado nem falar com a SEFAZ: a API cuida disso, processa em fila e avisa o resultado por webhook.

Todas as requisições usam a URL base abaixo, sempre via HTTPS:

https://app.simplifisca.com.br/api/v1

• Corpo das requisições e respostas em JSON (UTF-8), com Content-Type: application/json.
• Nomes de campos em camelCase (ex.: razaoSocial, chaveAcesso).
• Datas em ISO 8601 com fuso horário (ex.: 2026-10-09T14:03:11-03:00).
• Valores monetários nas respostas vêm como string decimal (ex.: "119.80").

Este guia cobre o essencial para colocar a emissão no ar. Todos os campos, schemas e respostas estão na referência completa da API, gerada a partir do OpenAPI em /api/v1/openapi.json.

Autentique cada requisição com sua chave de API no header Authorization, no formato Bearer:

Authorization: Bearer sf_live_...

Gere as chaves no painel em Painel → Chaves de API (em /painel/). A chave completa é exibida uma única vez, no momento da criação — guarde-a num gerenciador de segredos ou em variável de ambiente. Se perder, revogue e gere outra.

curl https://app.simplifisca.com.br/api/v1/conta \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY"

O ambiente é definido por emitente, no campo ambiente:

Comece em homologação, valide o fluxo completo (emissão, webhook, cancelamento) e depois troque o emitente para produção com um PATCH /api/v1/emitentes/{id}.

A Simplifisca expõe um servidor MCP (Model Context Protocol) para que agentes como Claude Code, Cursor e Windsurf emitam, consultem e cancelem notas como ferramentas nativas — e usem a própria API para te ajudar a integrar.

Claude Code

claude mcp add --transport http simplifisca https://app.simplifisca.com.br/mcp \
  --header "Authorization: Bearer sf_live_SUA_CHAVE"

Cursor

Crie ou edite .cursor/mcp.json na raiz do projeto (ou ~/.cursor/mcp.json para todos os projetos):

{
  "mcpServers": {
    "simplifisca": {
      "url": "https://app.simplifisca.com.br/mcp",
      "headers": {
        "Authorization": "Bearer sf_live_SUA_CHAVE"
      }
    }
  }
}

Windsurf

Adicione em ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "simplifisca": {
      "serverUrl": "https://app.simplifisca.com.br/mcp",
      "headers": {
        "Authorization": "Bearer sf_live_SUA_CHAVE"
      }
    }
  }
}

Outros clientes funcionam desde que suportem MCP remoto via Streamable HTTP com headers personalizados.

Ferramentas expostas (13)

Publicamos a documentação em Markdown, no formato llms.txt, para você colar no contexto do agente ou deixá-lo buscar sozinho:

Em ferramentas como Lovable, Bolt e v0, que geram código mas nem sempre suportam MCP, o llms-full.txt é o caminho mais rápido: peça ao agente para ler o arquivo antes de escrever a integração.

Cole no Cursor, Claude Code, Lovable, Bolt ou na ferramenta de sua preferência. Ajuste o gatilho (pagamento confirmado) ao seu produto:

Antes de rodar o prompt: crie a chave de API, cadastre o emitente com o certificado A1 e defina SIMPLIFISCA_API_KEY no ambiente do projeto.

O emitente é a empresa (CNPJ) que emite as notas. Uma conta pode ter vários emitentes, cada um com seu certificado, ambiente e numeração de série.

1. Cadastrar o emitente

curl -X POST https://app.simplifisca.com.br/api/v1/emitentes \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @emitente.json

{
  "cnpj": "11222333000181",
  "razaoSocial": "Minha Empresa LTDA",
  "nomeFantasia": "Minha Empresa",
  "inscricaoEstadual": "123456789",
  "inscricaoMunicipal": "12345",
  "regimeTributario": 1,
  "ambiente": "homologacao",
  "endereco": {
    "logradouro": "Rua das Flores",
    "numero": "100",
    "complemento": "Sala 2",
    "bairro": "Centro",
    "codigoMunicipio": "3550308",
    "municipio": "São Paulo",
    "uf": "SP",
    "cep": "01001000"
  },
  "email": "fiscal@minhaempresa.com.br",
  "telefone": "11999999999",
  "nfe": { "serie": "1", "proximoNumero": 1 },
  "nfse": { "serie": "1", "proximoNumero": 1 }
}

O campo regimeTributario é o CRT da NF-e:

codigoMunicipio é o código IBGE de 7 dígitos. Os blocos nfe e nfse definem a série e o próximo número a ser usado em cada tipo de documento.

2. Enviar o certificado A1

Envie o arquivo .pfx codificado em Base64 e a senha do certificado. Ele é armazenado criptografado e usado apenas para assinar os documentos desse emitente.

CERT_B64=$(base64 < certificado.pfx | tr -d '\n')

curl -X PUT https://app.simplifisca.com.br/api/v1/emitentes/$EMITENTE_ID/certificado \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"arquivoBase64\": \"$CERT_B64\", \"senha\": \"senha-do-certificado\"}"

{
  "arquivoBase64": "MIIKpAIBAzCCCm4GCSqGSIb3DQEHAaCCCl8Egg...",
  "senha": "senha-do-certificado"
}

Endpoints

• POST/api/v1/emitentesCadastrar emitente
• GET/api/v1/emitentesListar emitentes
• GET/api/v1/emitentes/{id}Detalhar emitente
• PATCH/api/v1/emitentes/{id}Atualizar campos (ex.: ambiente)
• DELETE/api/v1/emitentes/{id}Remover emitente
• PUT/api/v1/emitentes/{id}/certificadoEnviar ou substituir certificado A1

O catálogo fiscal guarda seus produtos (NF-e) e serviços (NFS-e) com a tributação já configurada — NCM, CFOP, impostos, código de tributação nacional, NBS, ISS e valor. Configure uma vez (o seu contador pode fazer isso direto no painel, ou você via API) e a nota passa a precisar só do código.

O codigo é o identificador do seu sistema (SKU, slug do plano etc.) e é único por conta. PUT funciona como upsert: cria se não existir, substitui se existir — ideal para sincronizar o catálogo a partir do seu código.

Produto (NF-e)

curl -X PUT https://app.simplifisca.com.br/api/v1/produtos/SKU-001 \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @produto.json

{
  "codigo": "SKU-001",
  "descricao": "Camiseta básica",
  "ncm": "61091000",
  "cfop": "5102",
  "unidade": "UN",
  "valorUnitario": 59.90,
  "impostos": {
    "icms": { "origem": 0, "csosn": "102" },
    "pis": { "cst": "07" },
    "cofins": { "cst": "07" }
  }
}

Serviço (NFS-e)

curl -X PUT https://app.simplifisca.com.br/api/v1/servicos/PLANO-PRO \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @servico.json

{
  "codigo": "PLANO-PRO",
  "descricao": "Assinatura mensal do plano Pro (software como serviço)",
  "codigoTributacaoNacional": "010501",
  "codigoNbs": "115013000",
  "aliquotaIss": 2.0,
  "valor": 99.90
}

Emitindo com o catálogo

Na NF-e, troque os campos do item por produto (o código do catálogo) e a quantidade. Na NFS-e, envie só servico.codigo; valores.servico é opcional quando o serviço do catálogo tem valor.

"itens": [
  { "produto": "SKU-001", "quantidade": 2 }
]

"servico": { "codigo": "PLANO-PRO" }

Endpoints

• GET/api/v1/produtosListar produtos
• POST/api/v1/produtosCadastrar produto
• GET/api/v1/produtos/{codigo}Detalhar produto
• PUT/api/v1/produtos/{codigo}Criar ou substituir (upsert)
• PATCH/api/v1/produtos/{codigo}Atualizar campos
• DELETE/api/v1/produtos/{codigo}Remover produto
• GET/api/v1/servicosListar serviços
• POST/api/v1/servicosCadastrar serviço
• GET/api/v1/servicos/{codigo}Detalhar serviço
• PUT/api/v1/servicos/{codigo}Criar ou substituir (upsert)
• PATCH/api/v1/servicos/{codigo}Atualizar campos
• DELETE/api/v1/servicos/{codigo}Remover serviço

Envie a nota para POST /api/v1/nfe. O campo emitente aceita o id (UUID) ou o CNPJ do emitente. Use referencia para guardar o identificador do seu sistema (pedido, fatura etc.).

curl -X POST https://app.simplifisca.com.br/api/v1/nfe \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042" \
  -d @nfe.json

{
  "emitente": "11222333000181",
  "referencia": "pedido-1042",
  "naturezaOperacao": "Venda de mercadoria",
  "destinatario": {
    "cpfCnpj": "99888777000100",
    "nome": "Cliente Exemplo LTDA",
    "email": "compras@cliente.com.br",
    "indicadorIe": 9,
    "endereco": {
      "logradouro": "Av. Brasil",
      "numero": "500",
      "bairro": "Jardins",
      "codigoMunicipio": "3550308",
      "municipio": "São Paulo",
      "uf": "SP",
      "cep": "01430000"
    }
  },
  "itens": [
    {
      "codigo": "SKU-001",
      "descricao": "Camiseta básica",
      "ncm": "61091000",
      "cfop": "5102",
      "unidade": "UN",
      "quantidade": 2,
      "valorUnitario": 59.90,
      "impostos": {
        "icms": { "origem": 0, "csosn": "102" },
        "pis": { "cst": "07" },
        "cofins": { "cst": "07" }
      }
    }
  ],
  "pagamentos": [
    { "forma": "17", "valor": 119.80 }
  ]
}

Com o catálogo fiscal, cada item pode ser só {"produto": "SKU-001", "quantidade": 2} em vez dos campos completos (codigo, ncm, cfop, impostos...). Campos enviados no item sobrescrevem o catálogo.

Para regime normal, troque csosn por cst no bloco icms e informe as alíquotas correspondentes. Veja todos os campos de imposto na referência.

A emissão é assíncrona: a API valida o payload, coloca a nota na fila e responde imediatamente com 202 Accepted e status processando.

{
  "id": "8f3c2a1e-...",
  "tipo": "nfe",
  "status": "processando",
  "ambiente": "homologacao",
  "referencia": "pedido-1042",
  "emitente": { "id": "...", "cnpj": "11222333000181" },
  "numero": null,
  "serie": "1",
  "chaveAcesso": null,
  "protocolo": null,
  "valorTotal": "119.80",
  "sefaz": { "codigo": null, "mensagem": null },
  "criadoEm": "2026-10-09T14:03:11-03:00",
  "autorizadoEm": null,
  "canceladoEm": null,
  "links": { "self": "/api/v1/nfe/8f3c...", "xml": null, "pdf": null }
}

Consultar, baixar e cancelar

Acompanhe o resultado pelo webhook (recomendado) ou consultando a nota. Depois de autorizada, links.xml e links.pdf apontam para o XML autorizado e o DANFE.

curl https://app.simplifisca.com.br/api/v1/nfe/$NFE_ID \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY"

curl -o nota.xml https://app.simplifisca.com.br/api/v1/nfe/$NFE_ID/xml \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY"

curl -o danfe.pdf https://app.simplifisca.com.br/api/v1/nfe/$NFE_ID/pdf \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY"

Para cancelar uma nota autorizada, envie uma justificativa com no mínimo 15 caracteres. A resposta é 202 com status cancelando; o resultado chega pelo webhook nfe.cancelada.

curl -X POST https://app.simplifisca.com.br/api/v1/nfe/$NFE_ID/cancelamento \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"justificativa": "Pedido cancelado pelo cliente antes do envio"}'

Liste notas com filtros por status, referência, emitente e paginação:

curl "https://app.simplifisca.com.br/api/v1/nfe?status=autorizada&referencia=pedido-1042&emitente=11222333000181&pagina=1" \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY"

Endpoints

• POST/api/v1/nfeEmitir NF-e
• GET/api/v1/nfeListar (status, referencia, emitente, pagina)
• GET/api/v1/nfe/{id}Consultar
• GET/api/v1/nfe/{id}/xmlXML autorizado
• GET/api/v1/nfe/{id}/pdfDANFE em PDF
• POST/api/v1/nfe/{id}/cancelamentoCancelar

A NFS-e segue o Padrão Nacional (DPS) e funciona para municípios aderentes. O fluxo é o mesmo da NF-e: resposta 202 com status processando e resultado por webhook.

curl -X POST https://app.simplifisca.com.br/api/v1/nfse \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: os-778" \
  -d @nfse.json

{
  "emitente": "11222333000181",
  "referencia": "os-778",
  "tomador": {
    "cpfCnpj": "12345678909",
    "nome": "Fulano de Tal",
    "email": "fulano@email.com",
    "endereco": {
      "logradouro": "Rua A",
      "numero": "10",
      "bairro": "Centro",
      "codigoMunicipio": "3550308",
      "uf": "SP",
      "cep": "01001000"
    }
  },
  "servico": {
    "descricao": "Desenvolvimento de software sob encomenda",
    "codigoTributacaoNacional": "010101",
    "codigoNbs": "115021000"
  },
  "valores": {
    "servico": 1500.00,
    "aliquotaIss": 2.0,
    "issRetido": false
  }
}

codigoTributacaoNacional é o código de tributação nacional do serviço e codigoNbs o código da Nomenclatura Brasileira de Serviços. Confirme os códigos corretos com o seu contador.

Se o serviço estiver no catálogo fiscal, basta "servico": {"codigo": "PLANO-PRO"} no lugar de descrição e códigos — e valores.servico fica opcional quando o catálogo tem valor.

• POST/api/v1/nfseEmitir NFS-e
• GET/api/v1/nfseListar (status, referencia, emitente, pagina)
• GET/api/v1/nfse/{id}Consultar
• GET/api/v1/nfse/{id}/xmlXML autorizado
• GET/api/v1/nfse/{id}/pdfDANFSe em PDF
• POST/api/v1/nfse/{id}/cancelamentoCancelar (justificativa com 15+ caracteres)

Toda NF-e e NFS-e passa pelos mesmos status:

Rede cai, timeout estoura, job roda duas vezes. Para nunca emitir a mesma nota em duplicidade, envie o header Idempotency-Key (até 100 caracteres) nas requisições de emissão.

Idempotency-Key: pagamento_7f2a91

Se você repetir a requisição com a mesma chave, a API não cria outro documento: retorna o documento já existente com status 200 (em vez de 202). Use um identificador estável do seu sistema, como o id do pagamento ou do pedido.

Webhooks avisam seu sistema quando uma nota muda de status — sem polling. Cadastre a URL que vai receber os eventos:

curl -X POST https://app.simplifisca.com.br/api/v1/webhooks \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-saas.com.br/webhooks/simplifisca",
    "eventos": ["nfe.autorizada", "nfe.rejeitada", "nfe.erro", "nfe.cancelada"]
  }'

A resposta inclui o campo segredo (formato whsec_...), usado para verificar as assinaturas. Ele é retornado apenas na criação — guarde-o com segurança.

Eventos

Formato da entrega

Cada evento é um POST JSON para a sua URL. Em dados vem o documento completo, no mesmo formato de GET /api/v1/nfe/{id}.

{
  "id": "evt_3b9d1c7a...",
  "evento": "nfe.autorizada",
  "criadoEm": "2026-10-09T14:03:19-03:00",
  "dados": {
    "id": "8f3c2a1e-...",
    "tipo": "nfe",
    "status": "autorizada",
    "chaveAcesso": "35261011222333000181550010000000011000000010",
    "links": {
      "self": "/api/v1/nfe/8f3c...",
      "xml": "/api/v1/nfe/8f3c.../xml",
      "pdf": "/api/v1/nfe/8f3c.../pdf"
    }
  }
}

Verificando a assinatura

Toda entrega traz o header:

X-Simplifisca-Assinatura: t=1730000000,v1=<hex>

t é o timestamp Unix do envio e v1 é o HMAC-SHA256, em hexadecimal, calculado com o seu segredo sobre a string {t}.{corpo_bruto}. Calcule o mesmo HMAC usando o corpo bruto (antes de fazer parse do JSON), compare em tempo constante e, de preferência, rejeite timestamps muito antigos.

import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SEGREDO = os.environ["SIMPLIFISCA_WEBHOOK_SECRET"]  # whsec_...


def assinatura_valida(corpo: bytes, cabecalho: str, tolerancia: int = 300) -> bool:
    try:
        partes = dict(item.split("=", 1) for item in cabecalho.split(","))
        t, v1 = partes["t"], partes["v1"]
        if abs(time.time() - int(t)) > tolerancia:
            return False
    except (KeyError, ValueError):
        return False
    mensagem = f"{t}.".encode() + corpo
    esperado = hmac.new(SEGREDO.encode(), mensagem, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, v1)


@app.post("/webhooks/simplifisca")
def webhook_simplifisca():
    corpo = request.get_data()  # corpo bruto, antes de qualquer parse
    cabecalho = request.headers.get("X-Simplifisca-Assinatura", "")
    if not assinatura_valida(corpo, cabecalho):
        abort(400)

    evento = request.get_json()
    if evento["evento"] == "nfe.autorizada":
        nota = evento["dados"]
        # salve nota["chaveAcesso"], nota["links"]["xml"] e nota["links"]["pdf"]
    return "", 200

import crypto from "node:crypto";
import express from "express";

const app = express();
const SEGREDO = process.env.SIMPLIFISCA_WEBHOOK_SECRET; // whsec_...

function assinaturaValida(corpo, cabecalho, tolerancia = 300) {
  const partes = Object.fromEntries(
    (cabecalho || "").split(",").map((item) => item.split("=", 2))
  );
  const { t, v1 } = partes;
  if (!t || !v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > tolerancia) return false;

  const esperado = crypto
    .createHmac("sha256", SEGREDO)
    .update(`${t}.`)
    .update(corpo)
    .digest("hex");
  const a = Buffer.from(esperado);
  const b = Buffer.from(v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post(
  "/webhooks/simplifisca",
  express.raw({ type: "application/json" }), // mantém o corpo bruto
  (req, res) => {
    if (!assinaturaValida(req.body, req.get("X-Simplifisca-Assinatura"))) {
      return res.sendStatus(400);
    }
    const evento = JSON.parse(req.body.toString("utf8"));
    if (evento.evento === "nfe.autorizada") {
      // salve evento.dados.chaveAcesso e evento.dados.links
    }
    res.sendStatus(200);
  }
);

Retentativas

Responda com qualquer status 2xx em até 10 segundos. Se a resposta não for 2xx (ou demorar mais), a entrega é reenviada com backoff, até 8 vezes. Por isso:

• Responda rápido e processe o evento de forma assíncrona, se for pesado.
• Trate entregas repetidas: use o id do evento (evt_...) para ignorar duplicatas.

Erros usam códigos HTTP padrão e um corpo com formato fixo. Em erros de validação, detalhes aponta o campo exato:

{
  "erro": {
    "codigo": "validacao",
    "mensagem": "Dados inválidos.",
    "detalhes": [
      { "campo": "itens.0.ncm", "mensagem": "NCM deve ter 8 dígitos." }
    ],
    "requestId": "req_3f9a1c7e2b8d4a6051c0e9f2"
  }
}

Toda resposta da API — de sucesso ou de erro — traz o header X-Request-Id, e os erros repetem o mesmo valor em erro.requestId. Registre-o nos seus logs.

• Taxa: 120 requisições por minuto por chave de API. Acima disso a API responde 429 limite_requisicoes; aguarde e tente novamente com backoff.
• Notas: cada plano tem um limite mensal de notas em produção. Homologação é ilimitada. Ao atingir o limite, novas emissões em produção retornam 402 limite_plano.

Consulte o plano atual e o uso do mês a qualquer momento:

curl https://app.simplifisca.com.br/api/v1/conta \
  -H "Authorization: Bearer $SIMPLIFISCA_API_KEY"

O formato completo da resposta está na referência da API.