API de integração — emissão de NFS-e

Visão geral

Cada empresa tem as suas chaves de API (em Configurações → Integração via API). A nota é emitida com o certificado, o ambiente e os dados da empresa dona da chave; uma chave nunca acessa dados de outra empresa.

• Base: https://e-nfse.com.br/api/v1 (somente HTTPS)
• Formato: JSON (Content-Type: application/json), codificação UTF-8
• Emissão síncrona: a resposta do POST /nfse já traz o resultado (número, chave e links) ou a rejeição da SEFIN
• Limite: 120 requisições por minuto por chave (429 com Retry-After se exceder)

Autenticação

Envie a chave no cabeçalho Authorization. Guarde-a como segredo (não a coloque em código público nem em aplicativos de celular/navegador).

Authorization: Bearer enfse_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Também é aceito o cabeçalho X-API-Key: enfse_... (só a chave, sem Bearer). Chave ausente, inválida, revogada ou de empresa desativada retorna 401; chamada sem HTTPS, 403 https_obrigatorio; plano sem acesso à API, 403 plano_sem_api.

Endpoints

Emitir uma NFS-e — POST /nfse

O mínimo é o seu identificador do pedido, o tomador e o serviço:

curl -X POST https://e-nfse.com.br/api/v1/nfse \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "pedido-12345",
    "tomador": { "cpf_cnpj": "217.981.762-20", "nome": "Antonio Brito Lima" },
    "servico": {
      "descricao": "Serviço de suporte técnico em informática",
      "valor": 150.00,
      "codigo_tributacao_nacional": "01.07.01"
    }
  }'

Com tomador pessoa jurídica (endereço obrigatório), código municipal, desconto e retenções:

{
  "external_id": "pedido-12346",
  "tomador": {
    "cpf_cnpj": "11.222.333/0001-81",
    "nome": "Cliente Exemplo Ltda",
    "email": "financeiro@cliente.com.br",
    "telefone": "(92) 99999-2222",
    "endereco": {
      "cep": "69082-551", "logradouro": "Rua Exemplo", "numero": "29",
      "bairro": "Coroado", "codigo_ibge": "1302603"
    }
  },
  "servico": {
    "descricao": "Suporte técnico - setembro/2026",
    "valor": 1000.00,
    "desconto": 100.00,
    "codigo_tributacao_nacional": "01.07.01",
    "codigo_municipal": "100",
    "pedido": "PED-98765"
  },
  "retencao_iss": true,
  "aliquota_iss": 2.5,
  "retencoes_federais": { "irrf": 1.5, "csll": 1, "pis": 0.65, "cofins": 3, "inss": 11 }
}

Campos

Retenções

Os valores retidos são calculados sobre o valor do serviço menos o desconto e vão no leiaute da DPS (tpRetISSQN/pAliq do ISS; vRetIRRF, vRetCSLL, vRetCP e o grupo PIS/COFINS com o tipo de retenção). A resposta traz os valores em retencoes (R$; 0.0 quando não há). No segundo exemplo acima (valor 1.000,00, desconto 100,00, base 900,00), para uma ME/EPP:

"retencoes": { "iss": 22.5, "irrf": 13.5, "csll": 9.0, "pis": 5.85, "cofins": 27.0, "inss": 99.0 }

Para MEI com retencao_iss: true, a nota sai como retida pelo tomador, sem alíquota, e retencoes.iss é 0.0.

O que vem do cadastro (não envie)

• Prestador: CNPJ, inscrição municipal (a registrada no CNC NFS-e do ambiente), município e regime (MEI, ME ou EPP) vêm do cadastro da empresa dona da chave; o nome e o endereço do prestador a SEFIN completa pelo cadastro dela.
• Ambiente (homologação ou produção), série e número da DPS.
• Data de emissão e competência: o dia do envio à SEFIN (no modo assíncrono, o do processamento da fila).
• Local da prestação: o município da empresa. ISS sempre tributável (imunidade, exportação e não incidência não são emitidas pela API) e sem deduções.

Cadastro do tomador

