Emitir NFS-e POST
Emite uma Nota Fiscal de Serviço eletrônica para o padrão nacional (DPS/ADN) ou para o layout homologado do município do prestador -- a CentralFiscal resolve automaticamente qual provedor/layout usar a partir do município.
Quando utilizar
Sempre que seu sistema precisar emitir uma nota de prestação de serviço em nome do contribuinte cadastrado. Cada chamada gera exatamente um documento -- para emitir várias notas, faça uma chamada por nota (a chave de idempotência evita duplicidade em caso de retry).
Pré-requisitos
- Contribuinte (prestador) já cadastrado --
POST /v1/contribuintes. - Certificado digital A1 vinculado ao contribuinte --
POST /v1/contribuintes/{id}/certificado-digital. - Tomador (cliente do prestador) já carregado, se possuir CPF/CNPJ --
POST /v1/contribuintes/{id}/tomadores. - Código do item da lista de serviços válido (LC 116/2003, formato
NN.NN).
Fluxo da operação
POST já transmite pra SEFIN/Ambiente Nacional e devolve o
resultado final -- não existe um "receber e processar depois" aqui.
A resposta já vem com status: AUTHORIZED (sucesso) ou REJECTED/
ERROR (falha) -- inclusive falha de validação de campo (ex.: faltou
servico.discriminacao) volta como 200 OK com status: ERROR,
não como 400. Ver Resposta de erro.
Endpoint
Headers
| Header | Valor | |
|---|---|---|
Authorization | Bearer <sua_api_key> | obrigatório |
Content-Type | application/json | obrigatório |
Idempotency-Key | string livre, definida por você | opcional -- alternativa ao campo idempotencia no corpo |
Body
Clique num campo com ▸ pra expandir.
Idempotency-Key.rps_numero, usa a série configurada na área do contribuinte (default "1").11AAAA-MM-DD).AAAA-MM-DD).POST .../tomadores.NN.NN.0.12 para 2%.pis/cofins/csll/ir/inss, cada um com base_calculo/aliquota/valor.cst/classificacao_tributaria) quando o prestador NÃO é optante do Simples Nacional nem MEI (que recolhem por fora, sem destacar IBS/CBS na DPS) -- se omitido nesse caso, a API preenche automaticamente com cst=000/classificacao_tributaria=000001 (tributação integral, sem benefício), em qualquer ambiente (homologação e produção). Informe este campo explicitamente se o serviço tiver uma classificação diferente da genérica.Lista de CST reduzida em relação à NF-e -- mostrando só os 7 códigos que têm ao menos 1 classificação tributária de serviço (nomenclatura NBS) na tabela nacional. Os demais (220/221/400/510/515/550/620/800/810/811/830) são exclusivos de mercadoria/ST/diferimento e não se aplicam a NFS-e.
reforma_tributaria). 1 Microempresa Municipal, 2 Estimativa, 3 Sociedade de Profissionais, 4 Cooperativa, 5 MEI, 6 ME/EPP.regime_especial_tributacao = 5 (MEI), deve ser true.servico/valores.Exemplo mínimo
Apenas os campos obrigatórios -- veja o código ao lado.
Exemplo completo
Com tomador, retenções e reforma tributária preenchidos -- veja o código ao lado.
Resposta de sucesso
200 OK -- síncrono, já com o resultado final da transmissão
(status: AUTHORIZED). Sem etapa de "consultar depois": numero_documento,
protocolo e o XML/DANFSe (em detalhes) já vêm nesta mesma resposta.
Resposta de erro
Dois formatos bem diferentes, dependendo de onde a falha acontece:
- Pré-requisito não atendido (contrato sem NFS-e, prestador não identificado, sem certificado ativo) --
400/403/409de verdade, antes de qualquer tentativa de emissão. - Falha de validação de campo ou rejeição do município (ex.: faltou
servico.discriminacao) -- a chamada retorna200 OKnormalmente, mas comstatus: "ERROR"e a mensagem real dentro demensagem/detalhes. Sempre confira o campostatus, não só o código HTTP.
Catálogo completo de erros: Tratamento de Erros.
Próximos passos
- Já com o resultado na mesma resposta, normalmente não é preciso consultar de novo -- mas
GET /v1/nfse/emissoes/{emissao_id}continua disponível pra reconsulta. - Baixar o XML e o DANFSe usando as URLs em
detalhes. - Se precisar corrigir/cancelar, ver
POST /v1/nfse/cancelamentosabaixo.
Cancelamento
POST /v1/nfse/cancelamentos -- exige motivo/justificativa
com pelo menos 15 caracteres. O jeito mais simples é informar emissao_id (o
transmissao_id retornado na emissão) -- a API busca sozinha o número, série e
código de verificação da nota original. Sem emissao_id, informe
numero_nfse/serie/codigo_verificacao manualmente. Veja
o exemplo ao lado.
Outros eventos
Exclusivos do Ambiente Nacional (Padrão Nacional) -- não existem no layout
de provedores municipais legados (Ginfes, Giss, IPM, etc.), que retornam erro de negócio
claro se você tentar usá-los fora do Padrão Nacional. Assim como no cancelamento, informar
emissao_id resolve sozinho a chave de acesso da nota original.
POST /v1/nfse/substituicoes-- evento e105102 (Cancelamento de NFS-e por Substituição). Cancela a NFS-e original vinculando a chave de uma NFS-e substituta que já precisa ter sido emitida antes desta chamada. Exigechave_substituta(chave de acesso da nota substituta) ecodigo_motivo_substituicao(01Desenquadramento do Simples,02Enquadramento no Simples,03Inclusão retroativa de imunidade/isenção,04Exclusão retroativa de imunidade/isenção,05Rejeição pelo tomador/intermediário,99Outros).POST /v1/nfse/confirmacoes-prestador-- evento e202201 (Manifestação de NFS-e - Confirmação do Prestador). O evento mais simples: só precisa da chave de acesso da nota, sem motivo nem observação.POST /v1/nfse/rejeicoes-prestador-- evento e202205 (Manifestação de NFS-e - Rejeição do Prestador). Exigecodigo_motivo_rejeicao(1Duplicidade,2NFS-e já emitida pelo tomador,3Não ocorrência do fato gerador,4Erro de responsabilidade tributária,5Erro de valor/serviço/data,9Outros).
GET
/v1/nfse/substituicoes/{transmissao_id}, GET
/v1/nfse/confirmacoes-prestador/{transmissao_id} ou GET
/v1/nfse/rejeicoes-prestador/{transmissao_id} (mesmo transmissao_id
devolvido na resposta de criação).
Eventos como Tomador/Intermediário
Assim como os eventos do prestador, exclusivos do Ambiente Nacional (Padrão
Nacional). O "autor" da manifestação é sempre a identidade fiscal do seu próprio
contribuinte (a mesma usada em prestador_documento nos outros endpoints) -- a
API não valida se esse CNPJ é de fato o tomador/intermediário identificado dentro da NFS-e de
terceiro, porque não há acesso ao XML original emitido pelo prestador pra conferir; a
responsabilidade de mandar o evento certo é de quem chama a API.
Como tomador -- use quando seu contribuinte contratou/recebeu um serviço de outra empresa e precisa se manifestar sobre a NFS-e recebida:
POST /v1/nfse/confirmacoes-tomador-- evento e203202 (Manifestação de NFS-e - Confirmação do Tomador). Só precisa da chave de acesso da nota recebida, sem motivo nem observação.POST /v1/nfse/rejeicoes-tomador-- evento e203206 (Manifestação de NFS-e - Rejeição do Tomador). Exigecodigo_motivo_rejeicao(mesmos códigos1a5/9de Rejeição do Prestador).
Como intermediário -- use quando seu contribuinte atuou como plataforma/marketplace intermediando a prestação de serviço de um terceiro (nem prestador, nem tomador):
POST /v1/nfse/confirmacoes-intermediario-- evento e204203 (Manifestação de NFS-e - Confirmação do Intermediário). Só precisa da chave de acesso da nota, sem motivo nem observação.POST /v1/nfse/rejeicoes-intermediario-- evento e204207 (Manifestação de NFS-e - Rejeição do Intermediário). Exigecodigo_motivo_rejeicao(mesmos códigos1a5/9).
GET
/v1/nfse/confirmacoes-tomador/{transmissao_id}, GET
/v1/nfse/rejeicoes-tomador/{transmissao_id}, GET
/v1/nfse/confirmacoes-intermediario/{transmissao_id} ou GET
/v1/nfse/rejeicoes-intermediario/{transmissao_id} (mesmo
transmissao_id devolvido na resposta de criação).
tiposEventos_v1.01.xsd) define 16 eventos ao todo; além de Cancelamento e
dos 7 acima (Substituição, Confirmação/Rejeição do Prestador, do Tomador e do
Intermediário), faltam apenas eventos exclusivos do fisco municipal: Anulação da
Rejeição, Confirmação Tácita (gerada automaticamente pelo sistema, não pela API) e os
eventos administrativos (Cancelamento Deferido/Indeferido por Análise Fiscal,
Cancelamento/Bloqueio/Desbloqueio por Ofício) -- esses nunca seriam emitidos pela API de
qualquer forma, são notificações que chegam do município.