Referência: NFS-e

Atualizado em 11/11/2026

Nesta página

O objeto NFS-e
Status
Emitir uma NFS-e
Corpo
Consultar uma NFS-e
Listar NFS-e
Baixar o XML
Baixar o PDF (DANFSe)
Cancelar uma NFS-e
Substituir uma NFS-e
Próximos passos

O recurso NFS-e representa uma emissão do começo ao fim: nasce como DPS na fila (queued) e, se a Sefin aceitar, vira a nota autorizada. O mesmo id vale em todas as fases.

Método	Rota	Escopo
`POST`	`/integracao/nfse`	`nfse:emit`
`GET`	`/integracao/nfse/{id}`	`nfse:read`
`GET`	`/integracao/nfse`	`nfse:read`
`GET`	`/integracao/nfse/{id}/xml`	`nfse:read`
`GET`	`/integracao/nfse/{id}/pdf`	`nfse:read`
`POST`	`/integracao/nfse/{id}/cancelar`	`nfse:cancel`
`POST`	`/integracao/nfse/{id}/substituir`	`nfse:replace`

A listagem dos eventos da nota está em Eventos.

O objeto NFS-e#

NFS-e autorizada

{
  "id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84",
  "status": "authorized",
  "ambiente": "sandbox",
  "is_test": true,
  "origem": "api",
  "external_ref": "pedido-2026-11-0001",
  "id_dps": "DPS355030821122233300018100900000000000000042",
  "serie": "900",
  "numero_dps": 42,
  "numero_nfse": "42",
  "chave_acesso": "35503082211222333000181000000000004226114829130573",
  "competencia": "2026-11-10",
  "emitida_em": "2026-11-11T10:15:32-03:00",
  "tomador": {
    "id": "5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10",
    "tipo_pessoa": "PJ",
    "documento": "11444777000161",
    "nome": "Padaria Silva Ltda"
  },
  "servico": {
    "item_id": "8a3e6d21-4f9b-4b2a-bc17-0e5d9c3a6f42",
    "codigo_tributacao_nacional": "010601",
    "codigo_nbs": "115011000",
    "descricao": "Consultoria em tecnologia da informação - novembro/2026",
    "municipio_prestacao_ibge": "3550308"
  },
  "valores": {
    "valor_servico": "1500.00",
    "desconto_incondicionado": "0.00",
    "desconto_condicionado": "0.00",
    "base_calculo": "1500.00",
    "aliquota_iss": "2.00",
    "valor_iss": "30.00",
    "iss_retido": false,
    "total_retido": "0.00",
    "valor_liquido": "1500.00"
  },
  "rejeicao": null,
  "substitui_id": null,
  "substituida_por_id": null,
  "created_at": "2026-11-11T10:15:30-03:00",
  "updated_at": "2026-11-11T10:15:33-03:00"
}

Campo	Descrição
`id`	Identificador da emissão na Emitra (é o id da DPS)
`status`	Ver tabela abaixo
`ambiente`	`sandbox`, `producao_restrita` ou `producao`
`origem`	`api`, `manual`, `recurring`, `batch` ou `connector`
`external_ref`	Sua referência, enviada na emissão
`id_dps`	Id oficial da DPS, 45 posições
`serie`, `numero_dps`	Série e número da DPS, controlados pela Emitra
`numero_nfse`	Número da nota, gerado pela Sefin. `null` antes da autorização
`chave_acesso`	Chave de 50 posições, gerada pela Sefin. `null` antes da autorização
`competencia`	Data de competência (`dCompet`)
`emitida_em`	Data e hora de emissão (`dhEmi`)
`valores`	Valores calculados. Depois da autorização, refletem o que a Sefin devolveu
`rejeicao`	Preenchido quando `status` é `rejected`. Ver Erros
`substitui_id` / `substituida_por_id`	Ligações de substituição

Status#

