Paginación, repetición y competencia sin sorpresas.
Las reglas transversales a continuación se aplican a todos los recursos y evitan la duplicación, los bucles infinitos y las integraciones frágiles.
Limitar y desplazar la paginación
Las listas utilizan un límite de 1 a 100 y un desplazamiento desde cero. Continúe siempre que desplazamiento + datos.longitud sea menor que paginación.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 y búsqueda
statusFiltra por el estado canónico del recurso.queryBúsqueda textual; trátelo como correspondencia, no como un identificador.marketplace / channelAcepta el código de proveedor documentado en la operación.daysVentana de analítica móvil entre 1 y 365 días.from / toCuando estén presentes, utilice marcas de tiempo ISO 8601 en UTC.Idempotencia y repetición segura
GET, PATCH y DELETE se pueden repetir con el mismo significado. Las creaciones que tienen una clave natural documentada, como ofrecer por URL y recibir por referencia externa, devuelven el recurso existente en lugar de duplicarlo.
Fallos de red, errores 429 y 5xx con retroceso exponencial y jitter.
POST sin clave natural: consulta por identificador externo antes de volver a intentarlo.
400, 401, 402 y 403 hasta la correcta entrada, clave, plano o alcance.
Vincula su llamada a la auditoría y simplifica cualquier investigación.