Emitindo NFS-e pelo motor próprio do Padrão Nacional

POST /v1/nfse-nacional/emitir

As rotas /v1/nfse-nacional emitem no Padrão Nacional pelo motor próprio do Conota. A DPS é montada e conferida contra o XSD oficial antes de ir para a Sefin, e cada erro volta com o caminho exato do campo.

Use este caminho quando precisar de um leiaute que POST /v1/nfse/emitir ainda não aceita, como os da NT 009. A rota POST /v1/nfse/emitir continua funcionando como antes.

A estrutura completa do payload está na Referência da API — esta página trata do fluxo e das decisões, não do schema.

Rotas

Operação	Rota	Consome cota
Emitir	POST /v1/nfse-nacional/emitir	sim
Emitir NFS-e de condomínio (NT 009)	POST /v1/nfse-nacional/condominios/emitir	sim
Validar sem emitir	POST /v1/nfse-nacional/validar	não

As emissões devolvem 202 com job_id. Consulta, arquivos e cancelamento usam as rotas de sempre: Consultar emissão, Arquivos e Cancelamento.

Forma da chamada

{
  "cpf_cnpj": "11222333000181",
  "referencia_externa": "pedido_98231",
  "versao": "1.01",
  "nota": {
    "infDPS": {
      "toma": { "CPF": "11144477735", "xNome": "Cliente Exemplo" },
      "serv": {
        "locPrest": { "cLocPrestacao": "3106200" },
        "cServ": { "cTribNac": "010101", "xDescServ": "Desenvolvimento de sistemas", "cNBS": "115021000" }
      },
      "valores": {
        "vServPrest": { "vServ": 1500.00 },
        "trib": { "tribMun": { "tribISSQN": "1", "tpRetISSQN": "1", "pAliq": 2.00 }, "totTrib": { "indTotTrib": "0" } }
      },
      "IBSCBS": {
        "finNFSe": "0", "cIndOp": "100301", "indDest": "0",
        "valores": { "trib": { "gIBSCBS": { "CST": "000", "cClassTrib": "000001" } } }
      }
    }
  }
}

Você não precisa informar o que já está no cadastro da empresa. Quando omitidos, o Conota preenche:

• prestador: CNPJ ou CPF, inscrição municipal e regime tributário (regTrib);
• cLocEmi, tpAmb, dhEmi e dCompet;
• serie e nDPS, a partir da numeração da empresa no ambiente da chave.

Para não enviar a inscrição municipal, informe "IM": null em prest.

Escolha do leiaute

O campo versao define o leiaute da DPS:

versao	Leiaute	Quando usar
1.01	XSD oficial de 09/02/2026	padrão, quando versao é omitido
1.01-20261020	XSD oficial de 20/10/2026, com parte da NT 009	homologação, até a Sefin adotar o novo XSD em produção
1.01-nt009	leiaute completo da NT 009, com condomínios	NFS-e de condomínio; provisório até a publicação do XSD oficial

Um valor fora da lista é recusado na hora, com 400.

O leiaute muda a posição dos campos

O mesmo JSON não serve para todos os leiautes. Um campo enviado na posição de outro leiaute é recusado com campo não existe no leiaute, e nada é enviado à Sefin. Valide o payload no leiaute escolhido antes de emitir.

O que muda no leiaute 1.01-20261020

• finNFSe sai de IBSCBS e vai para infDPS. Passa a ser obrigatório.
• CST e cClassTrib sobem de IBSCBS.valores.trib.gIBSCBS para IBSCBS.valores.trib. O gIBSCBS fica opcional e guarda só cCredPres, gTribRegular e gDif.
• cIndOp passa a ser opcional.
• A dedução/redução (gDedRed) e o reembolso (gReeRepRes) dão lugar ao ajuste da base de cálculo (gAjusteBC).
• Novos grupos: IBSCBS.imovel.gLocacao (locação, cessão e arrendamento), IBSCBS.imovel.gUnidImob (unidades imobiliárias) e IBSCBS.bensMoveis.

O exemplo acima, no leiaute 1.01-20261020, fica assim:

{
  "versao": "1.01-20261020",
  "nota": {
    "infDPS": {
      "finNFSe": "0",
      "IBSCBS": {
        "cIndOp": "100301", "indDest": "0",
        "valores": { "trib": { "CST": "000", "cClassTrib": "000001" } }
      }
    }
  }
}

Os demais campos não mudam.

Valide antes de emitir

curl -X POST https://api.conota.dev/v1/nfse-nacional/validar \
  -H "X-API-Key: $CONOTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @dps.json

A validação monta a DPS exatamente como a emissão montaria, sem assinar, enviar, consumir cota ou reservar número.

• 200 com "sucesso": true: a DPS passou no XSD e nas regras. O XML gerado vem em xml.
• 422: a DPS tem problemas. Cada erro vem com o caminho do campo, em erros (montagem), erros_xsd (XSD oficial) ou erros_regras (regras de condomínio).

Use o mesmo versao que você vai usar na emissão.

A validação não substitui a Sefin

O XSD confere a forma da DPS. Regras de negócio, como cadastro do município e códigos de serviço, só a Sefin confere. Veja as rejeições mais comuns abaixo.

Rejeições comuns da Sefin

Código	O que significa	O que fazer
E0234	o endereço do tomador é obrigatório para o cIndOp informado	informe toma.end
E0322	com IBS/CBS, a DPS precisa do código NBS	informe serv.cServ.cNBS
E0120	o município não tem dados do prestador no cadastro nacional, e a inscrição municipal não deve ir	envie "IM": null em prest
E0312	o município de incidência não administra o cTribNac na competência	confirme o código de serviço com o município

Os códigos cNBS, cIndOp e cClassTrib de cada serviço estão na tabela de correlação oficial do Portal Nacional da NFS-e (Anexo VIII da NT 004).

Rejeições da Sefin são definitivas: o Conota não tenta de novo. Corrija o payload e emita outra vez com outra referencia_externa.

Número da DPS já usado

O número da DPS (nDPS) é único por município, prestador e série. Se a Sefin informar que o número já existe, o Conota busca a NFS-e que ela tem para ele:

• se for a mesma operação (por exemplo, um retorno que se perdeu), a emissão é dada como concluída com essa nota;
• se for outra operação, a emissão termina com o erro DPS_DIVERGENTE, com a chave da nota existente e os campos que divergem.

DPS_DIVERGENTE pede ajuste de numeração

Esse erro aparece quando o número já foi usado por outro sistema ou outra integração. Ajuste a numeração da empresa antes de emitir de novo. Ver a numeração atual em GET /v1/empresas/numeracao.

Condomínios

POST /v1/nfse-nacional/condominios/emitir

Para o subitem 99.05 (cTribNac 990501), no leiaute da NT 009. Além do XSD, o Conota confere as regras da NT antes do envio:

• vServ igual à soma das cobranças;
• descontos batendo com vDescCondIncond;
• tipo de cobrança sem repetição;
• grupo do imóvel presente.

O leiaute da NT 009 ainda é provisório, montado a partir da planilha oficial até a publicação do XSD. Quando o XSD sair, o Conota passa a usá-lo e esta página é atualizada.