feat(apps): Integração com Bling ERP na plataforma

[vitorrgg]

Porta o app Bling ERP (app_id 102418) do repositório app-bling-erp-v2 para o monorepo, usando a API v3 do Bling.

Funções

Função	Papel
blingerp-onStoreEvent	Eventos da loja: exporta pedidos e produtos, e processa a fila manual em applications-dataSet
blingerp-callback	Callbacks de estoque e pedidos configurados no Bling
blingerp-authCallback	Recebe o code do fluxo OAuth e grava os tokens
blingerp-cronRefreshToken	Renova o access_token antes de expirar

Mudanças de arquitetura em relação ao app v1

• A fila em Firestore (queue/{storeId}/events + running_events + handle-queue) deu lugar ao PubSub de eventos do monorepo (maxInstances: 1) com a fila em data do app;
• appSdk multi-loja substituído por @cloudcommerce/api com as credenciais da própria loja;
• Tokens OAuth em blingTokens/{storeId} e cache das situações de venda em blingStatuses/{storeId}, no projeto Firebase da loja;
• Busca de produto por SKU usa products/skus:{sku} no lugar do ElasticSearch.

Correções sobre o comportamento do v1

Encontradas ao portar e ao validar contra a API real:

1. Atualização de produto com variações falhava com HTTP 400 — a listagem /produtos?codigo= devolve o produto resumido, sem variacoes, então o PUT ia sem os IDs e o Bling rejeitava como se fossem novas variações;
2. Preço por variação era perdido na exportação (o Bling aplica o preço do produto pai a todas) — corrigido com PUT /produtos/{idVariacao} apenas para as divergentes;
3. Callback de estoque de variação sem SKU no Bling era descartado em silêncio — agora usa o ID do Bling como referência, que é o SKU gravado na importação;
4. Configuração "Importar produto" não tinha efeito — o callback forçava canCreateNew: false;
5. Falhas em exportação automática não apareciam no painel do lojista, só no log da função;
6. Status "Devolvido" era enviado como fulfillment_status inválido;
7. Limite diário da API gravava a flag invertida, liberando novas chamadas em vez de bloquear;
8. other_config era lido como outher_config (typo), então o tipo de contato nunca era aplicado;
9. Comparação de estoque usava um campo inexistente no Bling (quantity), causando lançamento redundante a cada exportação;
10. Sem situação correspondente no Bling, o pedido falhava — agora registra aviso e segue exportado.

Grades de variação importadas passam a mapear para size/age_group/gender (antes só Cor era normalizada), mantendo o round-trip estável com a exportação.

Testes

packages/apps/bling-erp/tests/ — 37 testes com node --test, offline, sem credenciais: pedido e produto nos dois sentidos, mapeamento de status (incluindo parse_status customizado), endereço/CEP, parcelamento, prazo de entrega com dias úteis e feriados, variações sem SKU e normalização de grades.

scripts/bling-smoke.mjs faz uma varredura read-only na API do Bling validando credenciais e todos os endpoints usados.

Validação em produção

Loja de teste (1011) + conta Bling de teste, com as funções deployadas em um projeto Firebase real:

• Fluxo OAuth completo: autorização no Bling → blingerp-authCallback → tokens no Firestore;
• Callback público: estoque alterado no Bling refletiu na loja (99 → 10);
• Pedido pago na loja → evento → PubSub → blingerp-onStoreEvent → pedido criado no Bling com contato, item vinculado, frete, etiqueta e parcela;
• Atualização de situação (delivered → "Atendido") e round-trip de status;
• Produto com variações nos dois sentidos, incluindo um criado pela interface do Bling (sem SKU nas variações);
• Importação de produto com imagem migrada do S3 do Bling para o storage da e-com.plus, e categoria criada na loja;
• blingerp-cronRefreshToken executando e validando o token.

Notas

• O registro do app no marketplace (título e admin_settings) continua no repositório app-bling-erp-v2; este pacote traz apenas o runtime;
• Ao migrar uma loja que já usa o app v1, definir ignore_triggers nas configurações do app para o app central parar de processá-la;
• pnpm-lock.yaml não foi atualizado neste PR — o CI instala com --no-frozen-lockfile.

🤖 Generated with Claude Code

[vitorrgg]

🤖 Revisão adversarial — /review-pr (Opus, revisão multi-agente)

