---
title: "Emite uma NFS-e"
method: POST
path: "/v1/nfse"
tags: ["Emissão de NFS-e"]
---

# Emite uma NFS-e

`POST /v1/nfse`

## Request

- Base URL: `https://api.sudrel.com.br/api`
- URL: `https://api.sudrel.com.br/api/v1/nfse`
- Auth: HTTP bearer

Valida, cria e transmite a nota. Se a empresa ainda não pode emitir
(sem certificado válido, sem regime tributário, conta sem plano de
Emissão), devolve **412** `empresa_nao_pronta` com a mesma lista de
`GET /v1/companies/{id}/prontidao` e não cria nada. Com payload
inválido devolve **422 com todos os erros** e não cria nada. Com
payload válido, a nota
entra na fila de emissão e a chamada acompanha o resultado pelo
tempo pedido em `Prefer: wait=N`:

- **201**: autorizada dentro do prazo. Corpo: a nota.
- **202**: ainda `transmitindo`. Corpo: a nota; acompanhe por
  `Location` ou pelo webhook `NFSE_AUTORIZADA`.
- **422** `nfse_rejeitada`: rejeitada pelo Sistema Nacional. O corpo
  traz `nfse_id` e a nota inteira.
- **422** `falha_transmissao`: a transmissão terminou sem confirmação
  dentro da espera. O corpo traz `nfse_id` e a nota inteira; veja
  `falha.dps_enviada` antes de emitir de novo.

**202 não é erro.** A nota existe e está sendo cuidada: acompanhe por
webhook ou por `GET /v1/nfse/{id}`. Repetir a chamada com a mesma
`Idempotency-Key` devolve a MESMA resposta gravada (a foto do momento,
que pode continuar `transmitindo` mesmo depois de a nota autorizar):
para saber o status atual, use o `GET`.

Use sempre `Idempotency-Key`. Repetir a MESMA chave com o MESMO
corpo devolve a mesma resposta, sem criar outra nota; a mesma chave
com corpo diferente é **409** `idempotencia_conflito`.

## Headers

- `Idempotency-Key` string
- `Prefer` string
- `X-Sudrel-Simular` string

## Request body

