Impaginazione, ripetizione e competizione senza sorprese.
Le regole trasversali riportate di seguito si applicano a tutte le risorse e prevengono duplicazioni, cicli infiniti e integrazioni fragili.
Limitare e sfalsare l'impaginazione
Gli elenchi utilizzano il limite compreso tra 1 e 100 e l'offset da zero. Continua finché offset + data.length è inferiore a 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..."
}Filtri e ricerca
statusFiltra in base allo stato canonico della risorsa.queryRicerca testuale; trattarlo come corrispondenza, non come identificatore.marketplace / channelAccetta il codice del provider documentato nell'operazione.daysFinestra di analisi mobile compresa tra 1 e 365 giorni.from / toSe presente, utilizza i timestamp ISO 8601 in UTC.Idempotenza e ripetizione sicura
GET, PATCH e DELETE possono essere ripetuti con lo stesso significato. Le creazioni che hanno una chiave naturale documentata, come offerta tramite URL e ricezione tramite riferimento esterno, restituiscono la risorsa esistente invece di duplicarla.
Guasti di rete, errori 429 e 5xx con backoff e jitter esponenziali.
POST senza chiave naturale: interroga tramite identificatore esterno prima di riprovare.
400, 401, 402 e 403 fino alla corretta iscrizione, chiave, piano o ambito.
Collega la tua chiamata all'audit e semplifica qualsiasi indagine.