Revisão adversarial do diff (4 revisores paralelos, cada um num grupo de risco), comparando com tiny-erp/melhor-envio como integração de referência. Meta: refutar a mudança e achar o colateral, não aprovar. O caminho feliz claramente funciona (validado em produção na loja 1011) — os achados abaixo são o que testes manuais não pegariam.

Veredito: 🔴 request changes

Boa notícia: os pacotes compartilhados (firebase/config.ts, events/firebase.ts) estão limpos — sem colisão de appId, sem colisão de export no barrel, escopo de eventos confinado. Sem regressão cross-app em tiny-erp/melhor-envio. O risco é todo dentro do próprio app + deploy.

---

🔴 Critical

C1 · Race no refresh do token desativa a integração permanentemente — src/bling-auth/create-access.ts:63-101, bling-erp.ts:22-31
O Bling v3 rotaciona o refresh_token a cada uso. O fluxo é read-modify-write sem transação/lock em blingTokens/{storeId}, com atores concorrentes (cron de refresh + função callback, que não tem maxInstances). Duas chamadas leem o mesmo token antigo; a 2ª recebe invalid_grant → grava isBloqued:true e mata a integração até re-auth manual, mesmo após um refresh bem-sucedido.
Correção: runTransaction no read+refresh+write; só bloquear em invalid_grant genuíno relendo o doc.

C2 · Callback público processa sem autenticação (fail-open) — src/bling-callback.ts:44-54
callbackToken = env || appData.callback_token. Sem nenhum setado (default), só loga um warning e segue processando. tiny-webhook.ts faz 403. Qualquer um faz POST forjado com {retorno:{pedidos:[...]}} / {estoques:[...]} e dispara importação de pedidos/produtos na loja.
Correção: falhar fechado (exigir token), como no tiny.

C3 · OAuth state nunca é validado → account-mixup / sobrescrita de tokens — src/bling-auth-callback.ts:16-21
O state é só logado; não há nonce armazenado. Um code de outra conta Bling injetado no callback sobrescreve os tokens da loja.
Correção: gerar/persistir state na iniciação e validar aqui.

C4 · Pedido devolvido (returned) nunca é cancelado no Bling — fica "Aprovado" — src/integration/parsers/status-to-bling.ts
Não há case 'returned' no switch de fulfillment, e returned nem existe em parseStatusTitle. Pedido pago e devolvido cai no fall-through → ['aprovado','em aberto']. Referência tiny-erp trata returned → 'cancelado'. Consequência: estoque não retorna, financeiro segue como venda válida, NF não é cancelada.
Teste de regressão incluído. Correção incluída.

C5 · Round-trip de status regride "Entregue → NF emitida" em contas Bling padrão — status-to-bling.ts × status-from-bling.ts
As situações padrão do Bling Vendas não têm "Enviado"/"Entregue"/"Faturado", então shipped/delivered/invoice_issued caem no fallback "Atendido" → na volta "Atendido" → invoice_issued. Um pedido delivered reimporta como invoice_issued (regride). Idem in_production → in_separation.
Teste de regressão incluído.

C6 · Fix #9 usa base de comparação de estoque errada — src/integration/export-product-to-bling.ts:191
Compara contra estoque.saldoVirtualTotal (físico − reservado, todos os depósitos), mas o balanço ajusta o saldo físico e a importação usa o saldo do depósito configurado. Loja com reserva/multi-depósito → posta balanço em toda exportação (movimentação infinita) ou não corrige o físico errado.

---

🟠 Required

