Guide: synchronize inventory

This pattern combines periodic pulls with webhooks. Pulls guarantee eventual consistency; webhooks reduce latency.

Initial import

1. Fetch all locations and store each Coilinx id.
2. Fetch all material types and store each Coilinx id.
3. Fetch items with limit=250, following nextCursor.
4. Upsert by Coilinx item ID in a single transaction per page.
5. Record the synchronization completion timestamp.

Incremental job

Run periodically:

GET /inventory/items?updatedSince=<last-success-minus-five-minutes>&limit=250

For each item:

• upsert the current values;
• preserve Coilinx IDs as immutable external identifiers;
• map locationId and materialTypeId to previously imported records;
• treat archived as inactive rather than deleting history.

Advance the high-water mark only after every page succeeds.

Webhook worker

Subscribe to item and configuration events. The HTTP receiver should verify and enqueue the event, then return immediately. A worker:

1. de-duplicates on eventId;
2. fetches the current item/type/location by ID;
3. upserts the response;
4. records the event as processed.

If a fetch returns 404, the record is absent from the authenticated company and should be reconciled according to your retention policy.

Consistency notes

• Delivery is at least once; idempotent upserts are required.
• Events for different items can arrive out of order.
• updatedAt should win over event arrival time when resolving stale updates.
• A nightly or hourly incremental pull catches missed events and endpoint outages.