Lock offers - request & delivery - 20260702

deliverables/2 lock offer/lock-offer-delivery.md

@@ -0,0 +1,34 @@
+# Lock Offer Delivery
+
+_Required items_
+| object | description |
+| --- | --- |
+| LOCK OFFER DELIVERY | The container for the response |
+
+![alt text](image-1.png)
+
+## LOCK OFFER DELIVERY DETAILS
+
+| field | type | optional/conditions | description |
+| --- | --- | --- | --- |
+| requestId | string | condition: a-sync | the ID supplied in the request, to match request-response (in case of a-sync call) |
+| packageId | string | required | The reference to the locked offer package |
+| version | string | required | the (inital) version of the locked offer package |
+| expiryTime | date-time | required | expiry time of the lock, ISO 8601 |
+| warnings | list of warnings | optional | a list of warnings, in the requested contentLanguage. If this language is not supported, respond in the local accepted language |
+
+Remark: the version number can be a hash (of the offer structure), to validate that the offer hasn't been changed.  
+**You CANNOT rely on the fact that the version number increases, in steps of 1.**
+
+## Examples
+
+Remark: the usage of the JSON below is only indicative, to clarify our intensions. It is not how the final result will look like.
+
+### Simple
+```json
+{
+    "packageId": "offer-1",
+    "version": "305e50bfa0767185c3f0987277b60f53",
+    "expiryTime": "2026-07-01T10:03:00+01"
+}
+```

deliverables/2 lock offer/lock-offer-request.md

@@ -0,0 +1,58 @@
+# Lock Offer Request
+
+_Precondition_: There are offers   
+_Postcondition_: A single offer is selected, and 'claimed'/'reserved'/'blocked'. In general, it means that the resources required to execute the offer are claimed, and cannot be given to/reserve by another entity. 
+
+_Required items_
+| object | description |
+| --- | --- |
+| LOCK OFFER REQUEST | The main container for the request |
+| LOCK OFFER DELIVERY | The container for the response |
+
+![alt text](image.png)
+
+## LOCK OFFER REQUEST DETAILS
+
+| field | type | optional/conditions | description |
+| --- | --- | --- | --- |
+| lockOfferRequestId | string | condition: a-sync | a unique ID, the response to this request MUST have the same ID (in case of a-sync call) |
+| offeredPackageRef | string | required | the reference of the offer to lock |
+| allocations | list of allocationRef | condition: required allocations |  a list of allocatable seats/assets, subset of the 'required allocations' in the offer |
+| ancillaries | list of ancillaryRef | condition: required ancillaries | a list of ancillaries, subset of the 'required ancillaries' in the offer | 
+| aftersalesByRetailerOnly | boolean | optional | filter field; is it allowed that the customer can change the offer after purchase directly communicating with the distributor. Default 'false' |
+| contentLanguage | string | optional | The language/localization of user-facing content, One IETF BCP 47 (RFC 5646) language tag. If missing, the local accepted language |
+
+Implicit: the offers don't have a 'version' field yet, everything has no version. When locking the offer, the initial version will be assigned.
+
+## Examples
+
+Remark: the usage of the JSON below is only indicative, to clarify our intensions. It is not how the final result will look like.
+
+### Simple
+```json
+{
+    "offerPackageRef": "offer-1",
+}
+```
+
+### A-sync 
+```json
+{
+    "lockOfferRequestId": "LORI-3249",  # This ID must be repeated in the a-sync delivery
+    "offerPackageRef": "offer-2",
+}
+```
+
+### With a selection of allocations
+```json
+{
+    "offerPackageRef": "offer-2",
+    "allocations": { "NORMAL SEAT": 1, "BERTH": 1 }
+}
+```
+Later on, in the 'amend' phase (after the locking), the NORMAL SEAT and BERTH can be replaced by a reference to a specific seat and berth (SINGLE SPOT).
+
+_Exits from locked status_: 
+* the offer, or offer elements can be released: the customer announces that it does not want to use this offer (element). The claim(s) can be removed.
+* the offer is purchased and can be executed 
+* the expiry time of the offer has passed, the claims on the resources are removed.

deliverables/2 lock offer/lockOfferDelivery.yaml

@@ -0,0 +1,20 @@
+type: object
+properties:
+  requestId:
+    type: string
+    description: the ID supplied in the request, to match request-response (in case of a-sync call)
+  packageRef:
+    type: string
+    description: The reference to the locked offer package
+  version:
+    type: string
+    description: the (inital) version of the locked offer package
+  expiryTime:
+    type: string
+    format: date-time
+    description: expiry time of the lock, ISO 8601
+  warnings:
+    type: array
+    items:
+      type: string
+    description: a list of warnings, in the requested language

deliverables/2 lock offer/lockOfferRequest.yaml

@@ -0,0 +1,24 @@
+type: object
+properties:
+  requestId:
+    type: string
+    description: a unique ID, the response to this request MUST have the same ID (in case of a-sync call) 
+  packageRef:
+    type: string
+    format: package-ref
+    description: the reference of the offer to lock
+  aftersalesByRetailerOnly:
+    type: boolean
+    description: filter field; is it allowed that the customer can change the offer after purchase directly communicating with the distributor. Default 'false'
+  allocations:
+    type: array
+    items:
+      type: string
+      format: allocation-ref
+    description: a list of allocatable seats/assets, subset of the 'required allocations' in the offer
+  ancillaries:
+    type: array
+    items:
+      type: string
+      format: ancillary-ref
+    description: a list of ancillaries, subset of the 'required ancillaries' in the offer