---
title: "Referência: emitir uma NFS-e (POST /v1/nfse)"
description: "Referência do POST /v1/nfse: cabeçalhos, corpo da requisição (empresa, tomador e serviço), objeto NFS-e da resposta e erros da emissão de NFS-e pela API."
url: https://docs.emissordenota.com/referencia/nfse
language: pt-BR
---
# Emitir uma NFS-e

Cria uma nota de serviço e coloca na fila de transmissão. A resposta volta na hora com o status processando; o resultado chega pelo webhook nfse.autorizada ou nfse.rejeitada.

`POST /v1/nfse`

**Escopo exigido**: nfse:escrever

**Requisição**

```bash
curl -X POST https://api.emissordenota.com/v1/nfse \
  -H "Authorization: Bearer $EDN_KEY" \
  -H "Idempotency-Key: fatura-2026-11-0042" \
  -H "Content-Type: application/json" \
  -d '{
    "empresa_id": "emp_8Kq2mXv41c",
    "data_competencia": "2026-11-09",
    "referencia": "fatura-0042",
    "tomador": {
      "documento": "98765432000198",
      "nome": "Clínica Bem Viver Ltda",
      "email": "financeiro@bemviver.com.br"
    },
    "servico": {
      "codigo_tributacao_nacional": "010701",
      "descricao": "Suporte técnico em informática",
      "valor": 1500.00,
      "iss_retido": false
    }
  }'
```

## Notificações ao usuário da integração

Inclua notificacoes no corpo da operação para avisar quem usa seu sistema. Informe os contatos desse usuário. A escolha vale só para a operação e seus resultados, inclusive quando a autorização da nota chega depois.

**Campos opcionais**

```json
{
  "notificacoes": {
    "destinatario": {
      "email": "usuario@example.com",
      "whatsapp": "+5511999991234",
      "whatsapp_autorizado": true
    },
    "eventos": {
      "nfse.autorizada": [
        "email",
        "whatsapp"
      ],
      "nfse.rejeitada": [
        "email"
      ]
    }
  }
}
```

Omitir notificacoes executa a operação sem solicitar aviso. Cada canal precisa estar liberado no plano para o evento da API. Um pedido sem permissão retorna 403 permissao_insuficiente antes de executar a operação. Informe o WhatsApp com DDI e confirme a autorização do destinatário. Repetir uma chamada concluída com a mesma Idempotency-Key recupera a resposta original sem novo disparo. O sandbox valida a seleção e simula a operação sem efetuar entregas.

Para emissão e substituição, escolha nfse.enviada, nfse.autorizada, nfse.rejeitada ou nfse.verificando. A substituição também aceita nfse.substituida. Para cancelar, escolha nfse.cancelamento_solicitado, nfse.cancelamento_recusado ou nfse.cancelada.

## Cabeçalhos

- `Authorization` (string, obrigatório): Bearer seguido da chave de API.
- `Idempotency-Key` (string, recomendado): Identificador único da nota no seu sistema. Repetir a chamada com a mesma chave em até 24 horas devolve a nota já criada.

## Corpo da requisição

- `empresa_id` (string, obrigatório): Empresa emissora. Precisa estar liberada para a chave.
- `data_competencia` (date, opcional): Dia em que o serviço foi prestado, no formato AAAA-MM-DD. Sem ela, vale a data do envio.
- `referencia` (string, opcional): Identificador do seu sistema, com até 60 caracteres. Volta nas consultas e nos webhooks.
- `tomador` (object, obrigatório): Quem contrata o serviço.
  - `documento` (string, obrigatório): CNPJ ou CPF, só com dígitos.
  - `nome` (string, obrigatório): Razão social ou nome completo.
  - `email` (string, opcional): Se informado, o tomador recebe a nota por e-mail quando ela for autorizada.
  - `endereco` (object, opcional): CEP e número. Rua, bairro e cidade são preenchidos a partir do CEP.
- `servico` (object, obrigatório): O serviço prestado.
  - `codigo_tributacao_nacional` (string, obrigatório): Código de seis dígitos da lista nacional de serviços.
  - `descricao` (string, obrigatório): Discriminação do serviço, como vai aparecer na nota.
  - `valor` (number, obrigatório): Valor em reais, com ponto decimal. Maior que zero.
  - `iss_retido` (boolean, opcional): Marque true quando o tomador retém o ISS. O padrão é false.

## Resposta

201 com o objeto NFS-e. Os campos que só existem depois da autorização voltam como null.

- `id` (string): Identificador da nota na API.
- `status` (string): processando, autorizada, rejeitada ou cancelada.
- `numero` (string): Número da nota. Preenchido quando autorizada.
- `chave_acesso` (string): Chave de acesso de 50 dígitos. Preenchida quando autorizada.
- `xml_url, pdf_url` (string): Links para baixar os arquivos. Exigem a mesma chave de API.

**Resposta · 201 Created**

```json
{
  "id": "nfse_3Jt9wPz7Qa",
  "status": "processando",
  "empresa_id": "emp_8Kq2mXv41c",
  "referencia": "fatura-0042",
  "numero": null,
  "chave_acesso": null,
  "valor": 1500.00,
  "iss_retido": false,
  "criada_em": "2026-11-09T10:42:07-03:00",
  "xml_url": null,
  "pdf_url": null
}
```

## Erros deste endpoint

| Status | Código | Quando |
| --- | --- | --- |
| 403 | empresa_nao_autorizada | A chave não alcança a empresa emissora |
| 409 | idempotencia_em_conflito | A mesma Idempotency-Key veio com outro corpo |
| 422 | dados_invalidos | Algum campo foi recusado. Veja detalhes |
| 422 | certificado_vencido | O certificado A1 da empresa expirou |

**Resposta · 422 Unprocessable Entity**

```json
{
  "erro": {
    "codigo": "certificado_vencido",
    "mensagem": "O certificado A1 expirou.",
    "requisicao_id": "req_4Bn8Ws2Kd6"
  }
}
```
