NFS-e Nacional (LC 214/2025)

O novo padrão nacional de NFS-e entrou em produção em 05/01/2026 com validade jurídica. Substitui progressivamente os 5.570 sistemas municipais divergentes.

Grupos IBS/CBS

Em 2026, as validações dos grupos IBS/CBS estão temporariamente suspensas pela Nota Técnica 004 v2.0. Você pode emitir sem esses campos. A obrigatoriedade técnica plena vem em 2027 para Simples Nacional/MEI.

Emitir NFS-e Nacional

POST /api/v1/nfse-nacional
Authorization: Bearer {token}
Idempotency-Key: rps-2026-117

Idempotency-Key é opcional, mas use sempre em integração: retry com a mesma chave devolve a mesma nota autorizada, sem emitir de novo. Como este fluxo é síncrono, uma rejeição libera a chave — corrija e repita com a mesma. Detalhes em Idempotência.

{
  "numero": 1,
  "serie": "1",
  "tomador": {
    "cnpj": "00000000000000",
    "nome": "Cliente Exemplo",
    "email": "cliente@exemplo.com",
    "endereco": {
      "logradouro": "Av. Paulista", "numero": "1000",
      "bairro": "Bela Vista", "codigo_ibge": "3550308",
      "uf": "SP", "cep": "01310100"
    }
  },
  "servico": {
    "descricao": "Consultoria em tecnologia",
    "valor": 1500.00,
    "codigo_tributacao_nacional": "01.02",
    "codigo_nbs": "1.0201.00.00",
    "iss": { "aliquota": 0.05 }
  }
}

Resposta 201

{
  "sucesso": true,
  "id": "uuid",
  "chave": "3550308250200000000000181000000000001...",
  "numero_nfse": "000000001",
  "danfse_url": "https://www.nfse.gov.br/EmissorNacional/DANFSe/...",
  "valores": {
    "vServ": 1500.00, "vBC": 1500.00,
    "vIss": 75.00, "vLiq": 1500.00
  }
}

Cancelar NFS-e Nacional

POST /api/v1/nfse-nacional/{id}/cancelar

{
  "motivo_codigo": "1",
  "descricao": "Erro na emissão do documento fiscal"
}

Motivos disponíveis:

• 1 — Erro de emissão
• 2 — Serviço não prestado
• 3 — Duplicidade
• 9 — Outros

Substituir por nova DPS

Cancela a original e emite uma nova no mesmo ato.

POST /api/v1/nfse-nacional/{id}/substituir

{
  "numero": 2,
  "motivo": "Correção de valor e descrição",
  "tomador": { "cnpj": "00000000000000" },
  "servico": { "descricao": "Serviço corrigido", "valor": 2000.00 }
}

Sincronizar NFS-e recebidas

Útil quando sua empresa recebe serviços e precisa conciliar entradas.

POST /api/v1/nfse-nacional/sincronizar-dfe

Depois liste:

GET /api/v1/nfse-nacional/recebidas

Modo dual: Municipal × Nacional

Durante 2026, ambos padrões funcionam:

• NFS-e Municipal (legado): /api/v1/nfse → adapters SP/RJ/BH/Curitiba etc.
• NFS-e Nacional (novo): /api/v1/nfse-nacional → endpoint único federal

Configure por empresa com nfse_nacional_habilitado = true.

Série estritamente numérica

A partir de 01/01/2026, a série da DPS deve ser apenas numérica (^[0-9]+$). A API valida automaticamente.