• R1 export-product-to-bling.ts:99-103 — .catch(() => originalBlingProduct) engole 429/500 no re-fetch de variações → PUT sem IDs → volta o HTTP 400 do fix System design #1.
• R2 product-to-bling.ts:146 + product-from-bling.ts:236-241 — round-trip duplica variações sem SKU (codigo sintético PAI-1 não gravado de volta → não casa → cria nova).
• R3 parsers/order-to-bling.ts:~205-245 — amount.tax/amount.extra ignorados no total e parcelas → Bling recebe valor abaixo do pago; conciliação quebra. tiny-erp soma amount.tax.
• R4 parsers/order-from-bling.ts:78-96 — update de access_key da NF: else if (invoiceIndex && ...) pula o índice 0, e não seta shipping_lines → api.patch nunca envia.
• R5 create-access.ts:88-98 — 3 erros transitórios (5xx/timeout) no /oauth/token gravam isBloqued:true permanente; countErr read-then-set (usar FieldValue.increment).
• R6 bling-callback.ts:61-125 — erro transitório na importação retorna 200 sem retry (entradas isNotQueued) → Bling não re-notifica → evento perdido.
• R7 check-enable-api.ts:17-19 (24h) vs create-access.ts:34-36 (12h) — janela do rate-limit diário inconsistente.
• R8 after-bling-queue.ts:76-108 — lost-update na fila entre callback (instâncias ilimitadas) e onStoreEvent: ids reaparecem (pedido/etiqueta duplicados) ou somem.
• R9 try-image-upload.ts:16,29-35 — token ecom em cache de módulo nunca revalidado → ao expirar, grava a URL temporária do S3 do Bling como imagem (quebra depois).
• R10 get-products-bling.ts:9, import-product-from-bling.ts:143,187 — SKU não URL-encoded; SKU com espaço/+/# gera query malformada.
• R11 status-to-bling.ts — partially_delivered não mapeado (mesma classe do C4).
• R12 pnpm-lock.yaml não atualizado — o CI mascara com --no-frozen-lockfile, mas release/produção com --frozen-lockfile quebra (novo pacote de workspace + deps). Rebasear sobre a main (branch está 22 commits atrás) e commitar o lock.
• R13 (cobertura) — dos 8 fixes do PR, só [RFC] Deploy #5 e [RFC] Freemium #7 têm teste; os 37 testes cobrem só parsers puros. Sem teste: System design #1, Configure Renovate - autoclosed #2, Sign up #3, Conventional commits #4, [RFC] Automatic updates #6 (a flag de rate-limit invertida — bug booleano silencioso), Automatic releases #8 e o log de falhas do commit System design #1.

---

🟡 Optional (resumo)

Preço não exportado em loja multiloja (export-product-to-bling.ts:93) · estoque de variação sempre relançado sem comparação · /estoques/saldos sem paginação (>100 variações importam 0) · feriados hardcoded só até 2027 · datas em UTC → off-by-one de fuso (tiny-erp subtrai 3h) · numeroLoja numérico quebra a busca no import · fallback de forma de pagamento pega data[0] de qualquer tipo · recursão de categoria sem guarda de ciclo · pictureId pode apontar imagem de outra variação · potencial vazamento de client_secret em logger.error(err) cru sobre AxiosError (bling-auth-callback.ts:47-48).

✅ Confirmado OK (não são bugs)

Fix #7 (direção da flag), #8 (typo other_config, com fallback de leitura legado intencional), #5 (Devolvido→cancelado no parser), #2 (preço divergente no caminho feliz).

⚠️ Não verificado (precisa de API/ambiente real)

Forma real das respostas do Bling v3 (saldoVirtualTotal, variacoes[].id no PUT — base de C6/R1) · se o Bling reseta preço de todas as variações no PUT do pai · paginação real de /estoques/saldos · colisão de SKU em products/skus:{sku} · serialização final do logger do firebase · qual pipeline usa --frozen-lockfile.

---

_{Revisão gerada com Claude Code (Opus) via /review-pr — 4 agentes adversariais em paralelo. Achados de maior alavancagem: C1 (race de token), C2 (fail-open) e C4/C5 (regressão de status) — nenhum pego por teste manual.}

[vitorrgg]

🔄 Status atualizado — fixes aplicados + re-review adversarial do delta

Seguindo a revisão adversarial acima, os 6 Criticals foram tratados e, depois, rodei um segundo review adversarial focado só nos commits de fix (para pegar regressão que o próprio fix pudesse introduzir — o autor tem ponto cego sobre o próprio código). Esse re-review pegou 2 regressões nos meus fixes e corrigiu um exagero do review original — tudo já remediado. Estado verificado abaixo.

Placar final dos Criticals

#	Estado	Commits
C1 — race no refresh do token desativa a integração	✅ corrigido + hardening	8db7b7206, 9ba686120
C2 — callback público sem autenticação	✅ tratado (ver nota)	c51443af9 → revertido em eec45a191
C4 — pedido devolvido não cancela no Bling	✅ corrigido	c51443af9
C5 — round-trip regride status	✅ corrigido	7738fee86
C6 — base de estoque errada	✅ corrigido + refix	2dcaa6a0d → 303a028a0
C3 — OAuth state não validado	⏸️ risco aceito (ver nota)	—

O que o re-review encontrou (e como foi resolvido)

