Como a NFS-e Nacional funciona por baixo
Antes de escolher como integrar, vale entender o que a Sefin Nacional pede. Pelo manual oficial de APIs para contribuintes, a emissão é feita enviando uma DPS (Declaração de Prestação de Serviço) em XML para o serviço POST /nfse. A Sefin valida a DPS contra as regras de negócio e devolve, de forma síncrona, a NFS-e gerada ou o motivo da rejeição. A nota pode ser consultada depois pela chave de acesso, e eventos como o cancelamento são registrados em POST /nfse/{chaveAcesso}/eventos.
Para chegar a esse ponto, o seu sistema teria que: montar o XML no leiaute oficial (que vem mudando com a reforma tributária), assinar com o certificado digital da empresa, guardar esse certificado com segurança, controlar a numeração da DPS sem repetir, tratar as dezenas de códigos de rejeição e acompanhar as notas técnicas publicadas pela Sefin. O manual também prevê consultas por município (alíquotas, regimes, retenções) e a consulta da nota pelo identificador da DPS, que é o que permite descobrir se uma nota foi gerada quando a resposta não chegou.
Uma API intermediária como a do WAY NF existe para tirar esse trabalho do seu sistema. Você manda só o que muda em cada nota (tomador, valor, competência, descrição). Prestador, código de serviço, ISS, retenções e IBS/CBS ficam no perfil de emissão da empresa, configurado uma vez no painel com a contabilidade dela.
Visão geral da API do WAY NF
| Item | Como é |
|---|---|
| Endereço base | https://www.waynf.com.br/v1 |
| Autenticação | Authorization: Bearer com a chave criada no painel, em Integrações (API) |
| Ambientes | Chave wnf_test_ emite na homologação da Sefin (sem valor fiscal); chave wnf_live_ emite em produção |
| Empresa | A chave já identifica a empresa e o ambiente. Chave de várias empresas (contador, grupo): o CPF/CNPJ da empresa vai no cabeçalho X-Company-Id |
| Formato | JSON. Valores em reais como texto com ponto e duas casas ("150.00"); datas AAAA-MM-DD; CPF/CNPJ só com dígitos |
| Limite | 300 chamadas por minuto por chave; acima disso, resposta 429 com Retry-After |
| Contrato | OpenAPI 3.1 publicado em /v1/openapi.json, para gerar o cliente no seu sistema |
Toda empresa que usa a API também tem conta no painel: é lá que configura a emissão, instala o certificado A1, cria as chaves e vê todas as notas, inclusive as emitidas pela API, que aparecem marcadas. O seu sistema nunca guarda certificado nem senha, só a chave wnf_, como segredo no servidor. A API e os webhooks estão nos planos a partir do Crescimento; veja planos. A referência completa de campos está na documentação da API.
Emitir uma nota: POST /v1/requests
Uma chamada por nota. Os campos obrigatórios são external_id (o seu identificador, como o id da cobrança), competence, service_amount e payload, com o tomador (name e tax_id) e o serviço (description). O cabeçalho Idempotency-Key também é obrigatório.
export WAYNF_CHAVE="wnf_test_EXEMPLO_FICTICIO_0000"
curl -X POST https://www.waynf.com.br/v1/requests \
-H "Authorization: Bearer $WAYNF_CHAVE" \
-H "Idempotency-Key: cobranca-2026-10-123" \
-H "Content-Type: application/json" \
-d '{
"external_id": "cobranca-2026-10-123",
"competence": "2026-10-30",
"service_amount": "150.00",
"payload": {
"taker": { "name": "Maria da Silva", "tax_id": "12345678909", "email": "maria@exemplo.com" },
"service": { "description": "Mensalidade de outubro" }
}
}'A resposta é 202: o pedido foi aceito e entrou na fila. Com a fila ativa, a nota sai em segundos; o resultado chega por webhook ou por consulta.
{
"id": "cmuh71ozv0001l7044lsugi9f",
"external_id": "cobranca-2026-10-123",
"status": "queued",
"dps_number": "20003",
"status_url": "/v1/requests/cmuh71ozv0001l7044lsugi9f",
"correlation_id": "2a02a63a-0e08-4fd5-8d39-d27ba5b9a4d3"
}O mesmo envio em Node.js, com fetch:
// Node.js 18 ou mais novo (fetch nativo). A chave fica no servidor, nunca no navegador.
const BASE = "https://www.waynf.com.br";
async function emitirNota(cobranca) {
const resposta = await fetch(BASE + "/v1/requests", {
method: "POST",
headers: {
"Authorization": "Bearer " + process.env.WAYNF_CHAVE,
"Idempotency-Key": cobranca.id, // a mesma cobrança nunca vira duas notas
"Content-Type": "application/json",
},
body: JSON.stringify({
external_id: cobranca.id,
competence: cobranca.competencia, // "2026-10-30"
service_amount: cobranca.valor.toFixed(2), // "150.00"
payload: {
taker: { name: cobranca.nome, tax_id: cobranca.cpfCnpj },
service: { description: cobranca.descricao },
},
}),
});
const corpo = await resposta.json();
if (!resposta.ok) {
// corpo.code, corpo.message e corpo.correlation_id (mande este ao suporte)
throw new Error(corpo.code + ": " + corpo.message + " (" + corpo.correlation_id + ")");
}
return corpo; // guarde corpo.id junto da cobrança
}- Tipos de nota: empresa que presta serviços diferentes no mesmo CNPJ cadastra tipos no painel, cada um com o seu código de serviço e ISS. A nota escolhe o tipo em payload.service.type; GET /v1/service-types lista os tipos da empresa. Sem type, vale o serviço padrão do perfil.
- Campos opcionais: endereço e telefone do tomador, descontos, informações complementares, número do pedido, intermediário, obra, evento, tomador no exterior e os grupos do IBS/CBS. Formato errado volta 422 na hora, com a explicação em message.
- IBS/CBS: quando o imposto do serviço vai para o endereço do tomador, ou o serviço é sobre um imóvel, a nota precisa do endereço correspondente (payload.taker.address ou payload.property). Faltando, a resposta é 422 ibs_cbs_required. O guia IBS/CBS na NFS-e explica o contexto.
Idempotência: repetir nunca duplica
Em integração fiscal, o erro mais caro é a nota em dobro: o cliente recebe duas notas, a empresa paga imposto duas vezes e alguém precisa cancelar à mão. Ele quase sempre nasce de um timeout: o seu sistema mandou, a resposta não chegou, e o código tentou de novo.
- Idempotency-Key: use uma chave estável por cobrança (o id dela). Repetir a chamada com a mesma chave e o mesmo corpo devolve o mesmo pedido, sem criar outro.
- Mesma chave, dados diferentes: a resposta é 409. Isso protege contra um bug que reaproveita a chave para outra cobrança.
- external_id: é único por chave de API e serve para achar a nota depois, em GET /v1/requests?external_id=… Se o seu banco perdeu o id do pedido, é por ele que você recupera.
- Nota recusada: corrija o dado e envie um pedido novo, com outra Idempotency-Key (por exemplo, o id da cobrança com um sufixo de tentativa).
Estados da nota e o caso da Sefin sem resposta
| status | O que significa | O que o seu sistema faz |
|---|---|---|
| accepted | Recebido, mas a empresa ainda não terminou de configurar a emissão; message diz o que falta | Avise o cliente para completar a configuração no painel |
| queued | Na fila; sai em segundos | Aguarde o webhook |
| processing | Sendo enviado à Sefin | Aguarde o webhook |
| issued | Nota autorizada; access_key, dps_number, issued_at e pdf_url preenchidos | Grave a chave de acesso na cobrança e mostre "nota emitida" |
| rejected | Recusada; message traz o código e o motivo | Corrija e envie um pedido novo |
| uncertain | A Sefin não respondeu com clareza | Não reenvie. Espere: o WAY NF resolve sozinho |
| cancelled | Cancelada na Sefin (inclusive por substituição) | Marque a cobrança como sem nota válida, ou troque pela substituta |
O estado uncertain é o que separa uma integração robusta de uma frágil. Ele aparece quando a Sefin demora, cai no meio do envio ou devolve uma resposta que não permite saber se a nota foi gerada. Reenviar a mesma DPS nessa hora pode gerar nota duplicada ou uma rejeição confusa. O WAY NF consulta a Sefin pelo identificador da DPS antes de qualquer nova tentativa: se a nota existe, o pedido vira issued; se não existe, ele tenta de novo com segurança. Quando a Sefin está fora do ar, as notas esperam na fila sem se perder e o envio volta sozinho.
Por isso, a regra para o seu código é simples: pedido em uncertain não se reenvia. Espere o webhook ou consulte o pedido mais tarde.
Webhooks assinados
Cadastre um endereço https:// na integração, no painel. O WAY NF chama esse endereço quando a nota é emitida (request.issued), recusada (request.rejected), fica incerta (request.uncertain), é cancelada (request.cancelled) ou tem o cancelamento recusado (request.cancellation_rejected). Responda com qualquer status 2xx; sem isso, o WAY NF tenta de novo com espera crescente, até 8 vezes.
POST https://seu-sistema.exemplo.com/webhooks/way-nf
X-Way-NF-Event-ID: request.issued:cmuh71ozv0001l7044lsugi9f
X-Way-NF-Timestamp: 1793356800000
X-Way-NF-Signature: (HMAC-SHA256 em hexadecimal)
{
"id": "request.issued:cmuh71ozv0001l7044lsugi9f",
"schema_version": "1",
"request_id": "cmuh71ozv0001l7044lsugi9f",
"data": {
"event": "request.issued",
"external_id": "cobranca-2026-10-123",
"status": "issued",
"environment": "test",
"access_key": "(chave de acesso da NFS-e, 50 dígitos)",
"dps_number": "20003",
"issued_at": "2026-10-30T13:47:23.000Z",
"pdf_url": "https://www.waynf.com.br/v1/pdf/(token)"
}
}Cada aviso traz a assinatura HMAC-SHA256 do texto "timestamp.corpo", feita com o segredo mostrado ao ativar o webhook. Confira antes de confiar no conteúdo:
import { createHmac, timingSafeEqual } from "node:crypto";
// corpo: o texto bruto recebido, antes do JSON.parse
function avisoValido(corpo, headers, segredo) {
const ts = headers["x-way-nf-timestamp"];
if (Math.abs(Date.now() - Number(ts)) > 5 * 60 * 1000) return false; // aviso antigo demais
const esperado = createHmac("sha256", segredo).update(ts + "." + corpo).digest("hex");
const recebido = headers["x-way-nf-signature"] || "";
return recebido.length === esperado.length &&
timingSafeEqual(Buffer.from(recebido), Buffer.from(esperado));
}- Calcule a assinatura sobre o corpo bruto, antes de converter para JSON. Reformatar o JSON muda os bytes e a assinatura não bate.
- O mesmo aviso pode chegar mais de uma vez. Use o X-Way-NF-Event-ID para ignorar repetidos.
- O pdf_url abre o PDF sem a chave da API e vale 30 dias: dá para mandar ao tomador por e-mail ou WhatsApp. Quem tiver o link vê a nota, então envie só a ele.
- Como rede de segurança, consulte de tempos em tempos as notas que ainda estão em andamento no seu sistema.
Consultar, baixar, cancelar e substituir
curl "https://www.waynf.com.br/v1/requests/{id}" -H "Authorization: Bearer $WAYNF_CHAVE"
curl "https://www.waynf.com.br/v1/requests?external_id=cobranca-2026-10-123" -H "Authorization: Bearer $WAYNF_CHAVE"
curl "https://www.waynf.com.br/v1/requests/{id}/pdf" -H "Authorization: Bearer $WAYNF_CHAVE" -o nota.pdf
curl "https://www.waynf.com.br/v1/requests/{id}/xml?type=nfse" -H "Authorization: Bearer $WAYNF_CHAVE" -o nota.xmlO XML pode ser da nota autorizada (type=nfse), da declaração enviada (dps) ou do evento de cancelamento (cancellation). Também existe GET /v1/nfse/{chave}/pdf, que gera o PDF de qualquer nota da empresa pela chave de acesso, inclusive notas emitidas fora do WAY NF e importadas da Sefin.
curl -X POST https://www.waynf.com.br/v1/requests/{id}/cancel \
-H "Authorization: Bearer $WAYNF_CHAVE" \
-H "Content-Type: application/json" \
-d '{ "reason_code": 1, "reason": "Valor da mensalidade cobrado errado" }'No cancelamento, reason_code é 1 (erro na emissão), 2 (serviço não prestado) ou 9 (outros), e reason tem de 15 a 255 caracteres. A resposta confirma o pedido; a nota passa a cancelled quando a Sefin registra o evento. Se a Sefin recusar (por exemplo, por prazo do município), a nota segue issued e message explica.
Para corrigir uma nota sem cancelar e emitir de novo, envie a nota certa em POST /v1/requests com o campo replaces (chave de acesso da nota errada, código e motivo). Quando a Sefin autoriza a nova, ela mesma cancela a antiga, e o seu sistema recebe request.cancelled da antiga com replaced_by. No Simples Nacional (ME/EPP), a Sefin não aceita mudar competência, valor nem o CPF/CNPJ do tomador numa substituição. O guia cancelar e substituir NFS-e detalha as regras.
Erros e limites
Toda resposta de erro tem o mesmo corpo: code, message e correlation_id. Registre o correlation_id no seu log: é o que o suporte precisa para achar a chamada.
| HTTP | Quando acontece |
|---|---|
| 400 | JSON ou parâmetros inválidos |
| 401 | Chave ausente, errada ou revogada |
| 403 | A chave não tem a permissão ou o ambiente não bate. Com code payment_overdue (mensalidade vencida) ou production_paused (pico incomum no dia), a produção pausou: não adianta repetir. Passar das notas do plano não trava |
| 404 | Pedido não existe para esta chave |
| 409 | A mesma Idempotency-Key foi usada com outros dados |
| 422 | Dados recusados: valor, data, CPF/CNPJ, motivo de cancelamento, tipo de nota desconhecido, IBS/CBS faltando |
| 429 | Mais de 300 chamadas por minuto; espere o tempo do Retry-After |
Erros 4xx não se resolvem repetindo: corrija o dado. Para 429 e falhas de rede, repita com a mesma Idempotency-Key, com espera crescente.
Homologação primeiro, produção depois
A Sefin Nacional mantém dois ambientes: a produção restrita (homologação, para testes, sem valor fiscal) e a produção. No WAY NF, a chave wnf_test_ emite na homologação e a wnf_live_ só existe depois que a produção da empresa é ativada, o que pede pelo menos uma nota de teste autorizada.
- No painel da empresa, em Configurar emissão, salve o perfil de emissão (com os dados da contabilidade) e instale o certificado A1.
- Em Integrações (API), crie a chave wnf_test_ e cadastre o endereço do webhook.
- Emita notas de teste pelo seu sistema: um CPF, um CNPJ, uma nota recusada de propósito (CPF inválido), um cancelamento e uma substituição.
- Confira se o seu sistema grava o id do pedido e a chave de acesso, se trata o webhook repetido e se não reenvia pedido em uncertain.
- Simule um timeout repetindo a mesma chamada: tem que voltar o mesmo pedido.
- Ative a produção em Configurar emissão, crie a chave wnf_live_ e troque a variável de ambiente do servidor.
Notas de homologação não têm valor fiscal, mas passam pelas mesmas validações da Sefin. É ali que aparecem os problemas de cadastro (código de serviço, IBS/CBS, endereço do tomador) antes que um cliente real receba uma nota errada.
Perguntas frequentes
Meu sistema precisa guardar o certificado digital do cliente?
Não. O certificado A1 fica guardado cifrado no WAY NF e só é aberto na hora de assinar. O seu sistema guarda só a chave da API, como segredo no servidor.
O que faço se a chamada der timeout?
Repita com a mesma Idempotency-Key. O WAY NF devolve o mesmo pedido e nunca emite duas notas para a mesma chave.
O pedido ficou em uncertain. Reenvio?
Não. Uncertain quer dizer que a Sefin não respondeu com clareza. O WAY NF consulta a Sefin pela DPS antes de qualquer nova tentativa e resolve sozinho; o resultado chega por webhook.
Como testo sem emitir nota de verdade?
Use a chave wnf_test_, que emite na homologação da Sefin, sem valor fiscal. Depois de uma nota de teste autorizada, a empresa ativa a produção e cria a chave wnf_live_.
Atendo várias empresas (escolas, filiais, clientes do meu SaaS). Uma chave serve para todas?
Uma chave pode cobrir várias empresas da mesma conta (as escolhidas ou todas, inclusive as que entrarem depois): o seu sistema manda o CPF/CNPJ da empresa no cabeçalho X-Company-Id. Quem prefere separar continua podendo ter uma chave por empresa.
Preciso mandar código de serviço e alíquota em cada nota?
Não. Isso fica no perfil de emissão da empresa. A nota leva tomador, valor, competência e descrição; se a empresa tiver mais de um serviço, payload.service.type escolhe o tipo de nota.
Como sei que o webhook veio mesmo do WAY NF?
Confira o X-Way-NF-Signature: é um HMAC-SHA256 do timestamp e do corpo bruto, feito com o segredo do seu webhook. Recuse avisos com assinatura errada ou timestamp antigo.
Qual plano tem API?
A API e os webhooks estão a partir do plano Crescimento. A lista completa está em planos, na página inicial.
Fontes
- Manual dos Contribuintes: APIs do Emissor Público Nacional (Sefin Nacional NFS-e), v1.2
- NFS-e Nacional: APIs de produção restrita e produção
- NFS-e Nacional: documentação técnica atual (leiautes, esquemas XSD e anexos)
Este guia explica o uso da NFS-e Nacional; não substitui a orientação da sua contabilidade sobre regime, código de serviço e alíquotas.