- NfseEntrada: O mesmo conjunto de campos da planilha de emissão, em JSON. Só `tomador.documento` e `valor` são sempre obrigatórios; `descricao` e `codigo_nacional` vêm da configuração da empresa quando omitidos. Campo desconhecido é erro (422 `campo_desconhecido`).
  - `empresa_id` string: Empresa emissora. Dispensado quando a chave de API é restrita a uma empresa.
  - `referencia` string: Seu identificador para esta nota (pedido, contrato). Único por empresa; repetido é 409 com o id da nota existente.
  - `modelo` string: Nome ou id de um modelo de emissão salvo no painel. Preenche descrição, código de serviço e competência quando não enviados.
  - `substituicao` object: Esta nota SUBSTITUI uma NFS-e autorizada (grupo `subst` da DPS). Informe `nfse_id` (nota emitida pela Sudrel) ou `chave_acesso` (NFS-e emitida em outro sistema, do mesmo prestador). Veja "Substituir uma NFS-e" acima. Só em `POST /v1/nfse`: o lote recusa (`substituicao_fora_do_lote`).
    - `nfse_id` string: Id da nota a substituir (de `GET /v1/nfse`).
    - `chave_acesso` string: Ou a chave de acesso da NFS-e a substituir, 50 dígitos.
    - `codigo_motivo` '01' | '02' | '03' | '04' | '05' | '99', required: 01 desenquadramento do Simples Nacional; 02 enquadramento no Simples Nacional; 03 inclusão retroativa de imunidade ou isenção; 04 exclusão retroativa de imunidade ou isenção; 05 rejeição da NFS-e pelo tomador ou intermediário; 99 outros.
    - `motivo` string: Descrição do motivo. Obrigatória com `codigo_motivo` 99 (E0078).
  - `tomador` object, required
    - `documento` string, required: CPF (11 dígitos) ou CNPJ (14 posições, numérico ou alfanumérico), com ou sem pontuação.
    - `razao_social` string: Obrigatório para CPF. Para CNPJ, consultamos automaticamente.
    - `email` string: Obrigatório só quando o sistema do município da empresa precisa dele para cancelar a nota (hoje, o WebISS). Nos outros casos, opcional; quando vier, o PDF da nota vai para ele.
    - `endereco` object: Para CPF, opcional: CPF e nome bastam, menos quando o serviço tributa no domicílio do tomador (o `cIndOp` aponta para o endereço dele, ou mão de obra, 17.05.01), e aí a validação devolve `tomador_endereco_obrigatorio`. Quando vier, CEP e número vão juntos e o resto sai do CEP. Para CNPJ, não precisa.
      - `cep` string
      - `numero` string
      - `complemento` string
      - `municipio` string: Só para sobrescrever o município resolvido. Nome com UF ou código IBGE.
  - `valor` string, required: Texto decimal com ponto, sem separador de milhar. Número JSON é recusado (422 `tipo_invalido`).
  - `servico` object
    - `descricao` string
    - `codigo_nacional` string: Código de tributação nacional (cTribNac), 6 dígitos.
    - `competencia` string: AAAA-MM. Padrão, o mês atual.
    - `nbs` string: Código NBS do serviço (9 dígitos, com ou sem pontos), declarado junto do IBS e da CBS. Tem de ser um dos admitidos para o código de serviço (veja `GET /v1/servicos/{codigo}/nbs`); cada NBS leva a sua classificação tributária. Padrão: o NBS padrão da empresa, e na falta dele o padrão da tabela oficial.
    - `obra` ObraEntrada: Dados da obra (grupo `serv/obra` da DPS). Obrigatório nos códigos de construção civil (E0370) e proibido nos demais, menos o 99.01.01 (E0372). Identifique a obra por UM destes: `cno`, `cib` ou `endereco` (CEP e número); com mais de um, vai o CNO, depois o CIB. O município da obra é o local da prestação: vem do CEP, quando há CEP, ou de `municipio`.
      - `cno` string: Número da obra no Cadastro Nacional de Obras (ou CEI), com ou sem máscara.
      - `cib` string: Código do Cadastro Imobiliário Brasileiro do imóvel, 8 caracteres.
      - `inscricao_imobiliaria` string: Inscrição imobiliária fiscal (a do IPTU), opcional.
      - `endereco` object: Rua e bairro vêm do CEP.
        - `cep` string
        - `numero` string
        - `complemento` string
      - `municipio` string: Nome com UF (`Salvador - BA`) ou código IBGE. Dispensado quando o CEP foi informado; com os dois, têm de concordar (E0380).
  - `retencoes` object: O que o TOMADOR retém.
    - `iss` boolean: ISS retido pelo tomador.
    - `pis` Tributo: Informe o valor OU a alíquota. Com a alíquota, calculamos o valor sobre o valor do serviço.
      - `valor` string: Texto decimal com ponto, sem separador de milhar. Número JSON é recusado (422 `tipo_invalido`).
      - `aliquota` string: Percentual como texto, com ponto e sem "%".
    - `cofins` Tributo: Informe o valor OU a alíquota. Com a alíquota, calculamos o valor sobre o valor do serviço.
      - `valor` string: Texto decimal com ponto, sem separador de milhar. Número JSON é recusado (422 `tipo_invalido`).
      - `aliquota` string: Percentual como texto, com ponto e sem "%".
    - `csll` Tributo: Informe o valor OU a alíquota. Com a alíquota, calculamos o valor sobre o valor do serviço.
      - `valor` string: Texto decimal com ponto, sem separador de milhar. Número JSON é recusado (422 `tipo_invalido`).
      - `aliquota` string: Percentual como texto, com ponto e sem "%".
    - `irrf` Tributo: Informe o valor OU a alíquota. Com a alíquota, calculamos o valor sobre o valor do serviço.
      - `valor` string: Texto decimal com ponto, sem separador de milhar. Número JSON é recusado (422 `tipo_invalido`).
      - `aliquota` string: Percentual como texto, com ponto e sem "%".
    - `inss` Tributo: Informe o valor OU a alíquota. Com a alíquota, calculamos o valor sobre o valor do serviço.
      - `valor` string: Texto decimal com ponto, sem separador de milhar. Número JSON é recusado (422 `tipo_invalido`).
      - `aliquota` string: Percentual como texto, com ponto e sem "%".
  - `apuracao_propria` object: PIS/COFINS da apuração da SUA empresa (não é retenção).
    - `pis` Tributo: Informe o valor OU a alíquota. Com a alíquota, calculamos o valor sobre o valor do serviço.
      - `valor` string: Texto decimal com ponto, sem separador de milhar. Número JSON é recusado (422 `tipo_invalido`).
      - `aliquota` string: Percentual como texto, com ponto e sem "%".
    - `cofins` Tributo: Informe o valor OU a alíquota. Com a alíquota, calculamos o valor sobre o valor do serviço.
      - `valor` string: Texto decimal com ponto, sem separador de milhar. Número JSON é recusado (422 `tipo_invalido`).
      - `aliquota` string: Percentual como texto, com ponto e sem "%".
  - `iss` object
    - `aliquota` string: Percentual como texto, com ponto e sem "%".

