Produktsicherungs-PlattformProtection Platform

GROW

Hardware-inklusive Plattform für EAS, RFID, NFC/HF, Handheld und gesicherte Einbauten – von einfacher manueller Deaktivierung bis zu richtliniengesteuerten Mehrkanal-Flows.Hardware-inclusive platform for EAS, RFID, NFC/HF, handhelds, and secured fixtures – from simple manual deactivation to policy-driven omnichannel flows.

Diese Seite beschreibt die vollständige Schutzarchitektur: das Drei-Schichten-Modell, das Hardware-Capability-Register, artikelbezogene Autorisierung, das normalisierte Event-Schema (EPCIS-kompatibel), richtlinienbasierte Regeln und Offline-Tokens. Die klassische verifySecurityTagDeactivation-API bleibt vollständig kompatibel.This page describes the full protection architecture: the three-layer model, the hardware capability registry, item-level authorization, the normalised event schema (EPCIS-aligned), policy-based rules, and offline tokens. The classic verifySecurityTagDeactivation API remains fully backward-compatible.

1. Drei-Schichten-Datenmodell1. Three-layer data model

Das frühere securityTagMode-Feld wurde in drei orthogonale Dimensionen aufgeteilt: Technologie, Gerät und Workflow. So können alle gängigen Kombination – POS-integrierte Deaktivatoren, manuelle und elektrische Detacher, mehrere Installationstypen – ohne Hardcoding abgebildet werden.

The former single securityTagMode field is replaced by three orthogonal dimensions: technology, device, and workflow. This lets every real-world combination – POS-integrated deactivators, manual and powered detachers, multiple installation types – be represented without hard-coding store-specific branches.

Migration: securityTagMode bleibt gültig (siehe Abschnitt 17). Die neuen Felder sind optional und additiv.Migration: securityTagMode remains valid (see section 17). The new fields are optional and additive.

`protectionTechnology`

Value	BeschreibungDescription
`am`	Akustisch-Magnetisch – 58 kHz Schmetterling-/WeichetikettAcoustic-magnetic – 58 kHz butterfly / soft label
`rf`	Radio-Frequenz – 8.2 MHz Weichetikett oder HardetikettRadio-frequency – 8.2 MHz soft label or hard tag
`uhf_rfid`	UHF-RFID – 860–960 MHz, EPC Gen2 / GS1 EPCIS-kompatibelUHF RFID – 860–960 MHz, EPC Gen2 / GS1 EPCIS-aligned
`hf_nfc`	HF/NFC – 13.56 MHz (ISO 15693 / NfcV, ISO 14443 / NfcA, NfcB, IsoDep)HF/NFC – 13.56 MHz (ISO 15693 / NfcV, ISO 14443 / NfcA, NfcB, IsoDep)
`mechanical_lock`	Mechanische Sicherung – Spider Wrap, Bottle Tag, Cable Lock, Keeper CaseMechanical lock – spider wrap, bottle tag, cable lock, keeper case

`deviceType`

Value	BeschreibungDescription
`pos_deactivator`	POS-integrierter Deaktivator (z. B. Sensormatic am Kassentisch)POS-integrated deactivator (e.g. Sensormatic at checkout counter)
`self_checkout_detacher`	Self-Checkout-Detacher-Station – Kunde bedient selbstSelf-checkout detacher station – customer-operated
`exit_gate`	Ausgangsgate (EAS-Alarmbügel oder RFID-Gate)Exit gate (EAS pedestal or RFID portal)
`handheld_reader`	Mobiles Handheld-Lesegerät für MitarbeiterAssociate handheld reader / scanner
`cabinet_unlocker`	Schrank- oder Vitrinenentriegelung nach BezahlungCabinet / showcase unlocker triggered after payment

`workflowType`

Value	BeschreibungDescription
`staff_assisted`	Mitarbeiter führt Deaktivierung oder Entsperrung durchStaff member performs deactivation or unlock
`self_service`	Kunde agiert selbst an einer Station (QR-Scan + automatische Freigabe)Customer acts at a station (QR scan + automated release)
`automatic_exit`	Gate/Alarm reagiert automatisch auf bezahlte ArtikelGate/alarm responds automatically to paid items
`pos_integrated`	POS-System löst Deaktivierung direkt beim Kassieren ausPOS system triggers deactivation directly during checkout

Store-Konfiguration (Beispiel)Store configuration (example)

stores/{storeId} – three-layer fields