`status`	Significa	Final?
`queued`	Aceita pela Emitra, número reservado, na fila	Não
`signed`	XML montado, validado e assinado	Não
`sent`	Transmitida à Sefin, aguardando resposta ou reconciliação	Não
`error`	Falha técnica. A Emitra tenta de novo sozinha	Não
`authorized`	NFS-e gerada	Sim, até um evento
`rejected`	Recusada pela Sefin	Sim
`canceled`	Cancelada	Sim
`replaced`	Substituída por outra nota	Sim
`cancel_under_analysis`	Cancelamento fora do prazo aguardando o município	Não

Emitir uma NFS-e#

POST /integracao/nfse → 202 Accepted. Header Idempotency-Key obrigatório (ver Idempotência).

Corpo#

Campo	Tipo	Descrição
`tomador_id`	uuid	Tomador cadastrado. Use este ou `tomador`
`tomador`	objeto	Tomador inline, no mesmo formato de criar tomador. Omita os dois para tomador não identificado
`competencia`	data	`AAAA-MM-DD`. Não pode ser futura. Obrigatório
`servico.item_id`	uuid	Item cadastrado. Preenche códigos, descrição e alíquota
`servico.codigo_tributacao_nacional`	string	cTribNac. Obrigatório se não houver `item_id`
`servico.codigo_nbs`	string	NBS, 9 dígitos
`servico.codigo_tributacao_municipal`	string	cTribMun, quando o município usa
`servico.descricao`	string	Discriminação do serviço. Se omitida, usa a do item
`servico.valor`	string decimal	Valor do serviço. Obrigatório, maior que zero
`servico.municipio_prestacao_ibge`	string	Município da prestação. Padrão: o município emissor
`descontos.incondicionado`	string decimal	Reduz a base de cálculo
`descontos.condicionado`	string decimal	Reduz só o valor líquido
`iss_retido`	boolean	ISS retido pelo tomador. Padrão `false`
`external_ref`	string	Sua referência (pedido, fatura). Recomendado
`enviar_email_tomador`	boolean	Envia PDF e XML ao e-mail do tomador após a autorização

O regime tributário, a série, a inscrição municipal e os demais dados do prestador vêm da configuração fiscal da empresa. Os grupos de IBS/CBS são preenchidos a partir do cadastro do serviço.

cURL

curl https://emitra.com.br/api/v1/integracao/nfse \
  -H "Authorization: Bearer $EMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-2026-11-0001" \
  -d '{
    "tomador_id": "5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10",
    "competencia": "2026-11-10",
    "servico": {
      "item_id": "8a3e6d21-4f9b-4b2a-bc17-0e5d9c3a6f42",
      "descricao": "Consultoria em tecnologia da informação - novembro/2026",
      "valor": "1500.00"
    },
    "external_ref": "pedido-2026-11-0001",
    "enviar_email_tomador": true
  }'

Python

r = requests.post(
    f"{API}/nfse",
    headers={**H, "Idempotency-Key": "pedido-2026-11-0001"},
    json={
        "tomador_id": "5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10",
        "competencia": "2026-11-10",
        "servico": {
            "item_id": "8a3e6d21-4f9b-4b2a-bc17-0e5d9c3a6f42",
            "descricao": "Consultoria em tecnologia da informação - novembro/2026",
            "valor": "1500.00",
        },
        "external_ref": "pedido-2026-11-0001",
        "enviar_email_tomador": True,
    },
    timeout=30,
)
assert r.status_code == 202
nfse_id = r.json()["data"]["id"]

JavaScript

const r = await fetch(`${API}/nfse`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "pedido-2026-11-0001" },
  body: JSON.stringify({
    tomador_id: "5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10",
    competencia: "2026-11-10",
    servico: {
      item_id: "8a3e6d21-4f9b-4b2a-bc17-0e5d9c3a6f42",
      descricao: "Consultoria em tecnologia da informação - novembro/2026",
      valor: "1500.00",
    },
    external_ref: "pedido-2026-11-0001",
    enviar_email_tomador: true,
  }),
});
const { data } = await r.json(); // r.status === 202

