WineWorld.lk Commerce Platform | Business Central Inventory Interface (0.1-draft)

The website is the receiving system for inventory movements, so the two interfaces in this document (the Inventory Movement API and the Snapshot API) are defined by Encyte and implemented on the website. The sales order interface runs in the opposite direction: Business Central is the system of record for items, locations, tender codes, posting rules and the POS transaction, so that API contract is to be authored and owned by the Business Central team. The website will conform to the contract the Business Central team publishes. The attribute list and processing scenarios the website requires of it are in Section 7 of the governing document and are deliberately not expressed here.

• Store, then acknowledge. Every structurally valid movement is written to a durable event store before HTTP 200 is returned. A 200 means the website holds the data; Business Central does not retransmit it.
• Idempotent by key. The duplicate key is (sourceSystem, eventRef). A retransmitted movement is acknowledged as duplicate and is not applied a second time.
• Signed quantities. A negative quantity reduces website availability, a positive quantity increases it. Sales and returns may share one payload.
• Processing is decoupled from receipt. Movements are applied by a background process, sequentially per location and in parallel across locations.
• The website never deducts twice for its own orders. A WEB_ORDER_POST movement carrying websiteOrderRef releases the website's own reservation for that order as it is applied.
• Unknown is not an error. Movements for items, locations or bins the website does not sell from are stored and reported (unmatched, ignored), never rejected, so Business Central can send the complete stream for a location without filtering.

Adopted from the Business Central team's response of 23 October 2026 as the working list, subject to Wine World's confirmation.

An outbound quantity communicated at the request stage is not sent again on posting, is restored on rejection or cancellation, and is adjusted by the difference on amendment or partial processing.

1. The batch is validated as a whole for structure and authentication. A structurally invalid batch is rejected (HTTP 400) and nothing in it is stored.
2. Every structurally valid movement is written to the inventory event store with status stored before the response is returned. A movement whose (sourceSystem, eventRef) already exists is not stored again and is reported as duplicate.
3. A background process applies stored movements per location in order of occurredAt, then receipt. Applying a movement adds quantity to the location's saleable balance for the item, writes a row to the website's stock ledger with the Business Central references, and marks the event applied. Website availability is recomputed from the new balance.
4. A movement for an item not in the website product master, for a location not in the outlet list, or for a bin other than the location's saleable bin is stored and marked unmatched or ignored respectively. It is not applied and is listed on the reconciliation report.
5. Web orders. When the website places an order it reserves the quantity against the outlet's balance. When Business Central posts the POS transaction for that order it sends a WEB_ORDER_POST movement carrying websiteOrderRef. The website applies the negative quantity to the balance and releases the matching web reservation for that order and item, so the stock is reduced once, not twice. A WEB_ORDER_POST movement whose websiteOrderRef is unknown is applied to the balance and reported.
6. A released movement is applied as a positive quantity. If its relatedEventRef is known and the cumulative releases against that event exceed the quantity originally requested, the movement is still applied and the excess is reported.
7. Applying a movement never drives the saleable balance below zero. A movement that would do so sets the balance to zero, marks the event applied_clamped and reports it for reconciliation.
8. Every applied movement is recorded in the website's append-only audit trail with the Business Central references.
9. Applied events are retained for 90 days [proposed default, configurable] and then purged; the stock ledger rows and the audit trail are retained.

The limits are confirmed once Wine World and the Business Central team provide the transaction volumes requested in Section 6.2 of the governing document (POS transactions per location per day and in the peak hour; lines per transaction; other movements per day; locations per roll-out stage; longest outage to plan for; retry interval and batching). Expected transmission behaviour on the Business Central side: transmission at the event with no dependency that delays POS posting; a retry queue; exponential back-off on 5xx and no-response starting at 30 seconds and capped at 15 minutes [proposed]; Retry-After honoured on 429; the original eventRef and batchId preserved on retry; a 400 raised to an operator and not retried; after a store outage the backlog released oldest first in batches of up to 500.

Website sandbox and production, Business Central sandbox and production, with credentials per environment and never shared across. TLS 1.2 or higher; least-privilege service principal; no customer personal data in inventory payloads. All inbound requests are logged with source, size and outcome. The test plan (contract test with the examples in this document; snapshot plus 48 hours of live movements from store 1401 against the website sandbox in parallel with the stock file; burst test; duplicate and reversal cases; web order round trip) and the per-location go-live sequence are in Section 8 of the governing document.

Event-driven transmission of inventory movements from Shop Business Central to the website, one request per batch, store-then-acknowledge. Section 4 of the governing document.

Initial balance synchronisation before a location goes live on the movement interface, and on demand thereafter for reconciliation. Section 5 of the governing document. The outlet stock file upload in the website back office remains the manual fallback; applying a stock file for a location on the movement interface sets the balance exactly as a snapshot does.