Trabalho / Handoff
Projeto pessoal · demo no ar · outubro de 2026
Pedidos que chegam ao ERP uma vez só, mesmo quando o ERP está falhando.
O Handoff liga uma loja Shopify real a um ERP. Cada pedido entra exatamente uma vez; quando o ERP cai, fica lento ou recusa um pedido, a ponte tenta de novo, espera ou guarda o pedido para reenvio, e uma conferência noturna pega webhooks que nunca chegaram. Construí a partir dos problemas que encontro em integrações reais, e você pode quebrar o ERP você mesmo.
Abrir o console ao vivo- Papel
- Design, backend, frontend, operação
- Stack
- TypeScript · Next.js · PostgreSQL · QStash · Shopify Admin API
- Status
- Demo no ar
- Links
- Console em handoff.danielgcravo.com · código-fonte privado por enquanto
O console
Uma tela: todos os pedidos, o rastro de cada tentativa e os botões que quebram o ERP.
Qualquer pessoa pode ligar uma falha no ERP, fazer um pedido de teste real e ver o que a ponte faz. As telas abaixo são da demo no ar.
O que ele resolve
Cada jeito de o ERP falhar, e o que a ponte faz a respeito.
Do lado da loja: um webhook entregue duas vezes é tratado uma vez, dois webhooks do mesmo pedido viram um pedido só, e um que nunca chega é encontrado pela conciliação noturna.
- O ERP…
- A ponte…
- cai (503)
- tenta de novo seis vezes, de 10 s a 5 min de intervalo, e depois manda o pedido para a fila de falhas
- fica lento
- desiste depois de 8 s; a tentativa seguinte pergunta antes ao ERP se o pedido chegou mesmo assim
- limita requisições (429)
- espera o tempo que o ERP pediu antes de tentar de novo
- grava o pedido e perde a resposta
- encontra o pedido na tentativa seguinte em vez de criar outro
- recusa o pedido (422)
- manda para a fila de falhas na hora, porque tentar de novo não resolve
- muda o estoque por conta própria
- envia a nova quantidade para a loja, descontando pedidos ainda a caminho
Como funciona
Cinco tarefas pequenas, todas seguras para rodar duas vezes.
01
Webhook
Confere a assinatura da Shopify contra o corpo bruto, grava o pedido e responde na hora, para um ERP lento nunca parecer um webhook com falha.
02
Fila
O QStash chama a entrega até ela responder. Quem decide parar é a ponte, não a fila: 503 pede outra tentativa, 200 quer dizer entregue ou separado.
03
Entrega
Reserva o pedido para duas tentativas nunca rodarem juntas, pergunta ao ERP se ele já tem o pedido, cria se não tiver, e registra cada tentativa.
04
Estoque
O ERP não tem webhooks, então a ponte lê o que mudou desde o último marcador e grava quantidades absolutas na loja.
05
Conciliação
Toda noite: pedidos da loja que a ponte nunca recebeu entram no fluxo, e o estoque que divergiu é corrigido.
Decisões
As escolhas que impedem pedido perdido ou duplicado.
- Idempotência
- Três níveis: o ID do webhook barra reenvios, o ID do pedido barra dois webhooks do mesmo pedido, e uma consulta ao ERP antes de cada criação barra o duplicado que uma resposta perdida causaria.
- Erros
- Sem resposta, tempo esgotado, limite de requisições e erros do servidor são temporários e voltam a ser tentados. Qualquer outra recusa, ou um produto sem mapeamento, é permanente e espera uma pessoa.
- Estoque
- Só quantidades absolutas, então mandar o mesmo número duas vezes não muda nada. Unidades já vendidas e ainda fora do ERP ficam reservadas, para a loja nunca vender duas vezes.
- Privacidade
- Pedidos de teste não têm cliente, todo pedido chega ao ERP numa conta só, e os limites da demo guardam um hash com sal do endereço do visitante, nunca o endereço.
- Testes
- 62 testes, incluindo testes de integração que ligam cada falha do ERP e conferem que nenhum pedido se perde nem se duplica.
Seus sistemas
Precisa que sua loja, ERP ou CRM fiquem em sincronia, mesmo quando um deles falha?
Construo integrações com novas tentativas, fila de falhas e conferência noturna, documentadas, testadas e entregues no seu nome.