AploDelivery Partner API — full website scope (v1 extension) — implementation spec

Status: scope approved by the owner on 2026-09-23. It covers every process the website needs: menu and stop-list with iiko as source of truth, points and delivery zones, AploCard loyalty, payment, and guest profile. The ViL website developer integrates it. The docs must be corporate-grade (§9). Builds on PARTNER_API_SPEC.md (already live): conventions, auth, errors, scoping, webhooks and outbox are unchanged unless stated. All new routes stay under /v1 because nobody has integrated yet. The version policy (§9) starts from this release.

0. Architecture

website backend ──HMAC──▶ AploDelivery ──┬─▶ iikoCloud  (menu, prices, stop-lists, payment types, zones*, is_alive)  — read, cached
                                          ├─▶ AploCard   (HMAC POS API: calculate, hold/confirm/cancel, coupons, certificates, accrue)
                                          └─▶ POS plugin (order create, statuses, cancel, streets)     — existing claim protocol

• The site talks only to AploDelivery. The iikoCloud keys and the AploCard HMAC key live only in our env. The site never sees them.
• iikoCloud data is synced into our DB by a background worker and served from our DB. The site's reads never wait on iiko, and iiko rate limits are not multiplied by site traffic. Freshness targets: stop-list ≤ 60 s, menu/prices ≤ 10 min, payment types and zones ≤ 1 h, is_alive ≤ 60 s.
• Money is integer kopecks (amountMinor) everywhere. Business dates and times use Europe/Moscow, and every timestamp is RFC 3339 with an offset.
• \* Zones: the source depends on the live iiko probe (§3.3). The API contract is identical either way.

New Go packages (layering Handler → Service → Repository, as today): internal/iikocloud (client, v2 auth with v1 fallback, retry/backoff, 429 handling) · internal/catalog (sync worker + repo) · internal/loyalty (AploCard HMAC client only - typed errors, Fake for tests) · internal/checkout (pure pricing engine + signed calculationId token; DeliveryPricer interface, ZeroPricer stub for the parallel zones branch) · internal/loyaltysaga (background worker: outbox confirm/cancel/accrue, two reaper sweeps) · internal/ratelimit (in-memory per-key limiter). Migrations 006_catalog, 007_points (both already live). Phase 3 shipped as migration 009_loyalty (register version 9), not the originally planned 007_checkout_loyalty/008_guest_ratelimit: 008 is reserved for the parallel zones branch (phase 2), and guest rate limiting turned out to need no table (in-memory is sufficient for the current single-instance deployment - see §4 deviations). 009 adds delivery_loyalty_saga, delivery_loyalty_outbox, delivery_loyalty_audit, delivery_loyalty_org_mapping, and widens delivery_webhook_outbox.event_type's CHECK constraint for the 4 new webhook events.

1. Catalog

1.1 GET /v1/points/{pointId}/menu

Full sellable menu for the point, merged with the stop-list.

{"pointId":"3","revision":"2026-09-23T10:00:00+03:00#a1b2","currency":"RUB",
 "categories":[{"id":"…","name":"Роллы","sort":10,"parentId":null}],
 "items":[{"id":"<iiko productId>","externalId":"<site dish id if mapped>","categoryId":"…","name":"…","description":"…",
   "price":{"amountMinor":42000,"currency":"RUB"},"weightGrams":230,"nutrition":{"kcal":…,"protein":…,"fat":…,"carbs":…,"per":"100g"},
   "imageUrl":"https://…","available":true,"unavailableReason":null,"sizes":[],"modifierGroups":[],"tags":["new","spicy"]}]}

