Zum Hauptinhalt springen

Integrator Guide

This guide is for developers connecting any external system to the Digital Retail Engine (DRE) — point-of-sale terminals, e-commerce / webshop backends, CRM and marketing platforms, ERP and master-data systems. DRE is channel-agnostic: if your system has a basket (or needs promotion master data, or issues coupons), it can integrate. There is no vendor- or plugin-specific contract — every integration speaks the same JSON-over-REST and OData V4 surfaces described here.

It covers authentication (cloud and local), the POS REST endpoints, the evaluate → confirm transaction lifecycle, the coupon lifecycle, every promotion action and how it surfaces on the wire, and the patterns for writing your own adapter.

Who this is for​

You are building…Start with
A POS / checkout integration (real-time discounts at the till)POS endpoints → Evaluate → Confirm lifecycle
A webshop / e-commerce cart integrationEvaluate → Confirm lifecycle — use /v2/simulate for live cart preview
A CRM / marketing integration (issue & track coupons)Coupon lifecycle
An ERP / master-data integration (articles, budgets, promotion sync)Promotions API + article import
Your own channel adapter from scratchBuilding an integration

Two integration surfaces​

DRE exposes two distinct surfaces with different purposes. Pick by what you need; most integrations use both.

  1. Real-time evaluation — the POS Service (/pos), action-based. You POST a basket to POST /pos/v2/evaluate and get back every promotion's effect inline on the line it touched. At checkout you POST /pos/v2/confirm, which writes side effects — budget consumption, coupon redemption, loyalty points, calculation audit log. There is no readable Promotions collection on /pos; it is a pure action API.
  2. Master-data read — the Admin Service (/admin), OData V4. To read promotion definitions (for caching, display, or incremental sync) use GET /admin/Promotions. See Promotions API.

Topics​

  1. Authentication — OAuth 2.0 / JWT against SAP BTP, and API-key / session auth against a local-store instance.
  2. POS endpoints — the complete /pos REST surface and what each endpoint does.
  3. Evaluate → Confirm lifecycle — the transaction flow, the iteration-identity tuple, and synchronous vs asynchronous side effects.
  4. Coupon lifecycle — the coupon state machine, generation, reservation, redemption, and post-purchase issuance.
  5. Promotion scenarios & actions — line vs receipt promotions, and every action type with a request/response pair.
  6. Promotions API — read promotion master data via GET /admin/Promotions (OData V4).
  7. Building an integration — vendor-neutral patterns for mapping your basket to DRE and back, with resilience and performance guidance.
  8. Recommendation hint catalog — the stable code values used in recommendations[].

Key principles​

  • Channel-agnostic. The same /pos contract serves a till, a webshop checkout, a kiosk, or a call-center order screen. Nothing in the API assumes a physical terminal.
  • Protocols. The POS contract is plain JSON over REST. The Admin, Public, and Reporting services follow OData V4 conventions.
  • Idempotent reads. OData GET requests are safe to retry. POST actions that write (/confirm, coupon redeem) are not idempotent — see the relevant pages.
  • Correlation. Carry a stable lineReference per basket line and the (tenantId, transactionId, transactionCounter) tuple across evaluate → confirm so every effect is traceable.
  • Pagination. Use $top / $skip for large OData result sets.