Paginação, repetição e concorrência sem surpresas.
As regras transversais abaixo se aplicam a todos os recursos e evitam duplicidade, loops infinitos e integrações frágeis.
Paginação por limit e offset
Listas usam limit de 1 a 100 e offset a partir de zero. Continue enquanto offset + data.length for menor que pagination.total.
GET /api/v1/offers?status=approved&marketplace=amazon&limit=50&offset=100
{
"data": [ ... ],
"pagination": { "limit": 50, "offset": 100, "total": 384 },
"request_id": "req_01J..."
}Filtros e busca
statusFiltra pelo estado canônico do recurso.queryBusca textual; trate como correspondência, não como identificador.marketplace / channelAceita o código do provedor documentado na operação.daysJanela móvel de analytics entre 1 e 365 dias.from / toQuando presentes, use timestamps ISO 8601 em UTC.Idempotência e repetição segura
GET, PATCH e DELETE podem ser repetidos com o mesmo significado. Criações que possuem chave natural documentada, como oferta por URL e recebimento por referência externa, devolvem o recurso existente em vez de duplicá-lo.
Falhas de rede, 429 e erros 5xx com backoff exponencial e jitter.
POST sem chave natural: consulte pelo identificador externo antes de tentar novamente.
400, 401, 402 e 403 até corrigir entrada, chave, plano ou escopo.
Ele liga sua chamada à auditoria e simplifica qualquer investigação.