Boas práticas

O que faz uma integração ser estável — e o que a OTL confere no sandbox antes de liberar a produção.

Checklist

Antes de pedir a liberação da produção, confirme que a sua integração:

• Guarda o token só em servidor, em variável de ambiente ou cofre — nunca em site, aplicativo ou repositório.
• Lê a URL base e o token da configuração, para ir do sandbox à produção sem mexer no código.
• Começa pelo /v1/eu e para, com mensagem clara, se faltar permissão.
• Pagina até o fim, seguindo proximoCursor enquanto temMais for true.
• Sincroniza só o que mudou com atualizadoDesde, em vez de baixar o catálogo inteiro a cada execução.
• Respeita o 429: espera o Retry-After antes de tentar de novo.
• Decide pelo codigo do erro, não pela mensagem nem só pelo status.
• Não repete chamadas que não vão mudar de resultado (400, 401, 403, 404).
• Registra o X-Request-Id de cada chamada com erro.
• Ignora campos desconhecidos na resposta.
• Trata estoque: null como “desconhecido”, não como zero.
• Trata produto com ativo: false, tirando-o do ar no seu sistema.

Frequência de sincronização

Confirme o estoque no momento da venda

O estoque muda o dia inteiro. O número que você guardou na última sincronização é uma boa aproximação para exibir; para fechar uma venda, consulte de novo.

Preço de atacado é informação reservada

O precoAtacado é o custo do parceiro. Ele não deve aparecer para o cliente final, em anúncio, em página pública nem em código que rode no navegador. O que se mostra ao público é o preço de venda do parceiro: precoAtual, quando ele tem loja no HUB. precoSugerido é só uma referência.

Erros transitórios

Para 500, 503 e falhas de rede, tente de novo com espera crescente (1s, 2s, 4s, 8s) e desista depois de algumas tentativas, registrando o X-Request-Id. Um laço infinito de novas tentativas vira bloqueio por limite.

O que a OTL observa

No sandbox, a equipe OTL vê o histórico de chamadas de cada integração: rotas usadas, erros, quantas vezes bateu no limite. Uma integração que passa pelo sandbox sem 429 em série e sem 401 repetidos costuma ser liberada sem conversa.