Referência da APINFS-e

Emitir uma NFS-e

POST/v1/nfse

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.

Escopo exigidonfse:escrever

Linguagem dos exemplos
Requisição
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
{  "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

Authorizationstringobrigatório
Bearer seguido da chave de API.
Idempotency-Keystringrecomendado
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_idstringobrigatório
Empresa emissora. Precisa estar liberada para a chave.
data_competenciadateopcional
Dia em que o serviço foi prestado, no formato AAAA-MM-DD. Sem ela, vale a data do envio.
referenciastringopcional
Identificador do seu sistema, com até 60 caracteres. Volta nas consultas e nos webhooks.
tomadorobjectobrigatório
Quem contrata o serviço.
documentostringobrigatório
CNPJ ou CPF, só com dígitos.
nomestringobrigatório
Razão social ou nome completo.
emailstringopcional
Se informado, o tomador recebe a nota por e-mail quando ela for autorizada.
enderecoobjectopcional
CEP e número. Rua, bairro e cidade são preenchidos a partir do CEP.
servicoobjectobrigatório
O serviço prestado.
codigo_tributacao_nacionalstringobrigatório
Código de seis dígitos da lista nacional de serviços.
descricaostringobrigatório
Discriminação do serviço, como vai aparecer na nota.
valornumberobrigatório
Valor em reais, com ponto decimal. Maior que zero.
iss_retidobooleanopcional
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.

idstring
Identificador da nota na API.
statusstring
processando, autorizada, rejeitada ou cancelada.
numerostring
Número da nota. Preenchido quando autorizada.
chave_acessostring
Chave de acesso de 50 dígitos. Preenchida quando autorizada.
xml_url, pdf_urlstring
Links para baixar os arquivos. Exigem a mesma chave de API.
Resposta · 201 Created
{  "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

StatusCódigoQuando

  • 403empresa_nao_autorizada
    A chave não alcança a empresa emissora
  • 409idempotencia_em_conflito
    A mesma Idempotency-Key veio com outro corpo
  • 422dados_invalidos
    Algum campo foi recusado. Veja detalhes
  • 422certificado_vencido
    O certificado A1 da empresa expirou
Resposta · 422 Unprocessable Entity
{  "erro": {    "codigo": "certificado_vencido",    "mensagem": "O certificado A1 expirou.",    "requisicao_id": "req_4Bn8Ws2Kd6"  }}