• Source (decided by the 2026-09-23 probe): /api/1/nomenclature per organization. No external menu is linked to our apiLogin keys (/api/2/menu returns [], by_id 46626 returns EXTERNAL_MENU_DATA_MISSED). An item is sold at a point when it is a DISH/GOODS, not deleted, and has a size in sizePrices[] whose nested price.isIncludedInMenu is true and whose currentPrice is non-null; the product object itself carries no isIncludedInMenu field (verified live 2026-09-23 against Боброво). A currentPrice of exactly 0 is excluded by default because it is a promo giveaway, for example «Маки-ролл с авокадо | Акция»; set DELIVERY_CATALOG_ALLOW_ZERO_PRICE=true to include zero-price items instead. Categories are the nomenclature product groups (hide the service groups; the list is in config). Probe numbers: Боброво 224 products, 102 sellable products with the corrected rule (corrected down from the uncorrected probe reading of 106 on the menu with a price); Амурская 110; about 175 per org carry KBJU.
• If the owner later links external menu 46626 (or a dedicated site menu) to the apiLogin in iikoWeb, the sync switches to /api/2/menu/by_id behind the same contract. That gives curated categories, client descriptions and photos.
• available=false + unavailableReason:"stop_list" when the stop-list balance is ≤ 0.
• ETag = revision. If-None-Match gives 304. The site should poll at most once a minute or use the menu.updated webhook.
• Images: nomenclature has no images (0 in the probe). Phase 1 takes photos from iikoWeb external-menu items (existing IikoWebExtMenuClient knowledge, matched by productId). Otherwise, until the menu is linked, imageUrl is null and the site keeps its own photos keyed by iiko productId. iiko photo URLs change on re-upload, so we never cache bytes.
• Item id is the iiko productId. Orders may reference items by iiko id (new, preferred) or by the legacy site externalProductId via product mappings (existing). This retires the 61-unmapped-dishes problem: a dish the site shows is by construction a dish the POS knows.
• A product whose group is hidden/deleted/a modifier group, or that has no parentGroup at all, is excluded from the menu entirely (implementation review HIGH-1) — there is no synthetic "Прочее"/uncategorized bucket, so every item on the menu always has a real, navigable category.
• weightGrams is iiko nomenclature weight × 1000 (nomenclature weight is in kilograms), verified live 2026-09-23 against Боброво.

1.2 GET /v1/points/{pointId}/stop-list

Light, frequent read: {"pointId","revision","items":[{"id","balance"}]}. Webhook stoplist.updated.

1.3 GET /v1/catalog/revision

{"points":{"3":{"menu":"…","stopList":"…"}}} gives a cheap change detection for all points.

2. Points

2.1 GET /v1/points (extended, backward compatible)

Adds name, address, location{lat,lon}, phone, timezone:"Europe/Moscow", schedule[{weekday,open,close}], isOpenNow, acceptsOrders (= route active ∧ terminal alive ∧ within schedule), deliveryTypes:["courier","pickup"]. Point metadata that iiko lacks (display name, phone, schedule) lives in our delivery_points table, managed by operators (§8), seeded from the site's GET /api/rests data once.

2.2 GET /v1/points/{pointId}/status

{"acceptsOrders","terminalAlive","isOpenNow","reason"}. Webhook point.status_changed.

3. Delivery zones and address

3.1 POST /v1/delivery/resolve

Input {"location":{"lat","lon"}} and/or {"address":{"city","street","house"}} plus deliveryType. Output: {"serviceable":true,"pointId":"3","zoneId":"…","minOrder":{…},"deliveryFee":{…},"freeDeliveryFrom":{…},"etaMinutes":{"min":45,"max":60},"street":{"status":"ok|ambiguous|not_found|unknown","name":…}}. Point selection: the zone that contains the point wins. On overlap, lowest priority, then nearest point. A street check (existing §1.4 logic) runs against the chosen point's POS dictionary. serviceable=false + reason when outside all zones or the point is not accepting orders.

3.2 GET /v1/points/{pointId}/delivery-zones

{"zones":[{"id","name","polygon":[[lat,lon],…],"minOrder","deliveryFee","freeDeliveryFrom","etaMinutes","priority","active"}]}.

3.3 Zone source — decided: ours (B)

The 2026-09-23 probe returned deliveryZones: [] and restrictions: [] for all 26 ViL orgs, defaultMinSum=0 and no delivery-fee product. The only hint was a Google My Maps link (deliveryRegionsMapUrl). So zones live in our delivery_zones table. They are imported once from the site admin export (the site developer provides JSON/CSV) or from the Google My Maps KML, then managed in our operator admin (§8). The site stops using its own zones. iiko defaults are used as fallback ETA: courier 45 min, pickup 90 min. The contract (§3.1–3.2) is identical in both cases.

4. Checkout pricing

4.1 POST /v1/checkout/calculate

No side effects. Input:

{"pointId":"3","deliveryType":"courier","location":{…},"items":[{"id":"<iiko productId>","quantity":"2"}],
 "guest":{"phone":"+7…"},"coupon":"ABC123","bonusToSpend":{"amountMinor":10000,"currency":"RUB"},"deliverAt":"…"}