• C6 — regressão nova (Critical) no meu próprio fix. O primeiro fix comparava sempre o saldo físico, mas a importação usa o virtual quando a loja tem has_stock_reserve — lojas com reserva voltariam a divergir em todo export. Refix: extraí parseStockFromDeposits para um helper único usado por import e export, garantindo a mesma base (virtual/físico + soma por depósito). 303a028a0.
• C2 — severidade corrigida + regressão evitada. O review original tratou como "vetor de escrita não autenticado", mas o corpo do callback só traz identificadores — os handlers re-buscam o dado no Bling autenticado. O risco real é só disparar importação dos próprios dados da loja (sem injeção). Meu fail-closed derrubaria toda loja sem callback_token (campo opcional). Como o custo supera o ganho, revertido para "exigir token só quando configurado". eec45a191.
• C1 — verificado sólido. O reuso do token concorrente é barrado por um invariante forte (expiredAt futuro ⇒ refresh genuíno); FieldValue.increment eliminou a corrida do contador. Adicionado hardening: releitura do doc protegida com catch. 9ba686120.
• C5 — verificado sólido. Guard só afeta fulfillment, não bloqueia avanço legítimo. ⚠️ Trade-off by-design: correção "para trás" de fulfillment via Bling deixa de propagar (numa conta padrão "Atendido" mapeia p/ nf emitida). Correção manual passa a ser na loja — vale nota p/ o suporte.

Pendências (não-Critical)

• C3 — decidido manter o lojista autorizando pelo portal do Bling; como não iniciamos o fluxo, não há state nosso a validar. Risco residual documentado.
• R12 — lock não atualizado. Adicionei um check de CI (d2645980f, workflow "Lockfile integrity") que falha de propósito neste PR até o pnpm-lock.yaml ser regenerado com pnpm 10.17.0 no rebase sobre a main (a branch está 22 commits atrás).
• Optionals do review original seguem válidos (preço multiloja, paginação de /estoques/saldos >100 variações, feriados até 2027, datas UTC, etc.) — não bloqueiam.

Verificação

Todos os fixes verificados com build real (pnpm build: tsc + eslint) e suíte real (node --test): a cobertura foi de 37 → 58 testes, pass 58 · fail 0 · todo 0. Cada Critical tem teste de regressão.

_{Fixes e re-review gerados com Claude Code (Opus). O re-review do delta rodou 3 agentes adversariais sobre os commits de fix — pegou C6 e C2 antes do merge.}

[leomp12]

Revisei o port inteiro contra o app publicado (app-bling-erp-v2) e contra o tiny-erp como integração de referência. Antes dos problemas, o que está certo e não precisa ser revisitado:

As dez correções sobre o v1 são reais — conferi as que dava para conferir por código, e a de variação sem variacoes no PUT e a do outher_config (com fallback pro nome errado, migração bem feita em get-customer-bling.ts:13-14) são achados de quem foi atrás do comportamento, não de quem só transcreveu. Os testes são ganho de padrão: o tiny não tem nenhum, e o teste unitário de função pura offline não existia em app nenhum do monorepo — os irmãos só têm e2e atrás de credencial. A config compartilhada está limpa: nenhum appId duplicado entre os 31 apps, o nome exportado não colide, e o merge com main resolve automático. E as duas rodadas adversariais que você rodou pegaram coisa de verdade — os achados abaixo são o que sobrou depois delas, quase tudo em caminho sem cobertura de teste.

Também confirmei que after-bling-queue, order-to-bling, get-customer-bling, get-products-bling, payment-method e product-to-bling são ports fiéis, e que o canCreateNew tri-state, os nomes de config e o gate de preço/quantidade reproduzem exatamente o webhook.js:92-121 do app publicado. Nada disso é para mexer.

O que trava são quatro coisas, e as duas primeiras se compõem.

🏗️ Arquitetural — o lockfile.yml não pertence a esta PR

O d2645980f adiciona .github/workflows/lockfile.yml, que não tem relação nenhuma com o Bling. Três motivos para sair:

1. Ele falha na própria PR que o introduz — ERR_PNPM_OUTDATED_LOCKFILE ... not up to date with <ROOT>/packages/apps/bling-erp/package.json. Sobe vermelho por desenho.
2. O filtro de bot não funciona em PR. O if testa github.event.head_commit.author.name, que é campo de evento push; em pull_request é nulo, o contains dá falso e o job roda assim mesmo.
3. Ele briga com o ciclo do renovate que este repo já aceita. Todo PR do renovate merga com os 20 importers de loja fora do lock, e o chore: Fix package versions and submodules post-release restaura depois — o histórico do lock mostra isso em 35e33f14e (#798) e d47f33902 (#786). O workflow transforma um processo aceito em falha permanente de CI.

Some-se que ele usa actions/checkout@v7 sem submodules:, então validaria o lock contra uma árvore onde os 20 importers não existem em disco. A ideia é boa e eu quero ela — mas em PR própria, com o filtro corrigido e a decisão sobre submódulo explícita.

🔴 Bloqueante — o estoque anda para baixo até zerar, em loja com qualquer reserva

parse-stock-from-deposits.ts:1-6 documenta a invariante:

Usado pelos DOIS lados (importação e exportação) para que a base de comparação nunca divirja

Só que o call site da importação a pula justamente na configuração padrão. import-product-from-bling.ts:35-53:

if (typeof blingItem.estoqueAtual !== 'number'
  && typeof blingItem.estoque?.saldoVirtualTotal === 'number') {
  blingItem.estoqueAtual = Math.max(0, blingItem.estoque.saldoVirtualTotal);   // vira número aqui
}
if (Array.isArray(blingItem.depositos)
  && (blingDeposit || typeof blingItem.estoqueAtual !== 'number')) {           // ← falso com bling_deposit vazio
  blingItem.estoqueAtual = parseStockFromDeposits(...);
}

Com bling_deposit vazio e has_stock_reserve desligado — o padrão — a importação grava o saldo virtual e a exportação compara contra a soma do físico (export-product-to-bling.ts:194-196, que sempre chama parseStockFromDeposits). Havendo qualquer pedido reservando estoque, virtual < físico e as duas bases nunca batem.

A catraca, com físico 20 e 5 reservados:

passo	Bling físico	reservado	virtual	loja
import	20	5	15	15
export (operacao: 'B')	15	5	10	15
import	15	5	10	10
export	10	5	5	10

E assim até zerar. O motor que roda o ciclo é o bloqueante seguinte.

Colateral do mesmo ponto: com bling_deposit vazio a comparação soma todos os depósitos, mas a escrita vai só para depositos[0].id (:180). Em conta multi-depósito a soma nunca converge e o depósito 0 é sobrescrito com o total da loja.

O C6 (tests/parse-stock-from-deposits.test.mjs:26) afirma exatamente essa invariante e passa — porque testa o helper, não o call site. É o que faz o CI ficar verde em cima disso.

🔴 Bloqueante — o app não marca as próprias escritas, e o evento volta para ele

A plataforma tem supressão de auto-evento, e é central: EVENT_SKIP_FLAG = '_skip' (packages/firebase/src/const.ts:1), e o poller consulta a API com 'flag!': EVENT_SKIP_FLAG (check-store-events.ts:134), então evento marcado nunca chega a app nenhum. O updateAppData usa (update-app-data.ts:55), inclusive publicando direto no tópico antes, para a fila andar sem depender do poller.

O import de estoque não usa:

// import-product-from-bling.ts:75-79
endpoint += '/quantity';
// @ts-ignore
return api.put(endpoint, quantity);      // ← sem X-Event-Flag

E o app assina products-quantitySet (config.ts:154), que o tiny não assina. Então todo callback de estoque do Bling grava na loja, o evento volta, e event-to-bling.ts:79 reexporta pro Bling. Custo por callback recebido, ainda que a catraca acima não estivesse lá: +2 leituras de Firestore, +4 requisições ao Bling, +1 PATCH e +4 s de throttle. Dobra o custo de toda sincronização de estoque.

Vale notar que nenhum app de packages/apps/ usa o flag em escrita de recurso — o tiny tem a mesma omissão, mas não assina evento de estoque, então nunca dispara. O Bling é o primeiro a materializar.

Marcar a escrita fecha os dois bloqueantes de uma vez: sem o eco, a divergência de base do anterior deixa de ser realimentada. Ainda assim eu alinharia as bases, porque a divergência sozinha já produz um POST /estoques desnecessário por exportação.

🔴 Bloqueante — o callback lê o próprio segredo do documento que o chamador escolhe

bling-callback.ts:34-49:

const applicationId = req.query._id;                       // ← escolhido pelo chamador
const appEndpoint = applicationId && typeof applicationId === 'string'
  ? `applications/${applicationId}`
  : `applications/app_id:${appId}`;
const application = (await api.get(appEndpoint)).data;
const appData = { ...application.data, ...application.hidden_data };

const callbackToken = process.env.BLINGERP_CALLBACK_TOKEN || appData.callback_token;
if (callbackToken) {
  if (req.query.token !== callbackToken) { res.sendStatus(401); return; }
}

Sem BLINGERP_CALLBACK_TOKEN no ambiente, um ?_id=<outro app instalado na loja> carrega um doc sem callback_token, o if não entra e a requisição segue sem autenticação. A partir daí:

• :76 — no erro, afterQueue(queueEntry, appData, application, err) recebe o application que o atacante escolheu.
• after-bling-queue.ts:76 — o callback usa isNotQueued: true e action: 'importation', então a condição reduz a isError puro. E o erro é garantido, porque o app escolhido não tem credencial Bling.
• Resultado: escrita não autenticada no hidden_data de um documento de aplicação arbitrário da loja — até 200 entradas, notes de até 5000 caracteres cada, e o logs.unshift empurra para fora os logs reais do app vítima. O laço de :81-96 itera sobre pedidos/estoques do corpo da requisição, então o atacante controla quantas escritas por request.

O BLINGERP_CALLBACK_TOKEN neutraliza tudo — mas a action.yml não tem input para ele. Tem tinyerp-token → TINYERP_TOKEN (:57-58,307,365) e nenhum equivalente Bling, então no caminho oficial de deploy ele só entra via custom-dotenv genérico. O estado padrão do deploy é o vulnerável, e o README.md:28-33 manda definir a variável sem que exista o caminho para isso.

Duas correções, e as duas são pequenas: resolver sempre por applications/app_id:${appId} (o fallback que já está lá), e adicionar o input na Action.

🔴 Bloqueante — erro sem .response descarta o item da fila do lojista

create-access.ts:50 lança Error puro para o limite diário do Bling. O contrato de retry de after-bling-queue.ts:38 só entra se payload.response existir; sem isso cai no else (notes = payload.stack) e segue direto para o splice incondicional de :92-108, que remove o id da fila.

O irmão resolve no produtor, não no consumidor — post-tiny-erp.ts:44-56:

if (tinyErrorCode <= 2) response.status = 401;
else if (tinyErrorCode === 6) response.status = 503;
else if (tinyErrorCode === 20) response.status = 404;
const error: any = new Error(...);
error.response = response;      // ← é isto que faz o gate do consumidor funcionar

O port copiou o consumidor literalmente e não portou o contrato do produtor que o sustenta. Consequência: quando o limite diário estoura — evento esperado, não excepcional, e que se auto-limpa em 12h — a exportação manual do lojista perde itens em silêncio. E vale para todo estado terminal novo que bling-auth/ vier a lançar.

A correção certa é o client.ts normalizar os próprios erros como o post-tiny-erp faz, não somar mais um else if no after-bling-queue.

🟠 Estruturais

Variação criada nasce com estoque 0 e não se corrige. export-product-to-bling.ts:207-218 lê newVariations de responseData?.variations?.saved || responseData?.variacoes; variations.saved é shape que não existe na v3 (herdado quebrado do legado) e o POST /produtos responde só com o id. Com newVariations vazio, isUpdateStockVariation nunca dispara — e com export_quantity desligado o produto fica zerado para sempre.

O rastreio real é descartado. bling-callback.ts:83 desestrutura só { numero } do corpo do callback. O legado guardava transporte/codigosRastreamento na entrada da fila e fundia no pedido relido, com comentário explícito de que GET /pedidos/vendas/{id} nunca devolve urlRastreamento. Sem isso, todo rastreio importado recebe o link genérico do Melhor Rastreio, e volume que o Bling só expõe com urlRastreamento não gera rastreio nenhum (order-from-bling.ts:25 sai cedo). É regressão funcional contra o app publicado.

O smoke script mata a integração da loja. scripts/bling-smoke.mjs:31-50 se anuncia como somente leitura, mas a primeira coisa que faz é grant_type=refresh_token — e o próprio PR documenta que o Bling rotaciona o refresh token a cada uso. O README.md:56-62 manda rodar com o token de "uma loja já autorizada". Feito isso, o próximo refresh recebe invalid_grant, decideRefreshFailure não vê updatedAt novo e vai para isBloqued: true — integração morta até re-autorização manual.

A política de bloqueio está em dois lugares que discordam. check-enable-api.ts:17 usa janela de 24h; create-access.ts:36 usa 12h. E só o createAccess tem o ramo que limpa a flag — o gate roda antes (event-to-bling.ts:92, bling-callback.ts:55) e retorna false, então na trilha de evento e de callback nada destrava; só o cron. Entre 12h e 24h a integração fica escura enquanto a política já liberou. Vale notar que isso é comportamento novo: no legado o ramo gravava isRateLimit: false, então a flag nunca foi persistida em produção.

Sem camada de reconciliação. O único cron é o refresh de token, e a recuperação é o setTimeout(reject) dentro da janela de eventMaxAgeMs = 60000 — e só para item isQueued, porque o gate conflaciona "erro transitório" com "veio da fila manual". Evento automático não tem retry algum. O tiny pareia o mesmo handler com cronSendOrders varrendo pedidos pendentes a cada 3h. Composto com os dois itens acima, o caminho de volta à consistência é o lojista reenfileirar na mão.

O dedupe de retry sumiu sem substituto. O legado mantinha integration_retries/{...} com janela de 5 min. Restou o redelivery do PubSub, e como o splice só acontece no fim do afterQueue, a janela de duplo processamento é o handler inteiro. POST /estoques é idempotente por usar operacao: 'B'; POST /pedidos/vendas não é.

O throttle tem o escopo invertido. client.ts:33 guarda lastRequest em campo de instância e createBlingClient() é chamado dentro de cada handler. No legado isso era correto (um processo, N contas, limite por conta); numa instância por loja o escopo certo virou nível de módulo. Como está, checkTime curto-circuita na primeira request de toda invocação e não espaça chamadas concorrentes — as Promise.all de :187-228 calculam o mesmo atraso e disparam juntas contra um limite de 3 req/s.

Chaves de Firestore por storeId num projeto de uma loja. blingTokens/{storeId} e blingStatuses/{storeId} são os únicos documentos do monorepo particionados assim, e o storeId vem de ECOM_STORE_ID, constante de deploy. A convenção aqui chaveia pelo que varia — paypalTokens/${PAYPAL_CLIENT_ID}, pixSetup/${clientId}:${clientSecret}. Não é cosmético: o PayPal ainda deleta o doc no 401, porque a chave carrega a identidade da credencial. Aqui a chave é constante, então trocar client_id/client_secret nas configurações não invalida nada — o refresh token velho vai com credencial nova, dá invalid_grant e vira isBloqued. Rotação de credencial fica indistinguível de autorização revogada.

Terceira cópia do upload para a Storage API. try-image-upload.ts:16 tem ecomAccessToken module-scoped que nunca revalida; expirado em instância quente, todo upload baixa a imagem inteira, falha 401 e cai no fallback que hotlinka a URL do Bling para sempre, sem sinal de degradação. As outras duas cópias estão em tiny-erp/.../product-from-tiny.ts:26-64 e cli/src/ext/import-feed.ts:50. E os uploads são sequenciais (product-from-bling.ts:280-283) numa função sem timeoutSeconds explícito, ou seja 60s — produto com muitas imagens estoura e o import inteiro é descartado.

Trabalho pago antes de saber se é necessário. import-product-from-bling.ts:186-223 busca preço multiloja e importa categoria antes de descobrir que o caminho é isStockOnly — que é o de todo callback de estoque em loja sem update_product. export-order-to-bling.ts:74-77 busca /formas-pagamentos antes de saber se o pedido será criado, desperdiçando 1-2 chamadas em cada mudança de status de pedido já exportado. E export-product-to-bling.ts:100-104 refaz um GET /produtos/{id} idêntico em toda exportação de produto simples, porque a guarda não distingue resposta de listagem de resposta de detalhe. Tudo isso contra a mesma cota diária que o app tem uma máquina inteira para sobreviver.

Todo erro automático vira escrita de até ~1 MB. after-bling-queue.ts:76 inverteu a condição do tiny para logar também falha de evento automático — decisão deliberada e documentada, mas quem chega ali são os erros persistentes (os 429/5xx retornam antes). Em modo de falha estável, cada callback gera um PATCH de até 1 MB, em série, numa função maxInstances: 1.

🟢 Minors

• client.ts:61 — Promise<any> onde o TS inferiria Promise<AxiosResponse>; é a única superfície pública do contrato Bling e ~30 call sites fazem .data.data sem checagem. Uma linha tipa todos.
• bling-callback.ts:63 — handler: any no runQueueEntry, que é o segundo entrypoint de fan-out para os mesmos handlers; chama com 5 argumentos, mas import-order-from-bling.ts:22-26 declara 3. Um tipo IntegrationHandler cobriria os dois.
• order-from-bling.ts:10 — retorna Record<string, any> enquanto o parser irmão product-from-bling.ts:114 retorna ProductSet; OrderSet está exportado no mesmo @cloudcommerce/types.
• export-product-to-bling.ts:10 — getBlingStockBalances(bling: any) enquanto 6 helpers do pacote importam o tipo do client.
• order-from-bling.ts:91-93 — else if (invoiceIndex && ...): índice 0 é falsy, então o caso normal nunca recebe o back-fill; e o branch não seta shipping_lines, então nem persistiria. Morto nas duas pontas.
• order-from-bling.ts:96-108 — /notafiscal/{numero}/{serie} é endpoint v2 sob baseURL v3: 404 sempre, engolido pelo .catch(() => null). Dívida herdada, mas promete uma feature que não funciona.
• scripts/tests.sh:10-13 — exit 1 sem lib/, enquanto todo tests.sh irmão sai 0. Com turbo.json:19-21 declarando test sem dependsOn, pnpm test:apps num checkout limpo derruba o fan-out. Raiz: "test": { "dependsOn": ["build"] }.
• tests/*.test.mjs — importam de ../lib/**, a saída de build, em vez do fonte; acopla a suíte ao build-lib.sh.
• tests/decide-refresh-failure.test.mjs:52 — 2 erros de eslint e 3 warnings de max-len. Nada no repo linta .mjs, então é o primeiro a normalizar o resto.
• Comentários misturam português e inglês dentro do mesmo pacote (PT em 7 arquivos, EN em quantidade parecida); nos outros 30 apps não há comentário em PT.
• Prefixos [STOCK]/[PRICE_MULTILOJA]/[CATEGORY_IMPORT] em log são um terceiro dialeto — o repo usa >/>> e structured logging no 2º argumento, que vira label filtrável no Cloud Logging.
• describe dos testes prefixado por C1/C4/C5/C6, que referenciam um documento fora do repo, e em PT enquanto os outros dois arquivos da mesma suíte estão em inglês.
• guard-fulfillment-transition.ts exporta shouldAdvanceFulfillment — é o único helper cujo nome de arquivo não casa com o símbolo.
• payment-method.ts:16,47 — getPaymentBling exportado named e default.
• order-to-bling.ts:6-13 — feriados hardcoded cobrindo só 2026-2027; em jan/2028 o dataPrevista degrada sem log e sem teste que falhe.
• bling-auth-callback.ts:40 grava expiredAt com expires_in - 3600 e create-access.ts:73 com expires_in - 300 — dois escritores do mesmo campo discordando em 55 minutos.
• Crontab '36,51 * * * *' para token de ~6h: ~46 execuções no-op/dia, cada uma com um getAppData e uma leitura de Firestore. Veio verbatim de um fan-out multi-tenant onde os dois minutos ímpares faziam sentido.
• get-products-bling.ts:5-13 — monta codigo[]= com todos os itens do pedido sem limite/pagina nem chunking; a v3 pagina em 100.
• Falta CHANGELOG.md — é o único dos 31 apps sem, e o __skeleton já traz um.

Pra entrar antes do merge

1. Marcar o api.put(.../quantity) com X-Event-Flag: _skip e alinhar a base de estoque entre importação e exportação. As duas juntas fecham a catraca; a primeira sozinha para a realimentação, mas a divergência continua gerando POST /estoques desnecessário.
2. Resolver o callback sempre por applications/app_id:${appId} e adicionar o input de BLINGERP_CALLBACK_TOKEN na action.yml.
3. Normalizar os erros no client.ts para a forma que o after-bling-queue sabe classificar, como o post-tiny-erp faz.
4. Tirar o lockfile.yml para PR própria.
5. Corrigir o newVariations das variações criadas, e o aviso do smoke script no README — ou fazer o script parar de dar refresh.

Os 🟠 restantes dão para tratar em follow-up, mas queria tua leitura sobre quais viram issue antes do merge; nenhum deles tem issue aberta hoje, nem os seis follow-ups de packages/modules que você listou no corpo.

Uma ressalva de método: não rodei a suíte localmente (exige pnpm build antes, e o CI já a cobre verde), e o caminho de imagem, o OAuth e os callbacks não têm cobertura nenhuma — a validação deles foi leitura e rastreamento de fluxo, mais comparação com o app publicado. Os quatro bloqueantes eu conferi na fonte um por um antes de escrever.