Cada emissão cria ou atualiza o tomador no cadastro de clientes da empresa (pelo CPF/CNPJ) com os campos informados. Campos omitidos mantêm o que já está no cadastro e também vão na nota (por exemplo, o e-mail ou o telefone cadastrados no painel, ou o endereço de um tomador com CPF). Tomador com CNPJ precisa do endereço completo em toda emissão. Um município novo informado substitui o anterior.

Código de tributação municipal

Cada prefeitura define um código de 3 dígitos para cada serviço (em Manaus, 01.03.01 → 100 e 01.03.02 → 200; em São Paulo, 01.07.01 → 001 ou 002) e a SEFIN recusa (E0314) um código que o município não administra. O sistema consulta a base nacional de parâmetros municipais e guarda o resultado; por isso:

• Código informado e inexistente no município: a nota não é criada e a resposta é 422 com "erro": "codigo_municipal_invalido" e, em detalhes[0].codigos_validos, os códigos que existem.
• Código omitido e município com um único código para o serviço: ele é preenchido automaticamente (igual ao portal nacional), exceto 000 (que significa "sem desdobro").
• Código omitido e município com vários códigos: a nota é emitida sem código municipal e a resposta traz "avisos": [...]. Informe o código desejado para escolher um.
• Base nacional indisponível (ou município sem parâmetros): a emissão segue normalmente e a SEFIN decide. MEI não tem o código conferido pela SEFIN, então nada é bloqueado.
• Menos de 3 dígitos são completados com zeros à esquerda ("1" → "001").

Para saber os códigos antes de emitir: GET /codigos-municipais?codigo_tributacao_nacional=010701. A primeira consulta de um serviço pode levar alguns segundos; as seguintes vêm do catálogo.

{
  "municipio": { "ibge": "1302603", "nome": "Manaus", "uf": "AM" },
  "codigo_tributacao_nacional": "010701",
  "situacao": "encontrado",
  "validacao_ativa": true,
  "codigos_municipais": [ { "codigo": "100", "aliquota": 5.0 } ],
  "sugerido": "100",
  "motivo": null
}

situacao: encontrado, nao_encontrado (nenhum código nas combinações mais comuns; o serviço pode não usar código municipal), indisponivel (veja motivo), mei ou sem_municipio.

Resposta de sucesso — 201 Created

{
  "id": 42,
  "external_id": "pedido-12345",
  "status": "emitida",
  "valor": 150.0,
  "retencoes": { "iss": 0.0, "irrf": 0.0, "csll": 0.0, "pis": 0.0, "cofins": 0.0, "inss": 0.0 },
  "numero_dps": "31",
  "serie_dps": "1",
  "origem": "e-nfse",
  "criada_em": "2026-09-30T14:20:11-03:00",
  "nfse": {
    "numero": "74",
    "chave": "13026032204038227000187000000000007426093101234567",
    "data_emissao": "2026-09-30T14:20:12-03:00",
    "ambiente": "producao"
  },
  "links": {
    "danfse": "https://e-nfse.com.br/d/AbCd...",
    "xml": "https://e-nfse.com.br/x/AbCd...",
    "consulta_publica": "https://www.nfse.gov.br/ConsultaPublica?tpc=1&chave=..."
  }
}

valor é o valor bruto do serviço. Quando houver, vem também "avisos": [...] (por exemplo, código municipal não escolhido). Os links danfse e xml são públicos (não pedem login) e difíceis de adivinhar: podem ser enviados ao cliente por e-mail. Para conferir os demais dados emitidos, use GET /nfse/{id}/xml.

Repetindo a chamada (idempotência)

Se você repetir o POST com o mesmo external_id de uma nota já emitida, recebe 200 com a mesma nota e "ja_emitida": true — sem emitir outra e sem alterar nada, mesmo que o corpo seja diferente. É seguro repetir em caso de timeout de rede, mesmo que depois o certificado tenha vencido. Os dados do corpo são conferidos antes dessa verificação: repita com o mesmo corpo da primeira chamada.

Rejeição pela SEFIN

