API Docs v1 api.hubiss.com.br

Limitação

Quantos registros vêm por página, quantas requisições cabem por segundo e como reagir quando a API pede calma.

A API limita o tamanho da página; a velocidade depende da sua infraestrutura. Respeitar a paginação evita leituras incompletas e 429 de proxy.

Tamanho da página

Parâmetro Padrão Máximo
per_page 20 registros 20 registros

Valores acima de 20 são reduzidos para 20: a API usa o teto e continua paginando. Para volumes grandes, pagine seguindo links.next em vez de tentar aumentar a página.

Velocidade das chamadas

A API não aplica limite de requisições por token hoje. Você pode chamar livremente, desde que respeite a paginação. Se a sua infraestrutura (proxy, CDN ou gateway) impuser um limite, a resposta será 429 Too Many Requests — trate como no exemplo abaixo.

JSONjson
{
    "message": "Too Many Requests"
}

Como reagir ao 429

  1. Pare de enviar por alguns instantes.
  2. Repita a chamada com espera crescente (1 s, 2 s, 4 s, 8 s…).
  3. Se persistir, reduza a concorrência do seu processo.
Exemplo em JavaScriptjavascript
async function chamarComBackoff(fn, tentativas = 5) {
    for (let i = 0; i < tentativas; i++) {
        const resposta = await fn();
        if (resposta.status !== 429) return resposta;

        const espera = Math.min(1000 * 2 ** i, 15000);
        await new Promise((r) => setTimeout(r, espera));
    }
    throw new Error('Limite de requisições persistente');
}
Não faça retry imediato em loop
Repetir sem espera mantém o 429 e consome seu limite. O backoff exponencial resolve o caso na maioria das vezes.

Recomendações para integrações grandes

Cenário Recomendação
Catálogo com milhares de produtos Processar em lotes com pausa entre eles
Pedidos do dia Usar webhook em vez de polling
Reenvio após falha Reprocessar somente o que falhou, não o lote inteiro
Muitas atualizações de estoque Agrupar por produto e evitar chamadas redundantes
Horário de pico de vendas Priorizar consulta de pedidos; adiar sincronização de catálogo

Quanto tempo leva uma sincronização

Como referência: 1.000 produtos com 4 fotos cada ficam em torno de 5.000 chamadas; só para listar 1.000 produtos com per_page=20 são ~50 páginas. Processe em lotes e prefira janelas fora do horário de pico para não sobrecarregar o seu ambiente.

Próximo passo
Entenda como navegar nas listas em Paginação e o que fazer em cada falha em Erros.