Emita NFS-e pelo seu sistema
Uma chamada HTTP por nota. O WAY NF monta a DPS com o perfil da empresa, assina com o certificado A1 guardado, envia à Sefin Nacional e avisa o seu sistema quando a nota sai.
Como funciona
O seu sistema continua dono do financeiro (cobranças, pagamentos, alunos, clientes). O WAY NF só transforma "esta cobrança foi paga" em NFS-e na Sefin Nacional.
- 1. Conta no WAY NF
- A empresa cria a conta no painel (login com e-mail). É por ela que você vê todas as notas, inclusive as emitidas pela API, baixa XML e cancela.
- 2. Configurar emissão (uma vez)
- No painel: dados do prestador, código do serviço, tributação e certificado A1. O sistema de vocês nunca precisa saber disso.
- 3. Criar a chave
- Em Integrações (API): uma chave para o seu sistema e, se quiser, o endereço do webhook.
- 4. Seu financeiro chama a API
- Quando uma cobrança é paga (ou quando o usuário clica em "Emitir nota"), o seu sistema manda tomador, valor, competência e descrição.
- 5. O WAY NF emite e avisa
- Em segundos a nota sai na Sefin Nacional; o webhook avisa o seu sistema com a chave de acesso, ou com o motivo da recusa.
- 6. Seu sistema mostra o resultado
- Grave a chave de acesso junto da cobrança e mostre "Nota emitida" ao usuário. Quem preferir pode acompanhar tudo só pelo painel do WAY NF.
Integrar com IA
Usa uma IA para programar (Cursor, Claude Code, Lovable, Bolt)? Copie o texto abaixo e cole no chat dela, dentro do projeto do seu sistema. Ele explica a API, as regras de segurança e o que construir. A IA também pode ler direto em /docs/api/ia.txt.
Você vai integrar este sistema ao WAY NF (emissor de NFS-e Nacional) pela API REST.
Documentação: https://www.waynf.com.br/docs/api — contrato completo: https://www.waynf.com.br/v1/openapi.json (leia antes de escrever código).
REGRAS
- A chave da API (wnf_test_… = homologação, sem valor fiscal; wnf_live_… = produção) fica SÓ no servidor, em
variável de ambiente WAYNF_CHAVE. Nunca no navegador, no repositório ou em log.
- Toda chamada: header "Authorization: Bearer <chave>". Chave de várias empresas: header "X-Company-Id" com o
CPF/CNPJ (só dígitos) ou o id da empresa. GET /v1/companies lista as empresas da chave. O ambiente vem da chave
(X-Fiscal-Environment só se uma chave cobrir os dois).
- Valores em texto com ponto e 2 casas ("150.00"); datas AAAA-MM-DD; CPF/CNPJ só dígitos. Campo que a API não
conhece é recusado (422), nunca ignorado.
- Endereço do tomador: a maioria dos serviços com IBS/CBS exige (o imposto vai para o endereço dele). Mande sempre
que tiver: { "city_code": "<IBGE 7 dígitos>", "postal_code": "<8 dígitos>", "street", "number" (ou "S/N"),
"district", "complement"? }. Sem ele a nota volta com erro dizendo isso.
- Configurar a emissão (prestador, códigos de serviço, impostos, certificado A1) NÃO é pela API: a empresa faz uma
vez no painel do WAY NF. Não tente montar XML, calcular imposto nem guardar certificado.
- Comece com a chave wnf_test_. Só troque para wnf_live_ quando o usuário pedir. Mesmo na homologação a Sefin
confere o CPF/CNPJ do tomador na Receita: CPF inventado volta rejected (E0207). Para ver a nota emitida, teste
com um CPF/CNPJ real (ex.: o do próprio usuário, sem e-mail, para ninguém receber).
EMITIR UMA NOTA (ex.: botão "Emitir nota" numa cobrança paga)
POST https://www.waynf.com.br/v1/requests
Headers: Idempotency-Key = id estável da cobrança (repetir a chamada nunca duplica a nota)
Body: { "external_id": "<id da cobrança>", "competence": "AAAA-MM-DD", "service_amount": "150.00",
"payload": { "taker": { "name": "...", "tax_id": "<CPF/CNPJ>", "email": "...", "address": { ... } },
"service": { "description": "..." } } }
Resposta 202 com "id" e "status". Guarde o "id" na cobrança.
ACOMPANHAR
- GET https://www.waynf.com.br/v1/requests/{id} → status: accepted / queued / processing (em andamento), issued (pronta),
rejected (veja "message"), uncertain (o WAY NF resolve sozinho; NÃO reenvie), cancelled.
- Nota emitida traz access_key, nfse_number e, se foi criada por POST /v1/requests desta chave, pdf_url (link do
PDF para mandar ao cliente, vale 30 dias). Nota de cliente fixo não traz pdf_url: baixe por GET /v1/requests/{id}/pdf.
- Melhor que consultar em loop: webhook (cadastrado no painel, em Integrações). Confira a assinatura
conforme a documentação e ignore eventos repetidos pelo header X-Way-NF-Event-ID.
- PDF: GET /v1/requests/{id}/pdf. XML: GET /v1/requests/{id}/xml?type=nfse.
CANCELAR
POST https://www.waynf.com.br/v1/requests/{id}/cancel { "reason_code": 1, "reason": "<15 a 255 caracteres>" }
(1 erro na emissão, 2 serviço não prestado, 9 outros)
CLIENTES FIXOS (quem recebe nota todo mês: mensalidade, honorários)
- GET/POST https://www.waynf.com.br/v1/recurring-clients — listar / cadastrar
{ "tax_id", "name", "amount": "150.00", "address" (ver acima), "email"?, "phone"?, "description"?,
"issue_day"?: 1-28 ou null, "active"? }
Na descrição, {mes} vira o mês por extenso (ex.: "Honorários de {mes}"). Cadastrar não é idempotente: antes de
repetir um POST que falhou na rede, liste e procure pelo tax_id.
- PATCH / DELETE https://www.waynf.com.br/v1/recurring-clients/{id} — editar (só os campos enviados; null apaga) / remover
- GET https://www.waynf.com.br/v1/recurring-clients/month?competence=AAAA-MM-DD — só os ATIVOS, com a nota de cada um no mês
(competence = qualquer dia do mês, até hoje)
- POST https://www.waynf.com.br/v1/recurring-clients/issue { "competence": "AAAA-MM-DD", "items": [{ "id": "...", "amount"?: "..." }] }
emite as do mês (até 200 por chamada). Uma nota por cliente e mês: chamar de novo devolve a mesma nota,
MENOS quando ela foi recusada ou cancelada: aí cria outra (corrija o motivo antes de repetir). competence =
qualquer dia do mês, até hoje (Brasília). Guarde o request_id de cada item: estas notas são as mesmas do
painel e vêm com origin = "panel" e external_id interno (não filtre por origin=api).
ATENÇÃO: responde 200 mesmo quando um item falha. Confira "error_count" e cada data[].status: "error" = nota
não criada, com "code" (not_found = id errado ou pausado; invalid_request = dado faltando) e "message".
- GET https://www.waynf.com.br/v1/auto-issue — se a emissão automática está ligada (ligar/desligar só no painel).
test_environment = true: a produção da empresa ainda não foi liberada, a automática emite em homologação.
ERROS
Corpo { "code", "message", "correlation_id" }. Mostre "message" ao usuário. 401 chave errada; 403 sem permissão
(ou mensalidade vencida: payment_overdue); 409 mesma Idempotency-Key com outros dados; 422 dado recusado;
429 limite de 300 chamadas/minuto (espere o Retry-After).
ENTREGA
Crie: (1) um módulo cliente do WAY NF no servidor; (2) o botão "Emitir nota" onde fizer sentido, mostrando a
situação e o link do PDF; (3) a rota do webhook atualizando a situação; (4) um teste com a chave wnf_test_.
Pergunte ao usuário antes de criar tabelas ou mudar telas existentes.A configuração da emissão (dados da empresa, impostos e certificado A1) continua no painel do WAY NF: a IA não precisa nem deve mexer nisso.
Conectar o financeiro do seu sistema
Onde cada coisa do seu financeiro entra na API. Exemplo real: o Way School (gestão escolar) emite a nota da mensalidade quando a secretaria clica em "Emitir" numa parcela paga.
- Cobrança/parcela paga
POST /v1/requests com Idempotency-Key = id da cobrança- Responsável financeiro (nome, CPF/CNPJ)
payload.taker.name e payload.taker.tax_id- Valor pago
service_amount ("150.00")- Mês de referência / vencimento
competence (AAAA-MM-DD)- Texto da nota (ex.: mensalidade de setembro, aluno X)
payload.service.description- Situação da nota na tela do seu sistema
webhook (request.issued / rejected / cancelled) ou GET /v1/requests/{id}- Número/chave da nota guardado na cobrança
access_key do webhook- Botão "Cancelar nota"
POST /v1/requests/{id}/cancel- Botão "Corrigir nota" (substituir)
POST /v1/requests com replaces.access_key = chave da nota errada
O que o seu sistema precisa ter: um lugar para guardar a chave (variável de ambiente no servidor), uma coluna para o id/chave da nota em cada cobrança e uma rota que recebe o webhook e confere a assinatura. Nada de certificado, XML ou regra fiscal.
Dúvidas
- Quem usa a API também entra no painel?
- Sim. Toda empresa tem conta no painel: é lá que configura a emissão, cria as chaves e vê todas as notas (as da API aparecem junto, marcadas como API). A API é só o jeito do seu sistema pedir notas sem ninguém digitar.
- Meu sistema precisa guardar certificado ou senha?
- Não. O A1 fica cifrado no WAY NF. O seu sistema guarda só a chave wnf_… (como segredo, no servidor, nunca no navegador).
- E se a chamada der timeout?
- Repita com o mesmo Idempotency-Key. O WAY NF devolve o mesmo pedido e nunca emite duas notas para a mesma chave.
- E se o webhook falhar?
- O WAY NF tenta de novo até 8 vezes. Como rede de segurança, consulte GET /v1/requests?external_id=… das notas que ainda estão em andamento.
- A nota foi recusada. E agora?
- O motivo vem em message (ex.: CPF inválido). Corrija o dado no seu sistema e envie um pedido novo com outro Idempotency-Key.
- Como testo sem emitir nota de verdade?
- Use a chave wnf_test_: emite em homologação da Sefin, sem valor fiscal. Com uma nota de teste autorizada, você ativa a produção em Configurar emissão e cria a chave wnf_live_.
- Posso emitir para várias empresas (CNPJs)?
- Sim. Crie uma chave que cubra as empresas escolhidas ou todas as da conta e mande o CPF/CNPJ da empresa no cabeçalho X-Company-Id em cada chamada. Também dá para ter uma chave por empresa.
Começar em 3 passos
Contrato da API em OpenAPI (JSON), para gerar o cliente no seu sistema.
- No painel da empresa, em Configurar emissão, salve o perfil de emissão e instale o certificado A1.
- Em Integrações (API), crie uma chave.
wnf_test_…emite em homologação (sem valor fiscal);wnf_live_…emite de verdade e só existe depois que a produção da empresa é ativada (em Configurar emissão, após uma nota de teste autorizada). - Envie as notas com
Authorization: Bearer <chave>. A chave já identifica a empresa e o ambiente. Se ela cobre várias empresas, veja Várias empresas.
Emitir — POST /v1/requests
Você manda só o que muda em cada nota: tomador, valor, competência e descrição. Prestador, códigos de serviço e tributação vêm do perfil da empresa.
curl -X POST https://www.waynf.com.br/v1/requests \
-H "Authorization: Bearer $WAYNF_CHAVE" \
-H "Idempotency-Key: cobranca-2026-09-123" \
-H "Content-Type: application/json" \
-d '{
"external_id": "cobranca-2026-09-123",
"competence": "2026-09-25",
"service_amount": "150.00",
"payload": {
"taker": { "name": "Maria da Silva", "tax_id": "12345678909", "email": "maria@exemplo.com" },
"service": { "description": "Mensalidade de setembro" }
}
}'Resposta 202. Com a fila ativa a nota sai em segundos: acompanhe por consulta ou webhook.
{
"id": "cmuh71ozv0001l7044lsugi9f",
"external_id": "cobranca-2026-09-123",
"status": "queued",
"dps_number": "20003",
"status_url": "/v1/requests/cmuh71ozv0001l7044lsugi9f",
"correlation_id": "2a02a63a-0e08-4fd5-8d39-d27ba5b9a4d3"
}Node.js
const resp = await fetch("https://www.waynf.com.br/v1/requests", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.WAYNF_CHAVE}`,
"Idempotency-Key": cobranca.id, // repetir não duplica a nota
"Content-Type": "application/json",
},
body: JSON.stringify({
external_id: cobranca.id,
competence: "2026-09-25",
service_amount: cobranca.valor.toFixed(2), // "150.00"
payload: { taker: { name: aluno.responsavel, tax_id: aluno.cpf }, service: { description: "Mensalidade de setembro" } },
}),
});
const pedido = await resp.json(); // pedido.status: "queued" | "issued" | ...Python
import os, requests
resp = requests.post(
"https://www.waynf.com.br/v1/requests",
headers={"Authorization": f"Bearer {os.environ['WAYNF_CHAVE']}", "Idempotency-Key": cobranca_id},
json={
"external_id": cobranca_id,
"competence": "2026-09-25",
"service_amount": "150.00",
"payload": {"taker": {"name": "Maria da Silva", "tax_id": "12345678909"},
"service": {"description": "Mensalidade de setembro"}},
},
timeout=30,
)
pedido = resp.json()Consultar e baixar XML e PDF
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-09-123" -H "Authorization: Bearer $WAYNF_CHAVE"
curl "https://www.waynf.com.br/v1/requests/{id}/xml?type=nfse" -H "Authorization: Bearer $WAYNF_CHAVE" -o nota.xml
curl "https://www.waynf.com.br/v1/requests/{id}/pdf" -H "Authorization: Bearer $WAYNF_CHAVE" -o nota.pdf
# PDF de qualquer nota da empresa pela chave de acesso (inclusive importadas da Sefin)
curl "https://www.waynf.com.br/v1/nfse/{chave}/pdf" -H "Authorization: Bearer $WAYNF_CHAVE" -o nota.pdfLink do PDF para o tomador: com a nota emitida (ou cancelada), a consulta e o webhook trazem pdf_url. Esse endereço abre o PDF no navegador sem a chave da API: mande ao seu cliente por WhatsApp ou e-mail, ou ponha num botão. Vale 30 dias (cada consulta gera um novo) e para de abrir se a integração for revogada. Quem tiver o link vê a nota, então envie só ao tomador.
type do XML: nfse (nota autorizada), dps (declaração enviada) ou cancellation (evento de cancelamento). O cabeçalho X-Content-SHA256 traz o hash para conferência.
Cancelar — POST /v1/requests/{id}/cancel
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" }'reason_code: 1 erro na emissão, 2 serviço não prestado, 9 outros. reason: 15 a 255 caracteres. A resposta traz cancellation: "requested"; a situação vira cancelled quando a Sefin registra. Recusa (ex.: prazo vencido) mantém issued com message.
Substituir — POST /v1/requests com replaces
Para corrigir uma nota já emitida (descrição, dados do tomador e, fora do Simples ME/EPP, valor e data) sem cancelar e emitir de novo: envie a nota certa com replaces apontando a chave da errada. Quando a Sefin autoriza a nova, ela mesma cancela a antiga.
curl -X POST https://www.waynf.com.br/v1/requests \
-H "Authorization: Bearer $WAYNF_CHAVE" \
-H "Idempotency-Key: cobranca-2026-09-123-correcao" \
-H "Content-Type: application/json" \
-d '{
"external_id": "cobranca-2026-09-123-correcao",
"competence": "2026-09-25",
"service_amount": "135.00",
"replaces": {
"access_key": "33045572112223330001810000000000004226090000000001",
"reason_code": "99",
"reason": "Valor da mensalidade cobrado errado"
},
"payload": {
"taker": { "name": "Maria da Silva", "tax_id": "12345678909" },
"service": { "description": "Mensalidade de setembro" }
}
}'reason_code: 01 saiu do Simples, 02 entrou no Simples, 03 imunidade/isenção incluída depois, 04 imunidade/isenção retirada depois, 05 tomador (ou intermediário) rejeitou a nota, 99 outros. reason: 15 a 255 caracteres. A nota antiga precisa estar emitida, ser da mesma empresa e ambiente e não ter cancelamento em andamento; uma substituta por vez. Se a Sefin recusar a nova, a antiga continua valendo. A antiga passa a cancelled e o seu sistema recebe request.cancelled dela com replaced_by (a nota que vale agora: chave, valor, competência, número, data); a nova traz replaces na consulta. A substituição também pode ser feita no painel do WAY NF, inclusive de nota que o seu sistema emitiu: aí replaced_by traz os dados da nota e o PDF sai por GET /v1/nfse/{chave}/pdf. Ao receber esse aviso, troque a nota na cobrança, para ninguém emitir outra para a mesma cobrança. Simples Nacional ME/EPP: a Sefin não deixa mudar competence, service_amount nem o CPF/CNPJ do tomador na substituição (código E0063); o WAY NF recusa antes de enviar. Para mudar esses dados, cancele e emita outra. Recusas: 422 replacement_refused ou 409 replacement_in_progress.
Clientes fixos — /v1/recurring-clients
Para quem cobra todo mês o mesmo cliente (escola, contador, academia): cadastre os clientes fixos e emita as notas do mês numa chamada. É o mesmo cadastro da aba Clientes do painel: o que o seu sistema cadastra aparece lá, e vice-versa.
# Cadastrar quem recebe nota todo mês
curl -X POST https://www.waynf.com.br/v1/recurring-clients \
-H "Authorization: Bearer $WAYNF_CHAVE" -H "Content-Type: application/json" \
-d '{ "tax_id": "12345678909", "name": "Maria da Silva", "amount": "450.00",
"description": "Honorários contábeis de {mes}", "email": "maria@exemplo.com",
"address": { "city_code": "3304557", "postal_code": "22290030", "street": "Rua Exemplo",
"number": "10", "district": "Botafogo" } }'
# Quem já tem nota no mês
curl "https://www.waynf.com.br/v1/recurring-clients/month?competence=2026-11-05" -H "Authorization: Bearer $WAYNF_CHAVE"
# Emitir as do mês (até 200 por chamada; repetir não duplica, mas nota recusada libera outra)
curl -X POST https://www.waynf.com.br/v1/recurring-clients/issue \
-H "Authorization: Bearer $WAYNF_CHAVE" -H "Content-Type: application/json" \
-d '{ "competence": "2026-11-05", "items": [{ "id": "<id do cliente fixo>" }] }'- Uma nota por cliente e mês, valendo para a API e o painel juntos: se o painel (ou a emissão automática) já emitiu, a API recebe a mesma nota em vez de emitir outra. Só nota recusada ou cancelada libera outra no mês.
- Na descrição,
{mes}vira o mês por extenso.amountem cada item troca o valor só naquela nota. issue_day(1 a 28) marca o dia da emissão automática.GET /v1/auto-issuemostra se ela está ligada e as próximas rodadas; ligar e desligar só no painel, porque pede o aceite de uma pessoa.- Cadastrar, editar, remover e emitir pedem chave com permissão de emitir; listar e ver o mês, de consultar. Cada nota segue em
GET /v1/requests/{id}e no webhook.
Webhooks
Cadastre um endereço https:// na integração. O WAY NF chama esse endereço quando a nota é emitida, recusada, fica incerta, é cancelada ou tem o cancelamento recusado. Responda com qualquer 2xx; sem isso, tentamos de novo com espera crescente (até 8 vezes). O mesmo aviso pode chegar mais de uma vez: use X-Way-NF-Event-ID para ignorar repetidos.
POST https://seu-sistema.com/webhooks/way-nf
X-Way-NF-Event-ID: request.issued:cmuh71ozv0001l7044lsugi9f
X-Way-NF-Timestamp: 1790354843000
X-Way-NF-Signature: 5f1c…(hex)
{
"id": "request.issued:cmuh71ozv0001l7044lsugi9f",
"schema_version": "1",
"request_id": "cmuh71ozv0001l7044lsugi9f",
"data": {
"event": "request.issued",
"company_id": "cmh2r8k1x0003l704a1b2c3d4",
"company_tax_id": "11222333000181",
"external_id": "cobranca-2026-09-123",
"status": "issued",
"environment": "test",
"access_key": "33045572211222333000181000000000000926097606683075",
"dps_number": "20003",
"issued_at": "2026-09-25T16:47:23.000Z",
"pdf_url": "https://www.waynf.com.br/v1/pdf/cmuh71ozv0001l7044lsugi9f.1793032043.Qm9h…"
}
}Confira a assinatura com o segredo mostrado ao ativar o webhook:
import { createHmac, timingSafeEqual } from "node:crypto";
// corpo = texto bruto recebido (antes de JSON.parse)
function avisoValido(corpo, headers, segredo) {
const ts = headers["x-way-nf-timestamp"];
if (Math.abs(Date.now() - Number(ts)) > 5 * 60_000) return false; // evita reenvio antigo
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));
}Várias empresas com uma chave
Contador, grupo de empresas ou sistema que atende vários clientes: ao criar a chave em Integrações, escolha Esta e outras que eu escolher ou Todas as empresas da conta. A opção "todas" inclui sozinha as empresas cadastradas depois. Chave wnf_live_… vale só nas empresas com a produção ativada; quando a produção de outra empresa liga, uma chave "todas" passa a valer nela também.
Em cada chamada, diga de qual empresa é a nota no cabeçalho X-Company-Id, com o CPF/CNPJ dela (só dígitos) ou o id. Sem esse cabeçalho, a chave de várias empresas responde 400 invalid_scope. GET /v1/companies lista as empresas que a chave cobre.
GET /v1/companies
Authorization: Bearer wnf_live_…
{ "data": [
{ "id": "cmh2…", "name": "Clínica Exemplo", "tax_id": "11222333000181",
"environment": "PRODUCTION", "can_create": true, "can_read": true }
] }
POST /v1/requests
Authorization: Bearer wnf_live_…
X-Company-Id: 11222333000181
Idempotency-Key: cobranca-2026-11-123O webhook traz company_id e company_tax_id em data, para o seu sistema saber de qual empresa é cada aviso. O limite de 300 chamadas por minuto é da chave, somando todas as empresas.
Situações da nota
accepted- Recebido, mas a empresa ainda não configurou a emissão (message explica o que falta).
queued- Na fila; sai em segundos.
processing- Sendo enviado à Sefin.
issued- Nota autorizada: access_key, dps_number, issued_at e pdf_url preenchidos; em produção, official_url abre a nota no portal nacional.
rejected- Recusada pela Sefin; message traz o código e o motivo. Corrija e envie um pedido novo.
uncertain- A Sefin não respondeu com clareza. O WAY NF consulta sozinho e resolve; não reenvie.
cancelled- Cancelada na Sefin.
Erros
Corpo: { "code", "message", "correlation_id" }. Mande o correlation_id ao suporte.
- 400
- JSON ou parâmetros inválidos; chave cobre mais de uma empresa sem X-Company-Id.
- 401
- Chave ausente, errada ou revogada.
- 403
- A chave não tem essa permissão (emitir ou consultar) ou o ambiente não bate. Com code payment_overdue: a mensalidade está vencida e a produção pausou até o pagamento; com production_paused: a empresa teve um pico incomum de notas no dia e a Way precisa liberar. Passar das notas do plano não trava a emissão: as extras são cobradas no mês seguinte.
- 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…).
- 429
- Mais de 300 chamadas por minuto; espere o Retry-After.
Campos opcionais da nota
Tributação (ISS, PIS/COFINS, retenções de INSS/IRRF/CSLL, benefício municipal, total de tributos) fica no perfil de emissão da empresa, em percentual: o WAY NF calcula os valores de cada nota. Por nota, o seu sistema pode mandar:
"payload": {
"taker": {
"name": "Empresa Tomadora Ltda", "tax_id": "11222333000181",
"phone": "21999998888",
"municipal_registration": "1234567",
"address": { "city_code": "3304557", "postal_code": "20040002", "street": "Av. Rio Branco",
"number": "1", "complement": "sala 2", "district": "Centro" }
},
"service": {
"description": "Consultoria de setembro",
"additional_info": "Contrato 12/2026. Pagamento via Pix.",
"order_number": "PED-9",
"reference_document": "Contrato 12/2026"
},
"amounts": { "unconditional_discount": "100.00", "conditional_discount": "20.00", "deduction": "0.00" }
}Tudo é opcional. Se um campo vier fora do padrão, a resposta é 422 com a explicação em message.
Tipos de nota — service.type
Empresa que emite serviços diferentes pelo mesmo CNPJ (ex.: imobiliária com administração de aluguel e comissão de venda) cadastra um tipo de nota para cada um no painel (Configurar emissão → Tipos de nota). Cada tipo tem o seu código de serviço, ISS e federais; prestador, série e numeração são os do perfil.
"service": { "description": "Comissão de venda do apto 302", "type": "comissao_venda" }- Sem
type(ou"padrao"), a nota sai com o serviço padrão do perfil: nada muda para quem não usa tipos. GET /v1/service-typeslista os tipos da empresa no ambiente da chave:code,name, código de serviço e ISS de cada um.- Código que a empresa não cadastrou:
422 unknown_service_type, com os códigos válidos na mensagem. A consulta do pedido devolveservice_type.
IBS/CBS (reforma tributária)
A Sefin passou a exigir o IBS/CBS nas notas com competência a partir de 01/10/2026 (hoje na homologação; a produção vira em seguida). Os códigos do serviço (indicador da operação, CST e classificação) ficam no perfil de emissão da empresa, e a Sefin calcula os valores. Por nota, o seu sistema só manda o que o serviço exige:
- Serviço sobre imóvel (administração, corretagem…): o endereço do imóvel em
payload.property. - Imposto no endereço do tomador (a maioria dos serviços): o endereço do tomador em
payload.taker.address.
"property": { "city_code": "3304557", "postal_code": "22041001", "street": "Rua Barata Ribeiro",
"number": "100", "complement": "apto 302", "district": "Copacabana" }Nos dois endereços, city_code (IBGE) é opcional quando vem o postal_code: o WAY NF completa pelo CEP. Faltou o que o serviço exige: 422 ibs_cbs_required, com a explicação em message.
Situações menos comuns vão em payload.ibs_cbs: consumo pessoal (final_consumer), ente público adquirente (government_entity), notas do pagamento antecipado (referenced_invoices, obrigatório com tipo de operação 2 ou 3), destinatário diferente do tomador (recipient), locação (lease, property_adjustments, extra_units) e bens móveis locados (movable_goods). Detalhes no OpenAPI.
Serviços com dados especiais
Todos os grupos do leiaute nacional estão disponíveis. O que se repete fica no tipo de nota; por nota vai só o que muda:
- Tomador no exterior: sem
tax_id, comtaker.foreign(NIF ou o motivo de não ter, e o endereço lá fora) eforeign_trade.amount_in_currency. O tipo de nota precisa ter os dados de exportação (a Sefin exige, E0330). - Intermediário:
intermediarycom CPF/CNPJ, nome eaddress(a Sefin exige o endereço quando o ISS é retido por ele, E0293). - Construção civil:
constructioncom o código CNO/CEI, o CIB ou o endereço da obra. - Eventos (item 12):
eventcom nome, datas e o código da prefeitura ou o endereço. - Dedução por documentos:
amounts.deduction_documents(ex.: repasse a outros corretores, tipo 101, com a chave da NFS-e do corretor e o endereço dele emsupplier). - Responsabilidade técnica e pedido:
service.technical_document(ART/RRT) eservice.order_items.
Formato errado volta 422 na hora. As regras da Sefin (obra só em construção civil, evento só no item 12, dedução no Simples só em alguns serviços) o WAY NF confere antes de enviar. Se não passar, o pedido fica rejected com a explicação em message, sem ir à Sefin.
Regras importantes
- Idempotência: use um
Idempotency-Keyestável por cobrança (ex.: o id dela). Repetir a chamada por timeout nunca gera nota duplicada. - Mesmas notas no painel e no seu sistema:
GET /v1/requestse os webhooks cobrem todas as notas da empresa, também as emitidas no painel (campoorigin:api,panel,import). Para notas de fora da API, identifique pelaaccess_key;origin=apifiltra só as da sua chave. PDF e XML dessas notas saem por/v1/requests/{id}/pdfe/xml. - external_id é único por chave: serve para achar a nota depois (
GET /v1/requests?external_id=…). - Valores em reais como texto com ponto e duas casas (
"150.00"); CPF/CNPJ só com dígitos. - Limite de 300 chamadas por minuto por chave.
X-Company-Id(CPF/CNPJ ou id da empresa): obrigatório só na chave de várias empresas.X-Fiscal-Environment: opcional, o prefixo da chave já diz o ambiente.