{
  "id": 43,
  "external_id": "pedido-12347",
  "status": "erro",
  "valor": 150.0,
  "retencoes": { "iss": 0.0, "irrf": 0.0, "csll": 0.0, "pis": 0.0, "cofins": 0.0, "inss": 0.0 },
  "numero_dps": "32",
  "serie_dps": "1",
  "origem": "e-nfse",
  "criada_em": "2026-09-30T14:21:40-03:00",
  "nfse": null,
  "links": null,
  "erros": [
    { "codigo": "E0314", "descricao": "O código de tributação municipal informado não existe ...", "complemento": "" }
  ],
  "mensagem": "E0314: O código de tributação municipal informado não existe ..."
}

O corpo é a própria nota e o HTTP indica o tipo de falha: 422 (a SEFIN rejeitou; status erro com erros), 502 (falha de comunicação ou erro interno da SEFIN; status erro) ou 409 (a mesma nota já estava sendo enviada por outra chamada; consulte em instantes). A nota fica salva. Corrija os dados e envie o mesmo external_id novamente: a mesma nota (mesmo número de DPS) é atualizada e reenviada, inclusive se a correção for o tomador. Nota cancelada não pode ser reenviada (422 dados_invalidos). Se o envio foi interrompido (a nota ficou em processando por mais de 10 minutos), reenviar com o mesmo external_id retoma a mesma nota.

Emissão em massa: modo assíncrono (fila) — 202 Accepted

Cada emissão direta (201) mantém a sua conexão aberta por alguns segundos enquanto a SEFIN responde. Para lotes grandes (centenas de notas de uma vez), peça o modo assíncrono: a nota é validada e gravada, a resposta é imediata (202) e a emissão acontece em segundo plano, uma nota por empresa por vez, em ordem de chegada. Isso protege o seu lote e o serviço: nenhuma empresa consegue travar as outras.

curl -X POST https://e-nfse.com.br/api/v1/nfse \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{ "external_id": "pedido-12345", ... }'      # ou, no corpo: "assincrono": true

HTTP/1.1 202 Accepted
Location: https://e-nfse.com.br/api/v1/nfse/42
Retry-After: 5
Preference-Applied: respond-async

{
  "id": 42,
  "external_id": "pedido-12345",
  "status": "na_fila",
  "valor": 150.0,
  "retencoes": { ... },
  "numero_dps": "31",
  "serie_dps": "1",
  "origem": "e-nfse",
  "criada_em": "2026-09-30T14:20:11-03:00",
  "nfse": null,
  "links": null,
  "posicao_na_fila": 7,
  "mensagem": "NFS-e recebida e na fila de emissão. Consulte o andamento em GET /api/v1/nfse/42."
}

Acompanhe com GET /nfse/{id} (ou GET /nfse?external_id=...) a cada poucos segundos: o status vai de na_fila para processando e termina em emitida (com nfse e links) ou erro (com erros; reenvie o mesmo external_id depois de corrigir). GET /nfse?status=na_fila lista o que ainda aguarda. Repetir o POST com o mesmo external_id de uma nota que ainda está na fila devolve 202 com "ja_na_fila": true, sem duplicar (com ou sem o modo assíncrono).

• Na entrada são conferidos os dados, o cadastro da empresa, o certificado e a situação da assinatura: problemas voltam na hora (400, 402, 422). O limite de notas do plano é conferido a cada emissão: num lote maior que o saldo do mês, as notas além do limite terminam em erro com o código limite_notas. Se a assinatura for bloqueada enquanto a nota espera, ela também termina em erro com o motivo.
• A fila de cada empresa tem um teto (1.000 notas por padrão): acima dele a API responde 429 fila_cheia com Retry-After. Envie o resto depois que parte da fila for emitida.
• No modo síncrono (sem o cabeçalho), se houver emissões demais em andamento para a empresa ou no servidor, a API responde 429 (muitas_emissoes_simultaneas ou servidor_ocupado) com Retry-After: aguarde e repita, ou passe a usar o modo assíncrono.

Enviar a nota ao cliente — POST /nfse/{id}/enviar