## Response `201`

Autorizada.

- Nfse
  - `id` string
  - `referencia` string, nullable
  - `status` 'transmitindo' | 'autorizada' | 'rejeitada' | 'cancelada' | 'falha_transmissao' | 'descartada' | 'aguardando_confirmacao'
  - `empresa_id` string
  - `ambiente` 'producao' | 'sandbox': `sandbox` = emitida com chave de teste, no ambiente de testes do Sistema Nacional, sem valor fiscal.
  - `simulacao` string, nullable: Cenário do simulador de falhas (`X-Sudrel-Simular`); `null` em nota de verdade. Nota simulada nunca foi à Sefin.
  - `origem` 'api' | 'planilha' | 'manual' | 'monitoramento'
  - `numero` string, nullable
  - `chave_acesso` string, nullable
  - `dps` object, nullable
    - `serie` string
    - `numero` string
  - `valor` string: Texto decimal com ponto, sem separador de milhar. Número JSON é recusado (422 `tipo_invalido`).
  - `tomador` object
  - `servico` object
    - `codigo_nacional` string
    - `descricao` string
    - `competencia` string
    - `nbs` string, nullable: NBS escolhido para a nota, sem pontos. `null` = padrão da empresa ou da tabela oficial; o que foi declarado aparece nos `ajustes`.
    - `obra` ObraNfse, nullable
      - `cno` string, nullable
      - `cib` string, nullable
      - `inscricao_imobiliaria` string, nullable
      - `endereco` object, nullable
        - `cep` string
        - `logradouro` string
        - `numero` string
        - `complemento` string, nullable
        - `bairro` string
      - `municipio_ibge` string: Local da prestação.
  - `retencoes` object
  - `apuracao_propria` object
  - `iss` object
  - `rejeicao` object, nullable
    - `codigo_oficial` string, nullable
    - `mensagem` string: A mensagem do Sistema Nacional, como veio.
    - `explicacao` object, nullable: Explicação da Sudrel para o código oficial, quando ele é conhecido. `null` quando não é: aí vale só a `mensagem`.
      - `codigo` string: Estável, ex.: `aliquota_iss_obrigatoria`.
      - `campo` string, nullable: JSON Pointer no payload, quando é campo que você envia.
      - `mensagem` string
      - `correcao` string
  - `falha` object, nullable: Só em `falha_transmissao`.
    - `dps_enviada` 'nao' | 'desconhecido'
    - `mensagem` string, nullable
    - `correcao` string
  - `cancelamento` object, nullable
    - `em` string, date-time
    - `protocolo` string
    - `justificativa` string
  - `recuperada_em` string, date-time, nullable
  - `substituicao` object, nullable: Nesta nota (a nova), qual NFS-e ela substitui.
    - `nfse_id` string, nullable: `null` quando a original foi emitida fora da Sudrel.
    - `chave_acesso` string
    - `codigo_motivo` string
    - `motivo` string, nullable
  - `substituida_por` object, nullable: Nesta nota (a original, agora `cancelada` pelo Sistema Nacional), qual a substituiu.
    - `nfse_id` string
    - `links` object
      - `self` string
  - `confirmacao` object, nullable: Só em `aguardando_confirmacao`.
    - `motivo` 'competencia_encerrada'
    - `competencia` string
    - `mensagem` string
    - `correcao` string
  - `aviso` object, nullable: Só em `transmitindo`, depois de 30 minutos.
    - `codigo` 'processamento_prolongado'
    - `desde` string, date-time
    - `mensagem` string
  - `ajustes` Ajuste[]
    - `campo` string: JSON Pointer.
    - `acao` 'preenchido' | 'omitido' | 'derivado' | 'exigido'
    - `motivo` string
    - `regra` string: Identificador estável da regra.
  - `eventos` EventoNfse[]
    - `tipo` 'criada' | 'envio' | 'consulta_dps' | 'correcao_automatica' | 'reenfileirada' | 'falha_validacao' | 'recuperada' | 'cancelada' | 'substituida' | 'aguardando_confirmacao' | 'competencia_confirmada' | 'processamento_prolongado' | 'falha_transmissao'
    - `em` string, date-time
    - `detalhe` object
  - `regras_versao` string: Versões do catálogo de correções automáticas e do catálogo de regras de campo que decidiram esta nota, nessa ordem.
  - `criada_em` string, date-time
  - `atualizada_em` string, date-time
  - `links` object
    - `self` string
    - `xml` string
    - `pdf` string

