Integration core principles

This guide summarizes the core principles for integrating with the WAIR API.

Only POST Requests (Upsert by Primary ID)

• All endpoints use POST.

• WAIR uses an upsert pattern based on the primary ID:

  - If the ID already exists, the record is updated.

  - If the ID does not exist, the record is created.

• To update a record, always send the complete object; partial updates are not supported.

Loose Coupling Between Endpoints

• Endpoints are technically independent.

• You can send stock for a SKU even if the item record has not yet been uploaded.

• While items are commonly implemented first, you may build endpoints in any order, enabling multiple developers to work in parallel.

Identifiers: id vs code

All endpoints include both an id and a code. These serve different purposes:

• id

  The unique identifier of the object. This is often a GUID or system-generated internal ID. It may not be visible to users in the source system.

• code

  A business key defined in the source system and familiar to end users. This value appears throughout the WAIR Customer Portal. It does not need to be unique. Avoid using the system-generated internal ID as this confuses the users of the portal.

Batch Mechanism (Required for All Upload Cycles)

Each dataset upload must follow the batch sequence:

1. Start a batch

   POST /Batch/start

2. Upload all related data, for example:

   1. Items

   2. Sales

   3. Transfers

   4. etc.

3. Close the batch

   POST /Batch/stop

This ensures WAIR knows exactly when a dataset is complete and ready for processing.

Recommended Maximum Dataset Sizes Per API Call

To ensure performance and prevent time-outs, large datasets should be split into multiple API calls. Recommended maximums:

• Purchase orders: 25.000 per call

• Sales: 10.000 per call

• Stock / stock mutations: 50.000 per call

• Items: 25.000 per call

• Prepacks: 25.000 per call

• Transfers: 10.000 per call

• Images: 1000 per call (for images/urls endpoint)

Example:

If you need to upload 50,000 sales records for an initial historical load, split them into 5 calls of 10,000 records each to POST /sales

Upload Frequency and Reliability

Minimum requirement:

Upload all datasets at least once per day.

Recommended approach:

For transactional data such as stock and sales, send data continuously or in frequent small batches.

Reasoning:

A single daily job is a single point of failure. If it fails, all data becomes outdated, which may lead to inaccurate replenishments or redistributions. Smaller and more frequent updates reduce this risk and keep data accurate.

Full Load Functionality

Some endpoints support the fullLoad query parameter. A full load is generally used for refreshing an entire dataset rather than for an initial load.

When performing a full load:

1. Objects in your request that do not yet exist are created.

2. Objects that already exist and are included in your request are updated.

3. Objects that exist in WAIR but are not included in your request are deleted (soft delete).

Example outcome:

If your system originally has brands A and B, and you submit a full load containing brands B and C, the final result will contain B (updated) and C (created), and A will be removed.

moreRecordsAvailable (for multi-call full loads)

For large datasets that require multiple full-load calls, you can use the moreRecordsAvailable parameter:

• For all calls except the last:

  fullLoad = true

  moreRecordsAvailable = true

• For the last call:

  fullLoad = true

  moreRecordsAvailable = false

This prevents records from being deleted prematurely while the full load is still in progress.

Be sure to always do a batch start and batch stop call around the full load, read section Batch Mechanism above for more information.

Summary

• Use POST-only upserts based on full objects.

• Endpoints are independent and can be implemented in any order.

• Use /batch/start and /batch/stop around each dataset upload.

• Prioritize items, stock, sales, and locations for the backtest.

• Large datasets must be split into multiple API calls.

• Full load should be used for refreshing complete datasets, not for initial loads.

• Upload data daily, and use continuous or frequent uploads for stock and sales.