Integração com Bling, Tiny, Mercado Livre, Nuvemshop e Amazon: como fazer sem duplicar pedidos

O cenário típico

Uma empresa vende no balcão, na loja virtual e em marketplaces, e fatura em um ERP de mercado. Sem integração, alguém digita pedidos, ajusta estoque à mão e confere tudo no fim do dia. Com uma integração mal feita, o problema muda de forma: pedidos duplicados no ERP, estoque divergente e falhas silenciosas que só aparecem quando o cliente reclama.

Plataforma	O que normalmente se integra
Bling	Cadastro de produtos, por empresa, com inclusão, alteração e exclusão
Tiny ERP	Exportação de clientes, transportadoras e pedidos de vários canais
Mercado Livre	Importação de pedidos e acompanhamento de situação
Amazon	Importação de pedidos para o fluxo da empresa
Nuvemshop	Pedidos da loja virtual entrando na fila de exportação para o ERP

Pilar 1: conexão por empresa

Muitos grupos têm mais de um CNPJ. A integração precisa tratar cada empresa como uma conexão separada, com credenciais, tokens e dados próprios. Na integração com o Bling, por exemplo, a empresa é a primeira dimensão de qualquer consulta: todo produto pertence a uma conexão, e nenhuma sincronização mistura dados de CNPJs diferentes.

Pilar 2: OAuth bem implementado

1. O usuário autoriza a conexão no próprio painel da plataforma.
2. O parâmetro state é aleatório, guardado apenas como hash, expira em poucos minutos e só vale uma vez.
3. O código de autorização é trocado imediatamente pelo token, porque expira rápido.
4. Client Secret, Access Token e Refresh Token são armazenados criptografados.
5. Após a autorização, o sistema confere se o CNPJ da conta autorizada é o mesmo da empresa cadastrada. Se não for, o token é descartado.
6. A renovação do token acontece automaticamente antes do vencimento.

Pilar 3: respeitar os limites da API

Plataformas protegem suas APIs com limites de requisição. Ultrapassá-los gera bloqueios temporários que derrubam a integração no pior momento. Por isso, o controle de ritmo fica dentro da integração:

Controle	Exemplo aplicado na integração com o Bling
Por conta	Intervalo mínimo entre chamadas para ficar abaixo de 3 requisições por segundo
Por servidor	Intervalo global compartilhado entre todas as conexões
Por dia	Contador persistente abaixo do limite diário de requisições
Autenticação	Intervalo próprio para o endpoint de token
Respostas de limite	Respeito ao cabeçalho Retry-After e retentativa exponencial limitada

Pilar 4: sincronização incremental e cache local

Consultar a API a cada pesquisa na tela é lento e consome o limite à toa. A integração mantém um espelho local e sincroniza apenas o que mudou desde a última execução, paginando os resultados. Uma carga completa fica disponível para a primeira execução ou para correções. As listagens do painel usam o cache local, e a rotina incremental roda periodicamente pelo agendador.

Pilar 5: fila de exportação com etapas

Na exportação de pedidos para o Tiny ERP, pedidos de balcão, loja virtual e outros canais entram em uma única fila. A exportação acontece em etapas, porque um pedido depende de cadastros que precisam existir antes:

1. Cliente: cria ou atualiza o cadastro do comprador no ERP.
2. Transportadora: garante o cadastro do responsável pela entrega.
3. Pedido: só é enviado quando cliente e transportadora estão concluídos.
4. Marcadores: aplica as marcações que identificam a origem no ERP.
5. Cancelamento: propaga cancelamentos feitos depois da exportação.

Um bloqueio global impede duas exportações simultâneas, e cada execução tem limite de tentativas e de tempo, para não atropelar a próxima.

Pilar 6: retentativas inteligentes e idempotência

Nem toda falha é igual. A integração classifica o erro e decide o que fazer:

Tipo de falha	Tratamento
Validação ou cadastro (400, 404, 409, 422)	Espera de uma hora, enquanto as outras etapas continuam
Instabilidade temporária	Pausa da filial com espera crescente de um minuto até uma hora
Limite atingido	Espera pelo tempo indicado em Retry-After
Token expirado	Renovação automática e nova tentativa uma única vez

O pedido só é marcado como exportado depois do sucesso da etapa. O código do ERP já vinculado é preservado e usado em atualizações, e uma conferência busca pedidos equivalentes antes de criar um novo. Se a busca for incompleta ou ambígua, o sistema não vincula automaticamente: prefere sinalizar o caso a arriscar uma duplicidade.

Observabilidade

• Cada falha registra filial, origem, etapa, registro, tentativas, último diagnóstico e próxima tentativa.
• O retorno da rotina mostra processados, sucessos, falhas e pendências por filial.
• Falhas continuam visíveis enquanto aguardam nova tentativa, sem esconder o problema.
• Indicadores nunca são alterados à mão para ocultar uma falha: corrige-se o cadastro ou a configuração.

Perguntas frequentes

Posso integrar várias empresas do mesmo grupo?

Sim. Cada empresa é uma conexão independente, com credenciais, tokens e dados próprios.

Por que não sincronizar tudo a cada minuto?

Porque isso consome os limites da API e pode bloquear a conta. A sincronização incremental busca apenas o que mudou.

O que acontece se a API do ERP ficar fora do ar?

Os pedidos continuam na fila. A integração espera, tenta novamente com intervalos crescentes e retoma de onde parou, sem duplicar.

Dá para juntar vendas de vários canais no mesmo ERP?

Sim. Balcão, loja virtual e marketplaces podem alimentar a mesma fila de exportação, com a origem identificada em cada pedido.