API pública: paginación, sincronización e idempotencia
Cómo recorrer listas largas con el cursor, traer solo lo que cambió y repetir un POST sin crear duplicados.
Paginación por cursor
Las listas devuelven { "data": [...], "nextCursor": "..." }. Para la página siguiente, repite la petición con cursor= y el valor de nextCursor. Cuando nextCursor es null ya no hay más. Elige el tamaño con limit (de 1 a 200, por defecto 50). Los resultados van ordenados por fecha de cambio (updatedAt) y después por id, así que una página no se salta ni repite registros aunque entren datos nuevos mientras recorres.
Traer solo lo que cambió
Guarda el updatedAt del último registro que procesaste y, en la siguiente sincronización, pide updatedSince= con esa fecha (formato ISO 8601, por ejemplo 2026-11-14T08:00:00Z). En existencias, updatedSince también devuelve los productos cuyo stock de almacén cambió.
Idempotency-Key en los POST
Crear un cliente o un pedido exige la cabecera Idempotency-Key con un valor que elijas tú (de 1 a 120 caracteres: letras, números, -, _, ., :), por ejemplo el número del pedido en tu web.
- Si repites la petición con la misma clave y el mismo cuerpo (por un corte de red), recibes la respuesta de la primera vez con la cabecera
Idempotent-Replayed: true. No se crea nada nuevo. - La misma clave con otro cuerpo da 409
API_IDEMPOTENCY_KEY_REUSED: usa una clave nueva para una operación nueva. - Si la primera petición aún se está procesando recibes 409
API_IDEMPOTENCY_IN_PROGRESS: espera y repítela. - Si la operación falló (por ejemplo, un producto que no existe), puedes corregir y repetir con la misma clave.
- Las claves se guardan 24 horas.