Output: line prices from our catalog (never from the request), subtotal, programDiscount (automatic AploCard loyalty-program discounts), coupon{status, discount}, bonus{requested, maxSpend, spend}, deliveryFee, minOrder{met, missing}, total, warnings[] (e.g. item in stop-list, point closed), and calculationId (a signed token over the inputs and result, valid 15 min). Shipped coupon.status values: not_requested | applied | invalid - the engine's /calculate preview does not distinguish "invalid" from "expired" (no separate signal in its response), so both collapse to invalid here; a distinct expired status would need a dedicated engine field this phase does not have. Delivery is priced as a line after loyalty discounts. The existing gotcha is that promotions discount the delivery line. Decide per AploCard rule: the delivery line is excluded from discount bases (documented). Delivery-fee-line follow-up (owner decision 2026-09-23), shipped: pricing this fee into total was never the gap - deliveryFee/total above already reflected it. The gap was that the DeliveryCommand sent to the POS at order creation carried no line for it at all, so the created iiko order's own total fell short by the fee and the plugin-side POS invariant re-check could never balance. Closed with an additive deliveryFeeLine{iikoProductId, priceMinor} on the wire (domain.CommandDeliveryFeeLine, plugin/WIRE_CONTRACT.md's new section) - iikoProductId from DELIVERY_FEE_PRODUCT_ID (tenant-wide env, ViL's live «Доставка Приложение» Service product acdca4b3-8329-42ce-b8d2-5ab335a63b3d by default), priceMinor the zone fee actually priced. Absent for pickup and for a zero fee. internal/service.verifyMappedLoyaltyInvariant now takes the persisted payload.DeliveryFeeMinor as an explicit parameter rather than reading checkout.Result.DeliveryFeeMinor implicitly, so the check verifies what will actually reach the plugin, not merely what was priced a moment earlier.

4.2 Order creation with checkout (POST /v1/orders, extended)

New optional fields: calculationId, coupon, bonusToSpend, payment, deliveryType, location, comment, persons, callBack:false.

• The server recalculates. If the total differs from calculationId (price changed, stop-list), it returns 409 price_changed with the fresh calculation. The site shows it and asks again.
• payment: {"method":"online|cash|card_on_delivery","paid":true,"externalPaymentId":"yookassa-…","amountMinor":…,"change":{"from":…}}. Online orders must be created after successful payment (paid:true). The plugin adds an external prepayment of type ECARD, matched by code, never by name. The probe found ECRDL deleted in iiko, so ECARD covers both courier and pickup. Order types: «Доставка курьером» 76067ea3-…, «Самовывоз Сайт» c401fa52-…. cash and card_on_delivery map to the POS payment types configured per point.
• Loyalty saga (all idempotent by sourceRefId = order id):
  1. At ingest: coupon hold + bonus hold in AploCard. If either fails, the order is rejected 422 loyalty_rejected with the detail. Nothing is created.
  2. created_verified gives confirm for both.
  3. rejected_final / cancelled gives cancel for both. A manual_review status leaves the holds held and opens an alert.
  4. Expiry we enforce (owner decision 2026-09-23, see §4.3): any hold whose order is not created_verified within 30 min is acted on by our reaper, but the action depends on the order's own state - a hold is never released while the order could still reach created_verified. queued (never claimed) is cancelled outright, which releases the hold as part of that same action. claimed/prepared/create_sending/reconciliation_required only gets cancel_state=requested; the hold stays held until the order genuinely, definitively terminates (rejected_final/cancelled), at which point the normal step-3 cancel fires. An order/saga row with no order at all, or one already rejected_final/cancelled whose own release attempt is stuck, is released directly.
  5. Delivery status Delivered/Closed gives accrue (rule-based) with status read-back on unknown outcome.

4.3 Implementation notes and deviations (phase 3, shipped 2026-09-23)

Verified against the live engine source (not assumed) and worth recording here so the next person does not re-derive them:

• organizationId in every AploCard POS-API call is AploCard's own internal organizations.id, NOT the iiko organization id used everywhere else in this service (Route.OrganizationID). The engine resolves an iiko org id from it only for guest-lookup calls this service never makes. This is a materially different fact than §0's original assumption ("per-point org mapping = the route's iiko organizationId") - closed with a new operator-managed table, delivery_loyalty_org_mapping (tenant, source, external_point_id) → AploCard organization id, migration 009. A point with no row behaves exactly like AploCard being unconfigured: pricing works, coupon/bonus/accrual respond 503 loyalty_unavailable.
• Hold is synchronous at ingest, bounded by a 5s per-call timeout, and reservation happens before any AploCard call: ReserveLoyaltySaga inserts a delivery_loyalty_saga row (state holding) in its own small transaction, keyed by the deterministic order id, before the coupon/bonus hold calls. This row deliberately has no FK to delivery_orders (a failed hold must leave no order behind, so the order row may not exist yet when the saga row is written). A retried request for the same externalOrderId/order id sees the existing row and resumes instead of re-holding: held legs are reused as-is, failed legs are retried, a holding leg (mid-flight or crashed) is treated as in-progress and the caller is told to retry shortly. A leg stuck holding for more than ~1 minute (well above the 5s call timeout) is cleaned up by a dedicated reaper sweep independent of the spec's own 30-minute hold-not-verified reaper - see internal/loyaltysaga.Worker.resolveStuckHold. This narrows, but does not eliminate, the crash window between "AploCard call succeeded" and "we recorded it" - accepted risk, documented in code.
• Resuming a retry must use the ALREADY-HELD amounts, not a fresh recalculation. A fresh /calculate after a successful hold reflects the wallet balance the hold already reduced (a lower cap) or a coupon that may no longer preview as applicable - recalculating naively would permanently mismatch the calculationId token signed on the first attempt. checkout.Input.HeldCouponDiscountMinor/HeldBonusSpendMinor override the fresh derivation with the saga's recorded amounts; internal/service.IngressCheckout reads the saga row first for exactly this reason.
• payload.Items[i].Price and payment.amountMinor are independently re-verified against the fresh catalog/total, not just the signed token. The token binds catalog prices at calculate time; a partner could otherwise send an internally-consistent cart (own total matches own per-line prices, so the existing Validate() invariant passes) with a forged per-line price and a still-valid token. Any mismatch is 409 price_changed.
• Checkout item ids are the iiko productId directly (as this section already specifies) - BuildDeliveryCommand now falls back to parsing the item id as a UUID when no explicit product-mapping row exists, gated on the order actually being a checkout order (payload.Payment != nil). The legacy call_center/mobile_app path is unaffected and still requires an explicit mapping row.
• payment.code and the order's appliedDiscounts are server-authoritative even though they round-trip through the same JSON struct a partner could set them on. The checkout service unconditionally overwrites both right after decode/hold, before hashing/persisting - this is the guest-money trust boundary, and it is documented loudly at the struct definitions (domain.Payment, domain.AppliedDiscounts) so a future change does not casually skip the overwrite.
• payment.amountMinor for cash/card_on_delivery gets a POS payment-type code from DELIVERY_PAYMENT_CODE_CASH/DELIVERY_PAYMENT_CODE_CARD_ON_DELIVERY (tenant-wide env, not per-point). The spec's "configurable codes… per point" is narrower in this phase - a real per-point config surface belongs in §8's operator admin, which is out of scope for phase 3. Online always resolves to ECARD per the phase-0 probe finding (ECRDL deleted).
• accrue's items[].amount is an int at AploCard; checkout quantities are decimal strings. Rounded to the nearest integer, minimum 1 for any positive quantity (internal/loyaltysaga.roundQuantity, mirrored in the ingest-time loyalty /calculate preview by internal/service.checkoutItemAmount). Not expected to matter in practice - dishes are sold as whole units - but flagged as a real, if narrow, rounding deviation.
• sourceRefId = order id is reused unmodified for hold and accrue despite them being different AploCard resources (wallet-transaction hold vs. accrual): verified the engine's idempotency key for Accrue is scoped to (organization, source, source_ref_id, tx_type='accrual'), so it cannot collide with a hold row (tx_type presumably hold/debit). No namespacing needed.
• RESOLVED 2026-09-23 (owner decision, was the open "slow order" leak above): the reaper no longer releases a hold on a timer alone. repository.FindExpiredLoyaltyHolds classifies each held-past-deadline leg by the order's actual state (ExpiredLoyaltyHoldKind: orphaned/terminal_failed/queued/in_flight) instead of the old blanket "not created_verified/manual_review ⇒ release" predicate. internal/loyaltysaga.Worker.resolveExpiredHold acts on each: orphaned/terminal_failed release immediately via ReleaseExpiredLoyaltyHold (nothing can consume them - no order, or the order's own release already tried and is stuck); queued calls the SAME repository.Cancel the partner-facing §2.1 endpoint uses, which cancels the order outright and releases the hold in that one transaction (safe - no plugin ever claimed it); in_flight (claimed/prepared/create_sending/reconciliation_required) ALSO calls repository.Cancel, but that method's own logic for those states only sets cancel_state=requested and does not touch the loyalty outbox - the hold stays held until the order genuinely reaches rejected_final/cancelled (releasing it then, via the pre-existing step-3 enqueueLoyaltyOutbox on that transition) or created_verified (confirming it via step 2, discount intact). Either way a Михалыч alert fires (DELIVERY_MIHALYCH_TOKEN_FILE, internal/mihalych) so a human sees the stuck order, not just a partner-facing webhook. This closes option (b) from the original three, refined: cancellation is requested immediately (an honest signal) but the money-losing release is deferred to the actual terminal transition, not driven by the reaper itself.
• verifyOrderable also gates the crash-resume path, on purpose - worth knowing before someone "fixes" it. If an item enters the stop-list between the original hold and a retry, the retry correctly 409s (spec: never let a stop-listed line reach the POS) - but the hold stays held with no order until either the guest gives up or the 30-minute reaper releases it. This is the intended trade-off (safety over availability) but is easy to mistake for a bug when someone notices a held saga row with no matching order for up to 30 minutes.
• Open question for the owner: AploCard's write routes (hold, coupon/hold, confirm, cancel, coupon/confirm, coupon/cancel) are rate-limited 5 req/min per key. A coupon+bonus order is 2 holds + up to 2 confirms = 4 writes against that budget, meaning the whole ViL site is effectively capped at roughly one loyalty-bearing order per minute on a single API key before partners see 429/hold_in_progress retries pile up. Not a phase-3 code fix - either AploCard needs a higher per-key limit for this integration, or the site needs multiple keys/some other mitigation. Flagging this before it is discovered in production.
• DeliveryStatusCancelled after created_verified (a guest-cancelled order the POS already created and whose loyalty was already confirmed) does not release the confirmed coupon/bonus. This matches the spec's own wording literally (only created_verified/rejected_final/cancelled creation-states drive the saga; delivery-status-level cancellation is a separate, unaddressed case) but is worth an explicit decision from the owner: is a post-confirmation delivery cancellation supposed to also reverse the loyalty spend (a refund-style flow), or is that intentionally a manual/support-driven process?
• Guest-phone rate limiting (spec §7, 30 calls/min) is in-memory, per service instance. Exact on a single instance (today's deployment shape); on N horizontally-scaled instances the effective ceiling becomes 30×N. A Redis-backed limiter is the natural upgrade if/when this service scales out - not built now to avoid a new external dependency for a phase that does not need it yet.
• accrue_state's not_applicable value exists in migration 009's CHECK constraint but nothing in this phase sets it. Every checkout order that reaches AploCard tracking gets a saga row and eventually pending → queued → accrued|failed; not_applicable is reserved for a future distinction (e.g. an order type the accrual rule set explicitly excludes) that phase 3 does not need to make.
• StateManualReview holds are permanent with no automated release path, by design (the reaper explicitly excludes manual_review orders, matching "a manual_review status leaves the holds held and opens an alert" above) - but there is currently no alert beyond a structured log line from the reaper sweep, and §8's operator admin (where an actual hold-release action would live) is out of scope for this phase. An operator with a manual_review order today has no UI path to release its hold; treat this as a required follow-up, not a hidden gap.
• Checkout order items do not carry modifiers. internal/service.toCheckoutItems maps domain.Item to checkout.RequestItem{ID, Quantity} only - Item.Modifiers is silently dropped from pricing/verification even though CanonicalOrder.Validate() still requires Total to account for modifier prices the partner sent. A checkout order with modifiers will fail verifyNoTampering's line-price check (or pass by accident if the modifier total happens to be zero) rather than pricing the modifier from our catalog. Checkout does not support modifiers yet - flag this to partners/product before anyone tries to sell a modified dish through the checkout flow.
• A money-leak edge case (hold succeeds, order Create fails, the 30-minute reaper releases the hold, the partner retries) is closed, not merely documented as accepted risk: internal/service.IngressCheckout only counts a leg's discount toward appliedDiscounts when that leg is held or confirmed (never cancelled/failed), and attemptHold only restarts a cancelled leg when the caller has independently confirmed via GetByID that the order does not exist yet - restarting one for an order that already exists would orphan a second, uncorrelated hold. Both branches (safe restart; refused restart when the order exists, which then surfaces as an ordinary idempotency conflict) have tests.
• A second gap closed the same review pass: checkout.Calculate only warns about an unknown/stop-listed line or an unmet minimum/unserviceable delivery - it does not refuse to price them. internal/service.verifyOrderable is a hard gate in IngressCheckout, run right after the calculationId itself verifies: any line with a non-empty Warning, or !MinOrder.Met, or !DeliveryServiceable, rejects with the same 409 price_changed a genuine price mismatch would - the token can be entirely honest (nothing changed since calculate) and the order must still not reach the POS with a stop-listed line at full price or an unknown item at price 0 via the checkout product-id passthrough.
• Loyalty discount/gift-to-POS mapping (phase 3 follow-up, owner decision 2026-09-23), shipped: "Скидку на заказ надо привязывать к скидке в айке по ID - блюда в подарок - к блюду с 0-й ценой из айки. Акционное блюдо - к акционному блюду." A new operator-managed table, delivery_loyalty_discount_mapping (migration 010, kinds order_discount/gift_product/promo_product), translates AploCard's calculate-time result to iiko entities: every discounts[] entry (checkout.Calculate already counts each one in exactly one of ProgramDiscountMinor/Coupon.DiscountMinor regardless of whether it is coupon- or automatic-program-driven - loyaltyProgramResults/ProgramResults turned out to be unused by pricing entirely) maps by code to an iiko discountTypeId; every freeProducts[] entry maps by productId under either the gift or promo kind (the engine contract does not distinguish them at this field - open question below). An unmapped entry, or a mapped sum that does not equal what checkout.Calculate already verified against payment.amountMinor, rejects the order outright (422 loyalty_unmapped) before any AploCard hold is attempted - never a silently dropped or invented discount. catalog.BuildMenu/CatalogItem.Hidden now always stores a zero-price catalog item (instead of dropping it, phase-1's behavior) so it can be a gift_product/promo_product mapping target while staying off the partner-facing menu. domain.MappedDiscount/GiftLine on CanonicalOrder and domain.CommandDiscount/CommandGiftLine on DeliveryCommand carry the mapped result to the plugin (plugin/WIRE_CONTRACT.md's new discounts/giftLines section - Front API IOperationService.GetDiscountTypeById + IEditSession.AddFlexibleSumDiscount for discounts, AddOrderProductItem at predefinedPrice:0 for gift lines; plugin implementation is a separate, not-yet-started change). Open question for the owner, not a phase-3 code decision: the AploCard /calculate contract has no field distinguishing "gift" from "promo" - both arrive as freeProducts[].productId with no semantic tag, so this implementation tries gift_product then promo_product for the same key and lets the operator record which is which purely for their own bookkeeping. If AploCard is ever meant to actually differentiate them (e.g. different receipt text, different reporting), the engine contract needs a new field first.
• Hidden item ordered directly, closed (advisor review, round-2): a reviewer flagged - unverified - that a Hidden (zero-price gift/promo) catalog item could in principle be ordered as an ordinary cart line via the checkout product-id passthrough (BuildDeliveryCommand's UUID fallback), double-counting against a mapped giftLines[] entry for the same physical item on the same order. Checked and confirmed possible before this fix (the item WAS present, just priced 0, in the unfiltered catalog buildCheckoutInput reads). Closed with a dedicated checkout.Calculate warning ("hidden_item", distinct from "stop_list") and internal/service.verifyOrderable rejecting it as 422 product_not_orderable before any hold/order-creation - never the same 409 a genuinely stop-listed item gets, since this is categorical, not transient.
• Bonus spend never reached the POS, critical gap closed (round-2 review, owner decision 2026-09-23): mapLoyaltyResult/verifyMappedLoyaltyInvariant originally covered only program+coupon discounts - bonus spend was subtracted from payment.amountMinor (so the signed total was correct) but was never told to the POS as anything, so the cheque itself never balanced on ANY bonus-spending order (cart 100000, bonus 20000 ⇒ payment.amountMinor 80000, POS order total unchanged at 100000). Owner's decision, verbatim: "Там уже есть вкус коины, мы используем ту же самую валюту — вкус коины" - ViL's live iiko already has an external/processed VKUS2 | Вкускоин | kind Card | processing Both payment type (never VKUS3, which is kind IikoCard | processing Internal and cannot be added externally). Bonus spend now rides to the POS as a SECOND payment entry of code DELIVERY_PAYMENT_CODE_BONUS (default VKUS2), additive alongside the existing singular payment field via the new domain.CommandPaymentEntry/DeliveryCommand.Payments (plugin/WIRE_CONTRACT.md's new payments[] section). verifyMappedLoyaltyInvariant was extended from "mapped-discounts-sum matches the priced discount" to the full server-side invariant the owner specified: Σ(line prices at catalog price) + gift lines(0) - Σ(discounts[].sumMinor) + delivery fee == Σ(payments[].amountMinor), checked after the hold attempt (once the actually-held bonus amount is known) rather than at the earlier fail-fast unmapped-discount check.
• The Postgres loyalty repository path (migration 009 tables) has no coverage against a real database anywhere in this branch. One pgxmock test (TestReserveLoyaltySagaScansNullCouponCode) exercises scanLoyaltySaga/ReserveLoyaltySaga against a mocked row shaped like a no-coupon order - it caught and pins the fix for a real bug (the nullable coupon_code column was scanned into a non-pointer string, which pgx v5 refuses on NULL) - but pgxmock does not reproduce pgx's actual NULL-into-non-pointer error (verified: reverting the fix locally still passes that test against pgxmock), so it is not proof against a live database, only a plausibility check. Every other Postgres method added in this phase (UpdateLoyaltyLeg, DueLoyaltyOutbox, FindExpiredLoyaltyHolds/ReleaseExpiredLoyaltyHold, SetLoyaltyAccrueResult, RecordLoyaltyAudit, EnqueueOrderWebhook, the enqueueLoyaltyOutbox/enqueueLoyaltyAccrue transaction hooks) is untested beyond compiling and passing go vet. Running the full checkout+saga flow against a real (even sandbox) Postgres instance before this ships is a hard prerequisite, not a nice-to-have.
  • UPDATE 2026-09-23 (mid-DS review round): this is now partially addressed - postgres_integration_test.go (build tag pgintegration) runs against a copy of the production database and exercises Create, Cancel, AppendEvent's loyalty-outbox hooks, FindStuckLoyaltyHolds, FindExpiredLoyaltyHolds/ReleaseExpiredLoyaltyHold, RecordLoyaltyAudit, org-mapping lookup, concurrent-create races, RestartLoyaltyHold, SetLoyaltyAccrueResult, RecordDeliveryStatus, and outbox leasing. Still not covered live: the queued/in_flight branches of FindExpiredLoyaltyHolds' classification (proved only against repository.Memory, which mirrors the same CASE the Postgres query uses - kept off the integration suite deliberately, see the comment on TestPostgresIntegrationCancelWritesLoyaltyOutboxAndWebhookEvent, to avoid growing the number of permanent delivery_orders rows left in the shared database copy) and a live AploCard sandbox call of any kind.
• The idempotent-retry-vs-confirmed-legs gap (advisor mid-DS review M1, fixed 2026-09-23): a retry of POST /v1/orders for an externalOrderId whose order already reached created_verified used to re-derive a fresh price and fail with a spurious 409 price_changed. internal/service.IngressCheckout only reused held amounts (checkout_ingress.go's crash-resume block), never confirmed ones - but a leg only ever becomes confirmed once the order already exists (loyaltysaga.Worker.confirm, driven off the created_verified transition), so recalculating for a retry at that point compared a stale signed total against numbers AploCard could no longer reproduce (the discount was already spent). Fixed by short-circuiting before any recalculation: if the order already exists, Service.replayExistingOrder copies Payment.Code/AppliedDiscounts straight off the STORED order (immutable once created) rather than re-deriving them from the current saga (an earlier version of the fix did that, and returned ErrPayloadConflict on an ordinary retry if a leg happened to drift, e.g. confirmed→released by an unrelated later cancellation) - then defers to repository.Create's existing idempotent-replay-by-hash logic on the rest of the payload. A genuine conflict (same externalOrderId, materially different order content elsewhere) still surfaces ErrPayloadConflict unchanged.
• The delivery total was priced correctly but never sent to the POS as a line, closed (delivery-fee-line follow-up, owner decision 2026-09-23). checkout.Result.DeliveryFeeMinor/payload.Payment.AmountMinor always included the zone fee - the price the guest saw and paid was always right - but nothing in domain.BuildDeliveryCommand's output told the plugin to charge for delivery at the POS, so a fee-bearing order's created iiko order total fell short by exactly the fee. domain.CanonicalOrder gained DeliveryFeeMinor/DeliveryFeeProductID (server-authoritative, same overwrite-after-decode trust boundary as Payment.Code, set once in IngressCheckout and replayed unchanged on retry - internal/repository builds the wire command from the STORED order at claim time, long after the request's config is gone), and DeliveryCommand gained an additive DeliveryFeeLine (plugin/WIRE_CONTRACT.md's new deliveryFeeLine section) populated only when the fee is non-zero and DELIVERY_FEE_PRODUCT_ID is configured - "fee 0 ⇒ no line, pickup ⇒ no line" naturally follow, since a pickup order's DeliveryPricer quote is always 0. verifyMappedLoyaltyInvariant now takes the delivery-fee amount as an explicit parameter (the exact value that becomes the wire line) rather than reading it implicitly off checkout.Result.

5. Guest

• GET /v1/guests/{phone}/loyalty: balances per program, level/category, and active coupons. This uses AploCard via our server key.
• GET /v1/guests/{phone}/orders?limit&cursor: orders of this partner's source for this phone, newest first, with statuses (from our DB).
• GET /v1/guests/{phone}/addresses: last used delivery addresses (from our orders).
• Phone normalisation: E.164 +7XXXXXXXXXX. Invalid gives 400 invalid_phone.
• Trust model (must be in the docs, bold): the partner backend is trusted to assert the guest's phone. It must authenticate the guest itself (SMS/login) before calling guest or loyalty endpoints. Every guest/loyalty call is written to an audit log (partner, phone hash, route, result, no plain phone). Separate rate limit per phone (§7).
• PROPOSED, owner sign-off pending (phase 3 follow-up, 2026-09-23): this same trust model applies to §4's checkout endpoints, not only the not-yet-deployed §5 ones above - POST /v1/checkout/calculate/POST /v1/orders use guest.phone directly against AploCard (balance/coupon/hold) BEFORE any order exists, exactly the same "we trust the caller's phone" exposure this bullet already documents for GET /v1/guests/.... It was never a separate explicit decision when checkout shipped; extending the existing rule here is the logical continuation, but is recorded as proposed, not settled, until the owner confirms. See docs/portal/policies/security.md's guest-trust-model section and the new docs/portal/guides/checkout.md stub (same "proposed" marking, kept in sync).

6. Webhooks (extended)

New event types: menu.updated, stoplist.updated, point.status_changed, order.payment_recorded, order.loyalty_confirmed, order.loyalty_released, order.accrued. Same signing, outbox, retries and dedupe as today. Subscriptions are per event type in the credential config (webhookEvents, default all).

7. Operability

• Rate limits (fixes the known gap): per credential 600 req/min; per IP 100 req/min for unauthenticated/failed-auth traffic; per guest phone 30 loyalty calls/min. The response is 429 + Retry-After + X-RateLimit-Limit/Remaining/Reset.
• X-Request-ID is echoed on every response and logged. A support request quotes it.
• GET /v1/health stays public. GET /v1/status (auth) reports sync freshness per source.
• Idempotency: POST /v1/orders by externalOrderId, cancel by order. Every other POST is read-only or idempotent by body hash.
• Structured JSON logs without PII. Metrics: request rate/latency/error by route, sync lag per source, loyalty saga states, webhook backlog.

8. Operator/admin (minimal, AploKey SSO, roles)

Point metadata (name, phone, schedule), zones (source B), payment-type mapping per point, partner credentials (issue/rotate API key and webhook secret, event subscriptions, point allowlist). The admin UI is a later phase. The first cut is an admin JSON API + CLI. authz → Sonnet gate.

9. Corporate-grade documentation (deliverable, same priority as code)

Published developer portal served by the service at /docs (static, versioned):

1. API reference: OpenAPI 3.1 (single source of truth, lint-clean with Spectral), rendered with Redoc. Every field has a description, example, units and enum meanings.
2. Guides (RU): Quick start (first signed call in 10 min); Authentication and signing (with test vectors); Checkout flow end-to-end (sequence diagram); Menu and stop-list sync strategy; Delivery zones and address resolution; Loyalty (coupons, bonuses, trust model); Payments (online before creation, cash, change); Order lifecycle and statuses (state diagram, customer-facing RU labels); Cancellation rules; Webhooks (verification, retries, dedupe); Errors catalogue (every code, cause, action); Rate limits; Idempotency; Go-live checklist.
3. Policies: versioning and deprecation (additive changes any time; breaking changes only in a new major, with ≥ 90 days notice), changelog (dated, per release), support and escalation contacts, SLA/SLO (availability target, sync freshness), security (key storage, rotation, IP allowlist option, PII).
4. Sandbox: separate tenant and keys on staging, with a POS simulator that walks orders through statuses (configurable delays, failure scenarios: stop-list, price change, cancel rejected), a fake point with a menu, and zones.
5. SDK and examples: Go SDK (pkg/ingressclient, all endpoints + webhook verification), a Postman collection, curl examples for every endpoint, and a signature test-vector file.
6. Docs are tested: examples in the guide are executed in CI against the sandbox (doc-tests), and the OpenAPI is validated against real handler responses (contract tests).

10. Phases and acceptance

Security gate: credentials, scoping, guest/loyalty endpoints, audit and rate limiting are written and reviewed by Sonnet (web-developer). Everything else follows the peer-review chain.