PHP

<?php
$ch = curl_init("$api/nfse");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => array_merge($headers, ["Idempotency-Key: pedido-2026-11-0001"]),
    CURLOPT_POSTFIELDS => json_encode([
        "tomador_id" => "5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10",
        "competencia" => "2026-11-10",
        "servico" => [
            "item_id" => "8a3e6d21-4f9b-4b2a-bc17-0e5d9c3a6f42",
            "descricao" => "Consultoria em tecnologia da informação - novembro/2026",
            "valor" => "1500.00",
        ],
        "external_ref" => "pedido-2026-11-0001",
        "enviar_email_tomador" => true,
    ]),
]);
$data = json_decode(curl_exec($ch), true)["data"]; // HTTP 202

Resposta 202

{
  "status": "success",
  "message": "DPS recebida e enfileirada",
  "data": {
    "id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84",
    "status": "queued",
    "external_ref": "pedido-2026-11-0001",
    "is_test": true,
    "created_at": "2026-11-11T10:15:30-03:00"
  }
}

Erros comuns na hora: VALIDATION_ERROR, IDEMPOTENCY_KEY_REUSED, COTA_EXCEDIDA, TENANT_INADIMPLENTE, certificado ausente ou vencido. Veja Erros.

Consultar uma NFS-e#

GET /integracao/nfse/{id} → 200 com o objeto NFS-e.

cURL

curl https://emitra.com.br/api/v1/integracao/nfse/3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84 \
  -H "Authorization: Bearer $EMITRA_API_KEY"

Python

nota = requests.get(f"{API}/nfse/{nfse_id}", headers=H, timeout=30).json()["data"]
if nota["status"] == "rejected":
    print(nota["rejeicao"]["codigo"], nota["rejeicao"]["orientacao"])

JavaScript

const { data: nota } = await (await fetch(`${API}/nfse/${nfseId}`, { headers })).json();
if (nota.status === "rejected") console.log(nota.rejeicao.codigo, nota.rejeicao.orientacao);

PHP

<?php
$ch = curl_init("$api/nfse/$nfseId");
curl_setopt_array($ch, [CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true]);
$nota = json_decode(curl_exec($ch), true)["data"];

Se fizer polling, consulte a cada 2 segundos ou mais e pare quando o status for final. Prefira o webhook nfse.authorized.

Listar NFS-e#

GET /integracao/nfse → 200, paginado por cursor.

Parâmetro	Descrição
`competencia`	Mês de competência, `AAAA-MM`
`emitida_de`, `emitida_ate`	Intervalo da data de emissão, `AAAA-MM-DD`
`status`	Um dos status da tabela acima
`tomador`	Id do tomador
`external_ref`	Sua referência exata
`limit`, `cursor`	Paginação

cURL

curl "https://emitra.com.br/api/v1/integracao/nfse?competencia=2026-11&status=authorized&limit=200" \
  -H "Authorization: Bearer $EMITRA_API_KEY"

Para achar a nota de um pedido depois que a Idempotency-Key expirou:

cURL

curl "https://emitra.com.br/api/v1/integracao/nfse?external_ref=pedido-2026-11-0001" \
  -H "Authorization: Bearer $EMITRA_API_KEY"

Baixar o XML#

GET /integracao/nfse/{id}/xml → 200, Content-Type: application/xml. Disponível a partir de authorized. É o XML assinado pela Sefin, imutável, e é o documento fiscal.

cURL

curl -L -o nfse-42.xml \
  https://emitra.com.br/api/v1/integracao/nfse/3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84/xml \
  -H "Authorization: Bearer $EMITRA_API_KEY"

Baixar o PDF (DANFSe)#

GET /integracao/nfse/{id}/pdf → 200, Content-Type: application/pdf.

cURL

curl -L -o nfse-42.pdf \
  https://emitra.com.br/api/v1/integracao/nfse/3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84/pdf \
  -H "Authorization: Bearer $EMITRA_API_KEY"

