APIs REST para integrações de ecommerce: autenticação, limites e erros

Quase todas as integrações de uma loja falam com APIs REST: a do ERP, a do gateway de pagamento, a da transportadora, a da própria loja. Estas regras evitam a maioria dos problemas.

Autenticação

• Chaves de API: simples. Guarde-as fora do código (configuração cifrada, variáveis de ambiente) e uma por integração.
• OAuth2: tokens que expiram. Renove o token antes de expirar e trate o erro 401 renovando e tentando outra vez uma única vez.
• Nunca envie credenciais por HTTP sem cifrar nem no URL.

Paginação e filtros

Não peça «todas as encomendas». Peça as modificadas desde a última sincronização, por páginas. Guarde a marca temporal da última sincronização correta, não a da última tentada.

Limites de pedidos

A maioria das APIs limita quantos pedidos pode fazer por minuto. Quando o ultrapassa, respondem 429. Respeite o cabeçalho Retry-After e espere com um atraso crescente.

for ($intento = 0; $intento < 5; $intento++) {
    $r = llamar($url);
    if ($r->status !== 429 && $r->status < 500) {
        break;
    }
    sleep(min(60, 2 ** $intento));
}

Erros

• 4xx: o erro é seu (dados mal formados, sem permissão). Não tente de novo sem corrigir.
• 5xx e tempos de espera esgotados: tente de novo com espera.
• Registe o pedido e a resposta (sem dados sensíveis) de cada erro.