{ // Legacy field – still honoured (backward compat) "securityTagMode": "station", // New three-layer model (additive) "protectionTechnology": "am", // am | rf | uhf_rfid | hf_nfc | mechanical_lock "deviceType": "self_checkout_detacher", // pos_deactivator | self_checkout_detacher | exit_gate | handheld_reader | cabinet_unlocker "workflowType": "self_service", // staff_assisted | self_service | automatic_exit | pos_integrated "securityTagHint": "Bitte Etikett an der Detacher-Station am Ausgang entfernen." }

2. Hardware-Capability-Register2. Hardware capability registry

Das Geräteverzeichnis devices/{deviceId} beschreibt die Fähigkeiten jedes installierten Geräts. Damit können Store-Steuerprogramme und Checkout-Flows ohne hardkodierte Filiallogik arbeiten und spätere Partnerintegrations-Rollouts werden vereinfacht.

The device registry at devices/{deviceId} describes the capabilities of every registered hardware unit. Store logic and checkout flows can reason about available hardware without store-specific hard-coding, and staged partner-integration rollouts become straightforward.

devices/{deviceId}

{ "deviceId": "dev_sco_01", "deviceType": "self_checkout_detacher", "storeId": "store_123", "zoneId": "zone_exit_a", "laneId": "lane_02", "firmwareVersion": "3.14.1", // Capability flags "canDeactivateLabel": true, "canDetachHardTag": false, "canReadReceiptQr": true, "canReadUhfRfid": false, "canReadHfNfc": false, "canUnlockFixture": false, "supportsOfflineAuth": true, // Which protection technologies this device handles "supportedTechnologies": ["am", "rf"], "registeredAt": "2026-01-12T09:00:00Z", "lastSeenAt": "2026-03-30T07:41:00Z" }

Capability-FelderCapability fields

Field	Type	BeschreibungDescription
`canDeactivateLabel`	boolean	Kann AM/RF-Etiketten deaktivieren (elektromagnetisch)Can electromagnetically deactivate AM/RF labels
`canDetachHardTag`	boolean	Kann mechanische Hardetiketten entriegelnCan mechanically release hard tags
`canReadReceiptQr`	boolean	Kann QR-Code vom digitalen Kassenbon scannenCan scan QR code from digital receipt
`canReadUhfRfid`	boolean	Kann UHF-RFID-EPCs (860–960 MHz) lesenCan read UHF RFID EPCs (860–960 MHz)
`canReadHfNfc`	boolean	Kann HF/NFC-Tags (13.56 MHz) lesenCan read HF/NFC tags (13.56 MHz)
`canUnlockFixture`	boolean	Kann Vitrine, Schrank oder Kabelschloss öffnenCan unlock showcase, cabinet, or cable lock
`supportsOfflineAuth`	boolean	Akzeptiert offline-signierte Autorisierungs-Tokens bei schlechter KonnektivitätAccepts offline-signed authorization tokens under degraded connectivity
`supportedTechnologies[]`	string[]	Liste der unterstützten `protectionTechnology`-WerteList of supported `protectionTechnology` values

3. Artikelbezogene Autorisierung3. Item-level authorization

BEEP! bietet zwei komplementäre Autorisierungspfade. Einfache Integrationen nutzen weiterhin den kaufbezogenen Endpunkt. Fortgeschrittene RFID-Systeme wählen den artikelbezogenen Pfad, der mit dem GS1-EPCIS-Ansatz übereinstimmt (Ereignisse über identifizierte Objekte statt über Körbe).

BEEP! exposes two complementary authorization paths. Simple integrations continue to use the purchase-based endpoint. Advanced RFID systems choose the item-level path, which aligns with the GS1 EPCIS approach (events about identified objects rather than baskets).

Pfad A – Kaufbezogen (Legacy + einfache Integrationen)Path A – Purchase-based (legacy + simple integrations)

POST /api/v1/verifySecurityTagDeactivation Kauf-Deaktivierung verifizieren (Legacy)Verify purchase deactivation (legacy) GROW

Unverändert vom bisherigen Verhalten. Gibt an, ob ein Kauf bezahlt wurde und die Deaktivierung freigegeben ist. Für neue Integrationen wird Pfad B empfohlen.

Unchanged from existing behaviour. Returns whether a purchase is paid and deactivation is authorized. For new integrations Path B is recommended.

Parameter	Type	Required	BeschreibungDescription
`purchaseId`	string	optional*	Purchase-Dokument-IDPurchase document ID
`receiptToken`	string	optional*	QR-Code-Token vom digitalen KassenbonQR code token from digital receipt
`deviceId`	string	optional	Gerät, das die Anfrage stellt (für Audit & Analytics)Device making the request (for audit & analytics)
`Idempotency-Key`	header	optional	Verhindert Doppelaktionen bei WiederholungsanfragenPrevents double-actions on retries

* Mindestens purchaseId oder receiptToken muss angegeben werden.* At least purchaseId or receiptToken must be provided.

200 OK – Path A response

{ "success": true, "status": "paid", "deactivationAuthorized": true, "authorizationState": "issued", // issued | redeemed | expired | revoked // Offline-safe token (if device supportsOfflineAuth) "authorizationToken": "eyJ...", "expiresAt": "2026-03-30T08:10:00Z", "replayProtectedNonce": "nonce_7f3a...", "items": [ { "name": "Slim Fit Jeans", "priceUnit": 4999, "quantity": 1 } ], "securityTagMode": "station", "storeData": { "name": "Fashion Store" } }

Pfad B – Artikelbezogen (RFID / EPCIS-ausgerichtet)Path B – Item-level (RFID / EPCIS-aligned)

POST /api/v1/verifyProtectedItem Artikelschutz-Aktion autorisierenAuthorize protected item action GROW

Für Systeme, die auf Basis einzelner identifizierter Artikel (EPC, Tag-UID, Warenpositions-ID) entscheiden – analog zu GS1 EPCIS, das Ereignisse über identifizierte Objekte modelliert.

For systems that reason about individual identified items (EPC, tag UID, item line ID) – consistent with GS1 EPCIS, which models events about identified objects.

Parameter	Type	Required	BeschreibungDescription
`tagId`	string	optional*	Proprietäre Etikett-IDProprietary tag identifier
`epc`	string	optional*	GS1 EPC (UHF RFID) – z. B. `3014257BF400000000001A05`GS1 EPC (UHF RFID) – e.g. `3014257BF400000000001A05`
`tagUid`	string	optional*	NFC/HF-Tag-UID (HEX) für NfcA, NfcB, NfcV, IsoDepNFC/HF tag UID (hex) for NfcA, NfcB, NfcV, IsoDep
`itemLineId`	string	optional*	Warenpositons-ID aus dem Kauf-DokumentItem line ID from the purchase document
`deviceId`	string	required	Gerät, das die Anfrage stelltDevice making the request
`protectionAction`	string	required	Gewünschte Aktion (siehe § 5)Requested action (see § 5)
`scanSource`	string	optional	Quelle des Scans (siehe § 9)Source of the scan (see § 9)
`storeId`	string	optional	Filiale – wird aus `deviceId` abgeleitet wenn nicht angegebenStore – inferred from `deviceId` if omitted
`occurredAt`	string (ISO 8601)	optional	Geräteseitige Ereigniszeit (für Offline-Batches)Device-side event time (for offline batches)
`Idempotency-Key`	header	optional	Idempotenz-Schlüssel gegen DoppelaktionenIdempotency key to prevent double-actions

* Mindestens ein Artikel-Identifier (tagId, epc, tagUid oder itemLineId) ist erforderlich.* At least one item identifier (tagId, epc, tagUid, or itemLineId) is required.

200 OK – Path B response

{ "success": true, "authorized": true, "protectionAction": "deactivate_label", "authorizationState": "issued", // Offline-safe token "authorizationToken": "eyJ...", "expiresAt": "2026-03-30T08:10:00Z", "redeemedAt": null, "replayProtectedNonce": "nonce_9c1b...", // Minimal device-edge payload (no customer PII) "itemCount": 1, "itemStatus": "paid", "eventId": "evt_prot_8x72k..." }

4. EPC / NFC / HF-Identifier-Modell4. EPC / NFC / HF identifier model

UHF-RFID-Gates arbeiten typischerweise mit GS1-EPCs, während NFC/HF-Flows (z. B. Kunden-Smartphone, Handheld) auf Tag-UIDs und spezifischen Android-NFC-Technologietypen basieren. Beide Identifier-Klassen werden in einem gemeinsamen Modell unterstützt.

UHF RFID gates typically work with GS1 EPCs, while NFC/HF flows (e.g. customer phone, handheld) rely on tag UIDs and specific Android NFC technology types. Both identifier classes are supported in a single unified model.

Field	Type	AnwendungsfallUse case
`epc`	string?	GS1 EPC (UHF 860–960 MHz) – hexadezimale SGTIN/EPC URIGS1 EPC (UHF 860–960 MHz) – hex SGTIN/EPC URI
`tagUid`	string?	HF/NFC-Tag-UID (13.56 MHz) – ISO 15693 UID, ISO 14443 UIDHF/NFC tag UID (13.56 MHz) – ISO 15693 UID, ISO 14443 UID
`tagTechnology`	string?	Android-NFC-Technologieklasse: `NfcA` \| `NfcB` \| `NfcV` \| `IsoDep` \| `MifareClassic` \| `MifareUltralight`Android NFC technology class: `NfcA` \| `NfcB` \| `NfcV` \| `IsoDep` \| `MifareClassic` \| `MifareUltralight`
`serialNumber`	string?	Hersteller-Seriennummer des Etiketts (für proprietäre Protokolle)Vendor serial number of the tag (for proprietary protocols)
`itemLineId`	string?	Warenpositons-ID aus dem BEEP!-Kauf-Dokument (keine RF-Identifikation erforderlich)Item line ID from the BEEP! purchase document (no RF identification required)
`tagId`	string?	Proprietäre oder lesegerätspezifische Tag-ID (Legacy)Proprietary or reader-specific tag ID (legacy)

UHF vs. HF/NFC: UHF-RFID-Gates lesen EPCs aus bis zu ~5 m Entfernung. HF/NFC-Reads erfordern physische Nähe (< 10 cm) und werden am häufigsten von Smartphones oder Handhelds initiiert. Die beiden Pfade sind architektonisch getrennt – UHF-Gates nutzen bulk-EPC-Reads, NFC/HF-Geräte initiieren einzelne Session-Reads.UHF vs. HF/NFC: UHF RFID gates read EPCs at up to ~5 m. HF/NFC reads require close proximity (< 10 cm) and are most commonly initiated from phones or handhelds. The two paths are architecturally separate – UHF gates use bulk EPC reads, NFC/HF devices initiate individual session reads.

5. protectionAction-Enum5. protectionAction enum

Statt "Deaktivierung" wird die tatsächliche gewünschte Aktion modelliert. Das macht das Backend breit genug für Flaschensicherungen, Schränke, Kabelschlösser, Spider Wraps und zukünftige Einbauten.

Rather than "deactivation", the actual desired action is modelled. This makes the backend broad enough for bottle locks, cabinets, cable locks, spider wraps, and future fixture-control hardware.

`protectionAction`	BeschreibungDescription	Typische HardwareTypical hardware
`deactivate_label`	AM/RF-Etikett elektromagnetisch deaktivierenElectromagnetically deactivate AM/RF label	POS-Deaktivator, SCO-StationPOS deactivator, SCO station
`detach_hard_tag`	Magneto-mechanisches Hardetikett entriegelnRelease magneto-mechanical hard tag	Kassendetacher, SCO-DetacherCheckout detacher, SCO detacher
`suppress_alarm`	Gate-Alarm für diesen Artikel stumm schaltenSuppress gate alarm for this item	EAS-Gate (AM/RF)EAS pedestal (AM/RF)
`authorize_exit`	UHF-RFID-Gate: Artikelpassage genehmigenAuthorize item passage through UHF RFID gate	RFID-Exit-GateRFID exit gate
`unlock_fixture`	Schrank, Vitrine oder Kabelschloss öffnenUnlock cabinet, showcase, or cable lock	Cabinet-Controller, IoT-AktorCabinet controller, IoT actuator
`verify_item_status`	Nur Status abfragen, keine physische AktionQuery status only, no physical action	Handheld-Reader, BackofficeHandheld reader, back-office

6. Omnichannel-Artikelstatus6. Omnichannel item status

Moderne RFID/EAS-Plattformen (z. B. Nedap) entscheiden über Alarmverhalten anhand des Echtzeit-Artikelstatus über alle Kanäle – nicht nur anhand der lokalen Zahlungsverarbeitung. BEEP! modelliert diesen Status explizit.

Modern RFID/EAS platforms (e.g. Nedap) decide alarm behaviour from real-time item status across channels – not only local payment state. BEEP! models this status explicitly.

`itemStatus`	BedeutungMeaning	Gate/Alarm-VerhaltenGate/alarm behaviour
`sellable`	Im Regal, zum Kauf verfügbarOn shelf, available for purchase	Alarm bei PassgangAlarm on exit
`paid`	Kauf abgeschlossen und bezahltPurchase completed and paid	Kein Alarm – Aktion genehmigtNo alarm – action authorized
`reserved_bopis`	Reserviert für Click & CollectReserved for Click & Collect (BOPIS)	Alarm bis zur AbholungAlarm until pick-up confirmed
`picked_up`	Click & Collect abgeholtClick & Collect picked up	Kein AlarmNo alarm
`returned`	Zurückgegeben, werdend wiedereingelagertReturned, pending re-shelving	Alarm bis zur NeuaktivierungAlarm until re-activated
`transfer_in_transit`	Lagerübertrag in BearbeitungStock transfer in transit	Alarm unterdrückt (autorisierte Bewegung)Alarm suppressed (authorised movement)
`cancelled`	Kauf storniert oder Zahlung fehlgeschlagenPurchase cancelled or payment failed	Alarm bei PassgangAlarm on exit
`exception_hold`	Manueller Sperrung – Betrug, Schadensfall, PrüfungManual hold – fraud, damage, investigation	Alarm + Personal-BenachrichtigungAlarm + staff notification

7. Normalisiertes Event-Schema (EPCIS-kompatibel)7. Normalised event schema (EPCIS-aligned)

Jede Hardware-Interaktion erzeugt ein strukturiertes Ereignis nach dem GS1-EPCIS-Prinzip was / wann / wo / warum. Das ermöglicht spätere direkte EPCIS-Übersetzung.

Every hardware interaction emits a structured event following the GS1 EPCIS what / when / where / why principle. This allows direct EPCIS translation later.

Event-TypenEvent types

Event type	BeschreibungDescription
`protection.authorization.requested`	Gerät hat Autorisierungsanfrage gestelltDevice issued an authorization request
`protection.authorization.granted`	Autorisierung erteilt – Richtlinien erfülltAuthorization granted – policies satisfied
`protection.authorization.denied`	Autorisierung verweigert (mit Fehlercode)Authorization denied (with error code)
`protection.action.completed`	Hardware-Aktion erfolgreich abgeschlossenHardware action successfully completed
`protection.action.failed`	Hardware-Aktion fehlgeschlagen (mit Grund)Hardware action failed (with reason)
`protection.device.offline`	Gerät hat Offline-Token eingelöst (gepufferte Aktion)Device redeemed an offline token (buffered action)
`protection.exception.raised`	Ausnahme erfordert manuelle BearbeitungException raised requiring manual handling

Event-Payload (was / wann / wo / warum)Event payload (what / when / where / why)

Webhook: protection.action.completed

{ // ── WHAT ── "type": "protection.action.completed", "eventId": "evt_prot_8x72k...", "protectionAction": "deactivate_label", "protectionTechnology": "am", // ── WHEN ── "occurredAt": "2026-03-30T07:41:22.314Z", "processedAt": "2026-03-30T07:41:22.501Z", // ── WHERE ── "storeId": "store_123", "zoneId": "zone_exit_a", "gateId": null, "laneId": "lane_02", "deviceId": "dev_sco_01", "deviceType": "self_checkout_detacher", "firmwareVersion": "3.14.1", // ── WHY ── "purchaseId": "pur_abc123", "itemLineId": "line_01", "itemStatus": "paid", "workflowType": "self_service", "scanSource": "sco", "operatorId": null, // ── IDENTIFIERS ── "epc": null, "tagUid": null, "tagId": "AM-00451", "tagTechnology": null, // ── AUTH STATE ── "authorizationState": "redeemed", "replayProtectedNonce": "nonce_7f3a..." }

8. Gerätemetadaten8. Device metadata

Jede Verifizierungs- und Aktionsanfrage kann die folgenden Gerätemetadaten übermitteln. Diese Daten sind für Hardware-Debugging, Filialanalyse, Betrugsermittlung und Staged Rollouts über gemischte Hardware-Flotten essenziell.

Every verification and action request can carry the following device metadata. These fields are essential for debugging third-party hardware, store analytics, fraud investigation, and staged rollouts across mixed hardware fleets.

Field	Type	BeschreibungDescription
`deviceId`	string	Eindeutige Gerät-ID aus der Capability-RegistryUnique device ID from the capability registry
`deviceType`	string	Geräteklasse (aus `deviceType`-Enum)Device class (from `deviceType` enum)
`storeId`	string	FilialeStore
`zoneId`	string?	Zone innerhalb der Filiale (z. B. Ausgangsbereich)Zone within the store (e.g. exit area)
`gateId`	string?	Gate-ID für multi-gate-InstallationenGate ID for multi-gate installations
`laneId`	string?	Kassenlane oder SCO-BahnCheckout lane or SCO belt
`operatorId`	string?	Mitarbeiter-ID für Personal-assistierte WorkflowsAssociate ID for staff-assisted workflows
`occurredAt`	ISO 8601	Geräteseitige Ereigniszeit (offline-Puffer)Device-side event time (offline buffer)
`firmwareVersion`	string?	Firmware-Version für Staged-Rollout-TrackingFirmware version for staged rollout tracking

9. Scan-Quelle (scanSource)9. Scan source (scanSource)

Das Feld scanSource macht die Herkunft jeder Scan-Aktion explizit und unterscheidet POS, SCO, Exit-Gate, Handheld, Kunden-Smartphone und Service-Desk gleichwertig.

The scanSource field makes the origin of every scan action explicit, treating POS, SCO, exit gate, handheld, customer phone, and service desk as equal, first-class scan origins.

Value	BeschreibungDescription
`pos`	Kassenterminal (bedient durch Mitarbeiter)POS terminal (operated by associate)
`sco`	Self-Checkout-Terminal (Kunde)Self-checkout terminal (customer)
`exit_gate`	Automatisches Exit-Gate (EAS oder RFID)Automatic exit gate (EAS or RFID)
`associate_handheld`	Mobiles Handheld-Gerät eines MitarbeitersAssociate mobile handheld device
`customer_phone`	Kunden-Smartphone (NFC/HF-Tap oder BEEP!-App-Scan)Customer smartphone (NFC/HF tap or BEEP! app scan)
`service_desk`	Service-Desk oder KundendienstService desk or customer support

10. Offline-sichere Autorisierungs-Tokens10. Offline-safe authorization tokens

Retail-Hardware arbeitet oft in schlechten Netzwerkbedingungen. Kurzlebige signierte Tokens erlauben es Geräten, autorisierte Aktionen lokal auszuführen, ohne das Backend live zu erreichen.

Retail hardware often operates under degraded connectivity. Short-lived signed tokens let devices execute authorized actions locally without reaching the backend live.

Field	Type	BeschreibungDescription
`authorizationToken`	string	Backend-signiertes JWT – Gerät validiert Signatur lokal ohne NetzwerkzugriffBackend-signed JWT – device validates signature locally without network access
`expiresAt`	ISO 8601	Token-Ablaufzeit (empfohlen: 5–10 Minuten)Token expiry (recommended: 5–10 minutes)
`redeemedAt`	ISO 8601 \| null	Zeitpunkt der Einlösung (null = noch nicht eingelöst)Time of redemption (null = not yet redeemed)
`replayProtectedNonce`	string	Einmaliger Nonce – verhindert Replay-Angriffe auch bei gestohlenen TokensOne-time nonce – prevents replay attacks even with stolen tokens

Sicherheitshinweis: Geräte-Edge-Payloads enthalten nur authorized, action, expiresAt, itemCount und die Ereignis-ID. Kundenbezogene Daten werden an keinen Hardware-Edge übermittelt.Security note: Device edge payloads carry only authorized, action, expiresAt, itemCount, and the event ID. No customer-identifying data is sent to any hardware edge.

11. Idempotenz & Einlösestatus11. Idempotency & redemption state

Gates und Stationen führen Wiederholungsanfragen durch. Das Idempotenz-Modell verhindert Doppelaktionen und liefert konsistente Antworten.

Gates and stations retry requests. The idempotency model prevents double-actions and returns consistent responses.

MechanismusMechanism	BeschreibungDescription
`Idempotency-Key` (header)	UUID der Anfrage – gleiche Anfrage binnen 24 h gibt identisches Ergebnis zurückRequest UUID – same request within 24 h returns identical result
Request hash	Backend speichert Anfrage-Hash; doppelter Hash = idempotente Antwort ohne NeuausführungBackend stores request hash; duplicate hash = idempotent response without re-execution
`authorizationState`	`issued` → `redeemed` → `expired` / `revoked`

12. Richtlinien-Engine12. Policy engine

Anstelle von hardkodierten if securityTagMode == "station"-Prüfungen bewertet die Richtlinien-Engine deklarative Regeln. Händler können Self-Service für Bekleidungsetiketten erlauben, aber für Handtaschen oder Premiumartikel Personal-Unterstützung vorschreiben.

Instead of hard-coded if securityTagMode == "station" checks, the policy engine evaluates declarative rules. Merchants can allow self-service for apparel labels but require staff assistance for handbags or premium accessories.

Beispielregel (Pseudocode)Example rule (pseudocode)

Protection Policy Rule

// Plain-language rule evaluated by the policy engine: IF device.canDetachHardTag == true AND item.itemStatus == "paid" AND store.allowedActionsByCategory[item.category] includes "self_service" THEN grant action=detach_hard_tag, workflowType=self_service IF item.priceUnit >= store.requiresManualOverrideAboveValue OR store.requiresStaffForBrand includes item.brand THEN deny with reason="manual_assistance_required"

13. Kategorie- & Risikorichtlinien13. Category & risk policies

Händler nutzen häufig unterschiedliche Schutzhardware je Warengruppe und Diebstahlrisiko. Diese Konfigurationsfelder ermöglichen diese Differenzierung per Store-Dokument.

Merchants commonly use different protection hardware per product category and shrink risk. These configuration fields enable per-store differentiation.

stores/{storeId} – policy fields

{ // Which self-service actions are allowed per product category "allowedActionsByCategory": { "apparel": ["deactivate_label", "detach_hard_tag"], "handbags": [], "spirits": ["detach_hard_tag"] }, // Brands that always require staff regardless of category rule "requiresStaffForBrand": ["LuxuryBrandA", "PremiumBrandB"], // Item price threshold above which manual override is mandatory "requiresManualOverrideAboveValue": 19900, // cents // Which protection technologies are supported per store "supportedProtectionTechnologiesByStore": ["am", "rf"], // Per-device-type customer hint override "customerFacingHintByDeviceType": { "self_checkout_detacher": "Etikett an der Station am Ausgang entfernen.", "exit_gate": "Gate öffnet automatisch nach Bezahlung." } }

14. Adapter-Schicht (Herstellerprotokolle)14. Adapter layer (vendor protocols)

Die Plattform legt eine normalisierte API frei; herstellerspezifische Protokolle werden durch Adapter-Klassen übersetzt. Integration Engineers implementieren das ProtectionDeviceAdapter-Interface.

The platform exposes one normalised API; vendor-specific protocols are translated by adapter classes. Integration engineers implement the ProtectionDeviceAdapter interface.

TypeScript – ProtectionDeviceAdapter interface

interface ProtectionDeviceAdapter { /** Translate a normalized AuthorizationRequest to vendor command */ sendAuthorization(req: AuthorizationRequest): Promise<VendorAck>; /** Translate a vendor event to a normalized ProtectionEvent */ parseEvent(rawEvent: unknown): ProtectionEvent; /** Report device health / last-seen to capability registry */ reportHeartbeat(): Promise<void>; } // Built-in adapters: // QrStationAdapter – QR-code receipt scan stations // UhfRfidGateAdapter – UHF RFID exit gates // PosPeripheralAdapter – POS-integrated deactivators (e.g. Sensormatic) // HandheldReaderAdapter – associate handheld readers // FixtureControlAdapter – cabinet / cable-lock / showcase controllers // NfcSessionAdapter – customer phone NFC/HF sessions (Android NfcA/NfcV/IsoDep)

15. NFC/HF-Parallelpfad15. NFC/HF parallel path

NFC/HF-Flows (Smartphone-Tap) sind ein eigenständiger Pfad, der den UHF-RFID-Pfad nicht ersetzt. Android legt HF/NFC-Technologieklassen wie NfcV (ISO 15693) und IsoDep (ISO 14443-4) explizit offen – dies unterscheidet sich architektonisch von UHF-Gate-Bulk-Reads.

NFC/HF flows (phone tap) are a separate path that does not replace UHF RFID. Android explicitly exposes HF technology classes such as NfcV (ISO 15693) and IsoDep (ISO 14443-4) – architecturally different from UHF gate bulk reads.

POST /api/v1/verifyProtectedItem – NFC/HF phone tap

{ "tagUid": "E0040150A1B2C3D4", // ISO 15693 UID from Android NfcV "tagTechnology": "NfcV", "deviceId": "dev_phone_customer", "protectionAction": "verify_item_status", "scanSource": "customer_phone", "storeId": "store_123" }

Android NFC-Technologieklassen werden direkt als tagTechnology-Werte akzeptiert: NfcA, NfcB, NfcV, IsoDep, MifareClassic, MifareUltralight. Diese sind verschieden vom UHF-RFID-Stack und werden im NfcSessionAdapter verarbeitet.Android NFC technology classes are accepted directly as tagTechnology values: NfcA, NfcB, NfcV, IsoDep, MifareClassic, MifareUltralight. These are distinct from the UHF RFID stack and are handled by the NfcSessionAdapter.

16. Typisierte Fehler- & Ausnahmecodes16. Typed error & exception codes

Generische falsy-Antworten werden durch maschinenlesbare, klar beschriebene Fehlercodes ersetzt. Das spart Zeit bei Store-Pilots und Vendor-Debugging.

Generic falsy responses are replaced by machine-readable, clearly described error codes. This saves time during store pilots and vendor debugging.

Code	HTTP	BedeutungMeaning
`purchase_not_paid`	200	Kauf existiert, aber Zahlung wurde nicht abgeschlossenPurchase exists but payment not completed
`item_not_in_transaction`	200	Artikel-ID nicht im angegebenen Kauf enthaltenItem identifier not found in the given purchase
`unsupported_device_capability`	422	Gerät unterstützt die angeforderte Aktion nicht (laut Capability-Registry)Device does not support requested action (per capability registry)
`device_not_registered`	422	`deviceId` nicht in der Registry gefunden`deviceId` not found in registry
`token_expired`	401	Offline-Token abgelaufen; neues Token anfordernOffline token expired; request a new one
`status_conflict`	409	Artikelstatus verhindert die Aktion (z. B. `exception_hold`)Item status prevents the action (e.g. `exception_hold`)
`offline_policy_denied`	403	Filialrichtlinie erlaubt keine Offline-Aktion für diese KategorieStore policy does not permit offline action for this category
`manual_assistance_required`	200	Richtlinie verlangt Mitarbeiterbeteiligung (Wertgrenze oder Marke)Policy requires associate involvement (value threshold or brand)

200 – authorization denied with typed reason

{ "success": true, "authorized": false, "reason": "manual_assistance_required", "customerHint": "Please proceed to the service desk for this item.", "eventId": "evt_prot_denied_01k..." }

17. Abwärtskompatibilität17. Backward compatibility

Bestehende Integrationen können ohne Änderung weiter betrieben werden. Kleine Händler bleiben auf dem einfachen Setup; größere Händler mit gemischten EAS/RFID-Flotten übernehmen den erweiterten Pfad inkrementell.

Existing integrations continue to work without modification. Small merchants stay on the simple setup; larger merchants with mixed EAS/RFID fleets can adopt the richer hardware-inclusive path incrementally.

Altes Feld / EndpointOld field / endpoint	StatusStatus	EmpfehlungRecommendation
`securityTagMode`	✓ gültig / valid	Weiternutzen für einfache Setups; optional durch drei Schichten ergänzenKeep for simple setups; optionally supplement with three-layer fields
`securityTagHint`	✓ gültig / valid	Automatisch in `customerFacingHintByDeviceType` gespiegeltAuto-mirrored to `customerFacingHintByDeviceType`
`securityTagStatus`	✓ gültig / valid	Fortbestehend; zusätzlich `itemStatus` für OmnichannelRetained; additionally `itemStatus` for omnichannel
`verifySecurityTagDeactivation`	✓ gültig / valid	Legacy-Pfad; neuer Pfad: `verifyProtectedItem`Legacy path; new path: `verifyProtectedItem`
`securityTag.deactivated` webhook	✓ gültig / valid	Zusätzlich neues `protection.`-Event-Schema verfügbarNew `protection.` event schema additionally available

18. Checkout-Verifizierung (QR/PIN) – unverändert18. Checkout Verification (QR/PIN) – unchanged

Die Checkout-Verifizierung (Diebstahlprävention vor der Zahlung) ist unverändert. Sie ergänzt die Produktsicherung nach der Zahlung.

Checkout verification (theft prevention before payment) is unchanged. It complements protection-platform actions after payment.

Field	TypType	Default	BeschreibungDescription
`requiresCheckoutVerification`	boolean	`false`	Aktiviert die Verifizierung vor dem CheckoutEnables pre-checkout verification
`checkoutVerificationThreshold`	number?	`null`	Mindest-Warenkorbwert (EUR Cents) ab dem die Verifizierung greiftMinimum cart value (EUR cents) to trigger verification; null = always
`checkoutPin`	string?	`null`	4-stelliger PIN (nur Personal kennt ihn)4-digit PIN (known only to staff)
`checkoutQRCode`	string?	`null`	Hash für QR-Code-VerifizierungHash string for QR code verification

Scan & Go API → Checkout-EndpointsCheckout endpoints
Webhooks → Event-Referenz inkl. protection.* und securityTag.*Event reference incl. protection.* and securityTag.*
Datenformate →Data Formats → Store- und Transaction-JSONStore and transaction JSON
Fehlerbehandlung →Error Handling → Vollständige FehlercodesFull error code reference
OpenAPI Spec → Maschinenlesbare API-DefinitionMachine-readable API definition