Cancelar uma NFS-e#

POST /integracao/nfse/{id}/cancelar → 202 Accepted. Gera o evento de cancelamento (e101101) e o envia à Sefin.

Campo	Tipo	Descrição
`motivo_codigo`	string	`1` erro na emissão · `2` serviço não prestado · `9` outros. Obrigatório
`motivo_texto`	string	Justificativa, de 15 a 255 caracteres. Obrigatório

cURL

curl https://emitra.com.br/api/v1/integracao/nfse/3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84/cancelar \
  -H "Authorization: Bearer $EMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "motivo_codigo": "2", "motivo_texto": "Serviço cancelado pelo cliente antes da execução" }'

Python

r = requests.post(f"{API}/nfse/{nfse_id}/cancelar", headers=H, json={
    "motivo_codigo": "2",
    "motivo_texto": "Serviço cancelado pelo cliente antes da execução",
}, timeout=30)

JavaScript

await fetch(`${API}/nfse/${nfseId}/cancelar`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    motivo_codigo: "2",
    motivo_texto: "Serviço cancelado pelo cliente antes da execução",
  }),
});

PHP

<?php
$ch = curl_init("$api/nfse/$nfseId/cancelar");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode([
        "motivo_codigo" => "2",
        "motivo_texto" => "Serviço cancelado pelo cliente antes da execução",
    ]),
]);
$evento = json_decode(curl_exec($ch), true)["data"];

Resposta 202

{
  "status": "success",
  "message": "Pedido de cancelamento enviado",
  "data": {
    "evento": { "tipo": "101101", "status": "pending" },
    "nfse": { "id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84", "status": "authorized" }
  }
}

Quando a Sefin registrar o evento, a nota passa a canceled e o webhook nfse.canceled é enviado.

Regras:

Só notas authorized podem ser canceladas; outro status responde 409 FISCAL_INVALID_TRANSITION.
Cancelamento e substituição são eventos únicos: uma nota cancelada não pode ser substituída.
Exige assinatura em dia (TENANT_INADIMPLENTE bloqueia).

Substituir uma NFS-e#

POST /integracao/nfse/{id}/substituir → 202 Accepted. Header Idempotency-Key obrigatório.

A substituição emite uma nota nova que corrige a original. Quando a nova é autorizada, a Sefin cancela a original por substituição (e105102), de forma atômica.

O corpo é o mesmo da emissão, mais:

Campo	Tipo	Descrição
`motivo_codigo`	string	`01` desenquadramento do Simples · `02` enquadramento no Simples · `03` inclusão retroativa de imunidade/isenção · `04` exclusão retroativa de imunidade/isenção · `05` rejeição pelo tomador ou intermediário · `99` outros. Obrigatório
`motivo_texto`	string	Justificativa. Obrigatória para `99`

cURL

curl https://emitra.com.br/api/v1/integracao/nfse/3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84/substituir \
  -H "Authorization: Bearer $EMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-2026-11-0001-subst-1" \
  -d '{
    "tomador_id": "5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10",
    "competencia": "2026-11-10",
    "servico": {
      "item_id": "8a3e6d21-4f9b-4b2a-bc17-0e5d9c3a6f42",
      "descricao": "Consultoria em TI - novembro/2026 (horas extras do dia 08 incluídas na descrição)",
      "valor": "1500.00"
    },
    "motivo_codigo": "99",
    "motivo_texto": "Correção da discriminação do serviço"
  }'

Resposta 202

{
  "status": "success",
  "message": "DPS de substituição recebida e enfileirada",
  "data": {
    "id": "e4a1c7b2-3d5f-4a6e-9b8c-1d2e3f4a5b6c",
    "status": "queued",
    "substitui_id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84"
  }
}

Acompanhe a nota nova pelo id devolvido. Ao autorizar, a original muda para replaced e o webhook nfse.replaced é enviado.

Próximos passos#

Esta página foi útil?