Envia a NFS-e já emitida ao tomador por e-mail e/ou WhatsApp, usando o e-mail e a Z-API da própria empresa, configurados no painel em Configurações → Envio da NFS-e ao cliente (e-mail pelo Google com senha de app, ou outro SMTP). O cliente recebe os links do DANFSe e do XML (e o XML anexado, no e-mail).

O envio também pode ser automático: com a opção ligada no painel, toda nota de produção emitida (pelo painel ou pela API, inclusive no modo assíncrono) é enviada ao tomador em até 1 minuto, usando o e-mail e o telefone do cadastro do tomador (atualizados com os dados informados na emissão; para o WhatsApp, um celular já cadastrado tem preferência sobre um telefone fixo). Notas de homologação não são enviadas automaticamente.

curl -X POST https://e-nfse.com.br/api/v1/nfse/42/enviar \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "canais": ["email", "whatsapp"], "email": "outro@cliente.com.br", "telefone": "(92) 99999-2222" }'

Todos os campos são opcionais e o corpo pode ser omitido: sem canais tenta e-mail e WhatsApp; email e telefone valem só para este envio (sem eles, usa os do cadastro do tomador). Se enviar corpo, ele precisa ser application/json (senão 415) com até 4 KB.

{
  "enviados": ["email"],
  "resultados": {
    "email":    { "ok": true,  "destino": "outro@cliente.com.br", "mensagem": "E-mail enviado para outro@cliente.com.br." },
    "whatsapp": { "ok": false, "destino": "5592999992222", "mensagem": "WhatsApp não configurado: informe a Z-API da empresa em Configurações." }
  }
}

Resposta 200 se pelo menos um canal enviou; 422 com "erro": "envio_falhou" e resultados (o motivo de cada canal) se nenhum enviou; 409 (nao_emitida) se a nota ainda não foi autorizada; 404 se a nota não existe. Há um limite de envios por dia por empresa e um intervalo de 1 minuto para repetir o mesmo destino.

Códigos de resposta

Corpo de erro padrão: {"erro": "codigo", "mensagem": "texto", "detalhes": [...]} (detalhes só aparece quando há itens: [{campo, mensagem}] na validação, com codigos_validos no código municipal). Falhas de envio à SEFIN devolvem a própria nota, com status erro e erros.

Exemplos

PHP

$ch = curl_init('https://e-nfse.com.br/api/v1/nfse');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NFSE_CHAVE'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'external_id' => 'pedido-' . $pedidoId,
        'tomador' => ['cpf_cnpj' => $cpf, 'nome' => $nome],
        'servico' => ['descricao' => 'Mensalidade', 'valor' => 99.90, 'codigo_tributacao_nacional' => '010701'],
    ]),
    CURLOPT_TIMEOUT => 60,
]);
$resposta = json_decode(curl_exec($ch), true);
$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($http === 201 || $http === 200) { /* $resposta['links']['danfse'] */ }

Node.js

const r = await fetch('https://e-nfse.com.br/api/v1/nfse', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.NFSE_CHAVE}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    external_id: `pedido-${pedido.id}`,
    tomador: { cpf_cnpj: pedido.cpf, nome: pedido.nome },
    servico: { descricao: 'Mensalidade', valor: 99.9, codigo_tributacao_nacional: '010701' },
  }),
});
const nota = await r.json(); // r.status === 201 => nota.links.danfse

Boas práticas

• Para emitir em massa, use o modo assíncrono (Prefer: respond-async) e consulte o andamento depois; evite disparar centenas de chamadas síncronas ao mesmo tempo.
• Use sempre um external_id estável por pedido (por exemplo, o ID do pagamento) e repita a chamada em caso de timeout ou erro 5xx: não há risco de duplicar a nota.
• Emita a nota depois da confirmação do pagamento e guarde o nfse.chave e os links.
• Acompanhe o vencimento do certificado digital da empresa (GET /me mostra a validade) — com ele vencido nenhuma nota é emitida.
• Mantenha a chave em segredo e revogue-a no painel se suspeitar de vazamento.