Documentação

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.

  1. No painel da empresa, em Configurar emissão, salve o perfil de emissão e instale o certificado A1.
  2. 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).
  3. 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.pdf

Link 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. amount em cada item troca o valor só naquela nota.
  • issue_day (1 a 28) marca o dia da emissão automática. GET /v1/auto-issue mostra 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-123

O 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-types lista 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 devolve service_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, com taker.foreign (NIF ou o motivo de não ter, e o endereço lá fora) e foreign_trade.amount_in_currency. O tipo de nota precisa ter os dados de exportação (a Sefin exige, E0330).
  • Intermediário: intermediary com CPF/CNPJ, nome e address (a Sefin exige o endereço quando o ISS é retido por ele, E0293).
  • Construção civil: construction com o código CNO/CEI, o CIB ou o endereço da obra.
  • Eventos (item 12): event com 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 em supplier).
  • Responsabilidade técnica e pedido: service.technical_document (ART/RRT) e service.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-Key está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/requests e os webhooks cobrem todas as notas da empresa, também as emitidas no painel (campo origin: api, panel, import). Para notas de fora da API, identifique pela access_key; origin=api filtra só as da sua chave. PDF e XML dessas notas saem por /v1/requests/{id}/pdf e /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.