Referência da API › Notas
Emitir nota
Envia a NFS-e ao governo e devolve a nota autorizada ou o motivo da recusa.
/api/v1/notasUse para emitir uma nota fiscal de serviço por uma empresa que já está pronta para emitir (veja Consultar situação). A notem monta a nota com o serviço e o tomador cadastrados ou informados no pedido, envia ao governo e espera a resposta por até cerca de 20 segundos.
Antes de gerar o número da nota, a notem confere a empresa, o serviço, o tomador e os tributos. Se algo estiver errado, a resposta é 422 com o campo e o motivo, e nenhum número é usado. Por exemplo, o tomador não pode ter o mesmo CPF/CNPJ da empresa (E0202 — o CPF/CNPJ do tomador é igual ao da empresa emitente), e ISS retido pelo tomador exige CPF/CNPJ e endereço completo no Brasil (E0204 e E0237). Todas as recusas do governo, com o que fazer em cada uma, estão em Rejeições do governo.
O que esperar: 201 com a nota autorizada; 422 REJEITADO_GOVERNO quando o governo recusa, com o motivo original e uma explicação em português; 202 quando o governo não respondeu a tempo. No caso do 202, a nota fica em verificação, a notem descobre o resultado sozinha e avisa por webhook (nota.autorizada ou nota.rejeitada).
O cabeçalho Idempotency-Key é obrigatório e evita nota duplicada. Se a conexão cair e você não souber se a nota foi emitida, consulte a nota antes de tentar de novo. Repetir com a mesma Idempotency-Key é seguro: devolve a mesma nota, sem emitir outra. Nunca use uma chave nova para repetir o mesmo pedido. A chave fica ligada a essa nota para sempre; usá-la com outro conteúdo responde 409.
Se o único motivo da recusa for número já usado (E0014 — já existe uma nota da empresa com essa série e número), a notem tenta sozinha os números seguintes, até cinco vezes, e a nota mantém o mesmo ID.
Parâmetros
Idempotency-KeyCorpo da requisição
Os textos são ajustados antes da conferência (por exemplo, aspas e travessões viram equivalentes aceitos) e a nota usa o texto ajustado; caracteres sem equivalente, como emojis, retornam 422 com a mensagem "contém caracteres não aceitos pela NFS-e". Indique a empresa de uma única forma, o serviço de uma única forma e o tomador de no máximo uma forma. Com ISS retido pelo tomador, o tomador precisa de CPF/CNPJ e endereço completo no Brasil.
empresa_idempresa_id_externoid_externoservico_idservico_id_externocompetenciadescricaotomadortomador.id_externotomador.tipopj, pf, estrangeirotomador.nometomador.documentotomador.niftomador.motivo_sem_nifdispensado, nao_exigidotomador.emailtomador.telefonetomador.inscricao_municipaltomador.enderecotomador.endereco.cep^[0-9]{8}$tomador.endereco.codigo_municipio^[0-9]{7}$tomador.endereco.pais^[A-Z]{2}$tomador.endereco.cidadetomador.endereco.codigo_postaltomador.endereco.estado_provincia_regiaotomador.endereco.logradourotomador.endereco.endereco_livretomador.endereco.numerotomador.endereco.bairrotomador.endereco.complementotomador_idtomador_id_externovaloresvalores.servico^\d+\.\d{2}$valores.desconto_incondicionado^\d+\.\d{2}$valores.desconto_condicionado^\d+\.\d{2}$retencao_issnao_retido, retido_tomador, retido_intermediarioaliquota_iss_simpleslocal_prestacaolocal_prestacao.codigo_municipio^\d{7}$informacoes_complementaresRespostas
201 Nota autorizada (incluindo repetição)
Campos da resposta
idid_externoorigemnotem, externaempresa_idambientehomologacao, producaosituacaoprocessando, em_verificacao, autorizada, rejeitada, cancelamento_em_analise, cancelada, substituida, cancelada_prefeiturarestricoesmanifestacaonumerochave_acesso^[0-9]{9}[0-9A-Z]{14}[0-9]{27}$serie_dpsnumero_dpscompetenciaemitida_emautorizada_emtomadortomador.idtomador.id_externotomador.tipopj, pf, estrangeirotomador.nometomador.documentotomador.niftomador.motivo_sem_nifdispensado, nao_exigidotomador.emailtomador.telefonetomador.inscricao_municipaltomador.enderecotomador.endereco.cep^[0-9]{8}$tomador.endereco.codigo_municipio^[0-9]{7}$tomador.endereco.pais^[A-Z]{2}$tomador.endereco.cidadetomador.endereco.codigo_postaltomador.endereco.estado_provincia_regiaotomador.endereco.logradourotomador.endereco.endereco_livretomador.endereco.numerotomador.endereco.bairrotomador.endereco.complementotomador.criada_emtomador.atualizada_emservicoservico.servico_idservico.codigo_servicoservico.descricaovaloresvalores.servico^\d+\.\d{2}$valores.desconto_incondicionado^\d+\.\d{2}$valores.desconto_condicionado^\d+\.\d{2}$valores.base_calculovalores.aliquota_issvalores.valor_issvalores.valor_liquidovalores.iss_retidolocal_prestacaoibs_cbsibs_cbs.classificacaoibs_cbs.classificacao.cstibs_cbs.classificacao.codigoibs_cbs.indicador_operacaoibs_cbs.consumidor_finalibs_cbs.localidade_incidenciaibs_cbs.localidade_incidencia.codigo_municipioibs_cbs.localidade_incidencia.nomeibs_cbs.percentual_redutoribs_cbs.base_calculoibs_cbs.ajuste_base_calculoibs_cbs.ajuste_base_locacao_imoveisibs_cbs.ibs_ufibs_cbs.ibs_uf.aliquotaibs_cbs.ibs_uf.reducao_aliquotaibs_cbs.ibs_uf.aliquota_efetivaibs_cbs.ibs_uf.valoribs_cbs.ibs_uf.diferimentoibs_cbs.ibs_municipalibs_cbs.ibs_municipal.aliquotaibs_cbs.ibs_municipal.reducao_aliquotaibs_cbs.ibs_municipal.aliquota_efetivaibs_cbs.ibs_municipal.valoribs_cbs.ibs_municipal.diferimentoibs_cbs.cbsibs_cbs.cbs.aliquotaibs_cbs.cbs.reducao_aliquotaibs_cbs.cbs.aliquota_efetivaibs_cbs.cbs.valoribs_cbs.cbs.diferimentoibs_cbs.valor_total_ibsibs_cbs.valor_total_ibs_cbsibs_cbs.valor_total_notaibs_cbs.credito_presumido_ibsibs_cbs.credito_presumido_ibs.percentualibs_cbs.credito_presumido_ibs.valoribs_cbs.credito_presumido_cbsibs_cbs.credito_presumido_cbs.percentualibs_cbs.credito_presumido_cbs.valoribs_cbs.receita_bruta_simplesibs_cbs.versao_calculadoraerros_governosubstitui_nota_idsubstituida_por_nota_idoperacao_pendenteoperacao_pendente.tipocancelamento, analise_cancelamentooperacao_pendente.estadoem_verificacaooperacao_pendente.desdecancelamentocancelamento.tipocancelamento, analise_cancelamentocancelamento.motivoerro_emissao, servico_nao_prestado, outroscancelamento.justificativacancelamento.solicitado_emcancelamento.registrado_emcancelamento.situacaoem_verificacao, cancelado, em_analise, recusado, nao_registrado, nao_enviadocancelamento.pode_solicitar_analisecancelamento.registrado_fora_da_notemcancelamento.erros_governolinkslinks.xmllinks.pdflinks.consulta_publicacriada_ematualizada_em202 Nota em processamento ou verificação automática
Campos da resposta
idid_externoorigemnotem, externaempresa_idambientehomologacao, producaosituacaoprocessando, em_verificacao, autorizada, rejeitada, cancelamento_em_analise, cancelada, substituida, cancelada_prefeiturarestricoesmanifestacaonumerochave_acesso^[0-9]{9}[0-9A-Z]{14}[0-9]{27}$serie_dpsnumero_dpscompetenciaemitida_emautorizada_emtomadortomador.idtomador.id_externotomador.tipopj, pf, estrangeirotomador.nometomador.documentotomador.niftomador.motivo_sem_nifdispensado, nao_exigidotomador.emailtomador.telefonetomador.inscricao_municipaltomador.enderecotomador.endereco.cep^[0-9]{8}$tomador.endereco.codigo_municipio^[0-9]{7}$tomador.endereco.pais^[A-Z]{2}$tomador.endereco.cidadetomador.endereco.codigo_postaltomador.endereco.estado_provincia_regiaotomador.endereco.logradourotomador.endereco.endereco_livretomador.endereco.numerotomador.endereco.bairrotomador.endereco.complementotomador.criada_emtomador.atualizada_emservicoservico.servico_idservico.codigo_servicoservico.descricaovaloresvalores.servico^\d+\.\d{2}$valores.desconto_incondicionado^\d+\.\d{2}$valores.desconto_condicionado^\d+\.\d{2}$valores.base_calculovalores.aliquota_issvalores.valor_issvalores.valor_liquidovalores.iss_retidolocal_prestacaoibs_cbsibs_cbs.classificacaoibs_cbs.classificacao.cstibs_cbs.classificacao.codigoibs_cbs.indicador_operacaoibs_cbs.consumidor_finalibs_cbs.localidade_incidenciaibs_cbs.localidade_incidencia.codigo_municipioibs_cbs.localidade_incidencia.nomeibs_cbs.percentual_redutoribs_cbs.base_calculoibs_cbs.ajuste_base_calculoibs_cbs.ajuste_base_locacao_imoveisibs_cbs.ibs_ufibs_cbs.ibs_uf.aliquotaibs_cbs.ibs_uf.reducao_aliquotaibs_cbs.ibs_uf.aliquota_efetivaibs_cbs.ibs_uf.valoribs_cbs.ibs_uf.diferimentoibs_cbs.ibs_municipalibs_cbs.ibs_municipal.aliquotaibs_cbs.ibs_municipal.reducao_aliquotaibs_cbs.ibs_municipal.aliquota_efetivaibs_cbs.ibs_municipal.valoribs_cbs.ibs_municipal.diferimentoibs_cbs.cbsibs_cbs.cbs.aliquotaibs_cbs.cbs.reducao_aliquotaibs_cbs.cbs.aliquota_efetivaibs_cbs.cbs.valoribs_cbs.cbs.diferimentoibs_cbs.valor_total_ibsibs_cbs.valor_total_ibs_cbsibs_cbs.valor_total_notaibs_cbs.credito_presumido_ibsibs_cbs.credito_presumido_ibs.percentualibs_cbs.credito_presumido_ibs.valoribs_cbs.credito_presumido_cbsibs_cbs.credito_presumido_cbs.percentualibs_cbs.credito_presumido_cbs.valoribs_cbs.receita_bruta_simplesibs_cbs.versao_calculadoraerros_governosubstitui_nota_idsubstituida_por_nota_idoperacao_pendenteoperacao_pendente.tipocancelamento, analise_cancelamentooperacao_pendente.estadoem_verificacaooperacao_pendente.desdecancelamentocancelamento.tipocancelamento, analise_cancelamentocancelamento.motivoerro_emissao, servico_nao_prestado, outroscancelamento.justificativacancelamento.solicitado_emcancelamento.registrado_emcancelamento.situacaoem_verificacao, cancelado, em_analise, recusado, nao_registrado, nao_enviadocancelamento.pode_solicitar_analisecancelamento.registrado_fora_da_notemcancelamento.erros_governolinkslinks.xmllinks.pdflinks.consulta_publicacriada_ematualizada_em400 Erro no formato padrão
401 Chave ausente, inválida ou revogada
404 Erro no formato padrão
409 IDEMPOTENCIA_CONFLITO, ID_EXTERNO_DUPLICADO ou configuração alterada
422 REGRA_DE_NEGOCIO, EMPRESA_NAO_PRONTA ou REJEITADO_GOVERNO (detalhes incluem nota_id e mensagens originais)
503 Erro no formato padrão
Limites
Esta operação: 20 por minuto em produção e 10 em homologação; no máximo 2 ao mesmo tempo por empresa. Valem também os limites gerais da chave. Veja Limites de uso.

