fix(inbound): migra os 20 métodos de inbound/CT-e para as rotas reais /inbound/… (v3.4.0) - #30
Merged
Merged
Conversation
… /inbound/…
Os dois resources do domínio de documentos de entrada nunca funcionaram na
v3: as rotas usadas (/productinvoices/received/…, /productinvoices/inbound,
/cte/…) não existem na API — 404 de rota ou colisão com /productinvoices/{id}
(sondado ao vivo 2026-07-29/30). Migra tudo para o contrato /inbound/… da
consulta-dfe-distribuicao-v2 (spec canônica), mantendo nomes e assinaturas
públicas dos 20 métodos:
- config NF-e/CT-e: POST|GET|DELETE …/inbound/{productinvoices|transportationinvoices}
(habilitar era PUT, agora POST conforme a spec)
- consultas: rotas genéricas …/inbound/{key}… e específicas
…/inbound/productinvoices/{key}…
- manifest(): POST …/inbound/{key}/manifest?tpEvent={código} — sondado: o
binder só aceita código numérico SEFAZ; literais legados do SDK são
mapeados (Confirmation→210200, Acknowledgement→210210, Unknown→210220,
Refused→210240)
- reprocessWebhook(): POST …/inbound/productinvoices/{key_or_nsu}/processwebhook,
aceitando NSU via novo IdValidator::accessKeyOrNsu()
Testes: verbo+path pinados por método (datasets), InboundSpecAlignmentTest
(paths↔spec DF-e v2, rotas mortas ausentes, tpEvent integer, assinaturas dos
20 métodos por reflexão). Revalidado ao vivo com o código novo: settings e
chaves falsas retornam erros de domínio, nunca 404 de rota.
OpenSpec: fix-inbound-routes
andrenfe
added a commit
that referenced
this pull request
Jul 30, 2026
…ientes — release v3.4.0 (#32) Environment::Sandbox prometia roteamento/isolamento que nunca existiu: não há host sandbox na plataforma (o Node valida só production|development; a spec client-core já dizia que o servidor distingue por credencial) e Config::baseUrlForApi() nunca consultou o environment — todo tráfego sempre foi para produção. Um integrador que selecionava Sandbox com chave de produção emitia documento fiscal real achando-se isolado. - Environment/Config: docblocks passam a dizer a verdade (metadado declarativo; isolamento = chave de conta dev + company.environment) - Sandbox @deprecated; Config emite E_USER_DEPRECATED ao selecioná-lo, com a orientação do isolamento real; remoção na próxima major - Testes: deprecation disparada só em Sandbox; URLs idênticas com Production e Sandbox (pina a ausência de roteamento) - Docs: configuration.md ganha a seção "Ambientes na NFE.io"; getting-started.md, README e skill corrigidos - Nenhum comportamento de rede muda Inclui o corte da release v3.4.0 (Version.php + CHANGELOG), que embarca também a fix-inbound-routes (#30). OpenSpec: fix-sandbox-environment-contract
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resumo
O domínio de documentos de entrada inteiro nunca funcionou na v3.
InboundProductInvoicesResource(13 métodos) eTransportationInvoicesResource(7 métodos) usavam rotas que não existem na API — 404 de rota ou colisão com/productinvoices/{id}(sondado ao vivo 2026-07-29/30, empresa dev). Este PR migra os 20 métodos para o contrato real/inbound/…deopenapi/consulta-dfe-distribuicao-v2.yaml(spec canônica, superconjunto das 3 specs de distribuição), mantendo nomes e assinaturas públicas (pinado por teste de reflexão).PUT|GET|DELETE …/productinvoices/inboundPOST|GET|DELETE …/inbound/productinvoicesPUT|GET|DELETE …/cte/inboundPOST|GET|DELETE …/inbound/transportationinvoices…/productinvoices/received/{key}…,…/cte/{key}……/inbound/{key}…+ específicas…/inbound/productinvoices/{key}…PUT …/received/{key}/manifest/{type}POST …/inbound/{key}/manifest?tpEvent={código}POST …/received/{key}/webhook/reprocessPOST …/inbound/productinvoices/{key_or_nsu}/processwebhookDecisões de design (openspec
fix-inbound-routes)tpEventnumérico (tpEvent=Confirmation→400 "The value 'Confirmation' is not valid.";tpEvent=210210passa e falha na chave). O SDK aceita o código direto ou mapeia os literais legados:Confirmation→210200,Acknowledgement→210210,Unknown→210220,Refused→210240; outro valor lançaInvalidRequestExceptionlocal.reprocessWebhook()aceita chave de 44 dígitos ou NSU de 1–15 dígitos (novoIdValidator::accessKeyOrNsu()), conforme{access_key_or_nsu}da spec.Testes
MockTransport), mapeamento de literais, NSU, validações locais.InboundSpecAlignmentTest: cada rota emitida existe na spec DF-e v2 com o verbo correspondente; os esquemas de rota mortos seguem ausentes;tpEventéinteger; assinaturas dos 20 métodos pinadas por reflexão.make test: 262 passed / 1 failed — a falha é a ambiental pré-existente (CurlTransportFailurePhaseTest, DNS; passa no CI).make stanemake cslimpos.Validação ao vivo (2026-07-30, com o SDK deste PR)
getSettingsNF-e →404 "company not configured or enabled to use nfe distribution"; CT-e →400 "company not configured or active to use transportation inbound"— erros de domínio, não 404 de rota.getDetails/retrievecom chave falsa →400 "Key … for companyId … does not exist".manifestcom chave falsa →400 "Invalid access key …";reprocessWebhookcom NSU → erro de domínio citando o NSU.Decisão (task 5.3): não habilitamos inbound de verdade na empresa dev — a conta é compartilhada e a habilitação dispara busca real de DF-e na SEFAZ. Os erros de domínio acima provam o roteamento; a validação funcional ponta a ponta fica para uma conta dedicada.
OpenSpec:
fix-inbound-routes(19/19 tasks; artefatos locais,openspec/é gitignored). Contexto no vaultreview-07-14-2026(arquivos 05 e 09).