Saldo no Bling pode representar físico, reserva e estoque virtual. Publicar o número errado em um marketplace gera venda sem disponibilidade; reduzir demais esconde produtos vendáveis. A sincronização precisa declarar qual saldo comercial será enviado.
Webhooks reduzem polling, mas não eliminam reconciliação. Eventos podem se repetir, chegar fora de ordem ou representar apenas parte de uma composição.
Evento de estoque correto
A documentação Bling distingue estoque físico, disparado por lançamentos, e estoque virtual, alterado também por reservas e composições. O payload traz produto, depósito e saldos totais; o desenho escolhe a fonte conforme a política de venda.
Para kits complexos, o webhook pode marcar vinculoComplexo quando há mais de 200 componentes relacionados e orientar a consulta dos saldos pela API. O integrador não presume que o payload contém toda a árvore.
SKU, depósito e buffer
Cada SKU externo aponta para um produto/variação Bling. Depósitos são incluídos ou excluídos por regra, e um buffer pode reservar unidades para loja física, avarias ou atraso de atualização.
A quantidade publicada é uma fórmula versionada, por exemplo saldo virtual dos depósitos A+B menos segurança. Mudanças nessa fórmula são auditáveis e aplicadas a todos os canais de maneira controlada.
Fila e ordenação
O receptor valida assinatura HMAC, registra eventId e coloca atualização por produto em uma fila ordenada. Eventos próximos podem ser consolidados para evitar enviar cinco saldos intermediários.
Depois de publicar, o conector guarda saldo enviado e resposta do canal. Falha recebe retentativa com limite; erro permanente, como SKU inexistente, vira pendência de cadastro.
Reconciliação periódica
Uma rotina consulta a API Bling e os canais para comparar saldo efetivo. Ela corrige eventos perdidos e identifica SKUs sem de/para. Webhook dá velocidade; reconciliação dá completude.
Loops são evitados distinguindo evento de origem. Uma atualização que veio do canal e gerou ajuste no Bling não deve voltar indefinidamente como nova ordem.
Implantação
O piloto cobre os SKUs de maior giro, incluindo kit, variação e mais de um depósito. Simulamos venda simultânea, cancelamento, reserva e indisponibilidade de canal.
Precisamos da política de estoque vendável, cadastros, depósitos, canais e tolerância de atraso. Monitoramos defasagem, divergência e quantidade de correções manuais.