## Other responses

- `202`: Aceita e ainda transmitindo.
- `401`: `nao_autenticado`: chave de API ausente, inválida ou revogada.
- `403`: Chave restrita a outra empresa.
- `404`: `nao_encontrado`: `empresa_id` não existe nesta conta.
- `409`: `referencia_duplicada` (com `nfse_id` da nota existente), `idempotencia_conflito` (mesma `Idempotency-Key` com outro corpo) ou `conflito` (a mesma `Idempotency-Key` ainda está em processamento em outra requisição: espere a primeira responder e repita).
- `412`: `empresa_nao_pronta`: a empresa ainda não pode emitir. Nenhuma nota foi criada. `itens` traz a prontidão inteira; resolva os de `"situacao": "bloqueio"` e envie de novo.
- `422`: `validacao`: payload inválido, com todos os erros em `erros` (nada foi criado). `nfse_rejeitada`: rejeitada pelo Sistema Nacional (a nota existe, com status `rejeitada`). `falha_transmissao`: a nota existe e a transmissão não pôde ser concluída. `simulacao_so_no_sandbox` / `simulacao_invalida`: o cabeçalho `X-Sudrel-Simular` foi mandado com a chave de produção ou com um cenário que não existe.
- `429`: `limite_de_requisicoes` (`retentavel: true`): 120 requisições por minuto por chave, janela fixa de 60 s. Sem `Retry-After`: espere a virada do minuto e repita a MESMA requisição (com a mesma `Idempotency-Key`).

---

[API](https://skmtc.dev/sudrel/apis/api-publica-sudrel-nfs-e-nf-e-e-ct-e.md) · [All operations](https://skmtc.dev/sudrel/apis/api-publica-sudrel-nfs-e-nf-e-e-ct-e/llms.txt) · [OpenAPI document](https://skmtc.dev/sudrel/apis/api-publica-sudrel-nfs-e-nf-e-e-ct-e/revisions/efd7baba9e37?raw)