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 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": "", "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": "", "competence": "AAAA-MM-DD", "service_amount": "150.00", "payload": { "taker": { "name": "...", "tax_id": "", "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.