diff --git a/deliverables/4 purchase package/image-1.png b/deliverables/4 purchase package/image-1.png new file mode 100644 index 0000000..c3e2fd9 Binary files /dev/null and b/deliverables/4 purchase package/image-1.png differ diff --git a/deliverables/4 purchase package/image-2.png b/deliverables/4 purchase package/image-2.png new file mode 100644 index 0000000..d3fe7ea Binary files /dev/null and b/deliverables/4 purchase package/image-2.png differ diff --git a/deliverables/4 purchase package/image-3.png b/deliverables/4 purchase package/image-3.png new file mode 100644 index 0000000..b22606f Binary files /dev/null and b/deliverables/4 purchase package/image-3.png differ diff --git a/deliverables/4 purchase package/image.png b/deliverables/4 purchase package/image.png new file mode 100644 index 0000000..540d891 Binary files /dev/null and b/deliverables/4 purchase package/image.png differ diff --git a/deliverables/4 purchase package/personalInformationType.yaml b/deliverables/4 purchase package/personalInformationType.yaml new file mode 100644 index 0000000..0c572ad --- /dev/null +++ b/deliverables/4 purchase package/personalInformationType.yaml @@ -0,0 +1,23 @@ +type: string +x-extensible-enum: + - fullName + - firstName + - lastName + - dateOfBirth # always in the format YYYY-MM-DD, ISO 8601 + - gender # M for male, F for female, X for non-binary, U for unknown + - nationality # ISO 3166-1 alpha-2 country code + - email + - address # street, city, postal code, country + - phoneNumber + - mobileNumber + - passportNumber + - passportExpiryDate # always in the format YYYY-MM-DD, ISO 8601 + - passportIssuingCountry # ISO 3166-1 alpha-2 country code + - idCardNumber + - idCardAdditionalNumber + - idCardExpiryDate # always in the format YYYY-MM-DD, ISO 8601 + - idIssuingOrganisation + - drivingLicenseNumber + - drivingLicenseExpiryDate # always in the format YYYY-MM-DD, ISO 8601 + - drivingLicenseIssuingCountry # ISO 3166-1 alpha-2 country code +description: the type of personal information \ No newline at end of file diff --git a/deliverables/4 purchase package/purchase.md b/deliverables/4 purchase package/purchase.md new file mode 100644 index 0000000..cd357c3 --- /dev/null +++ b/deliverables/4 purchase package/purchase.md @@ -0,0 +1,179 @@ +# Purchase package Request - delivery + +The purchase can be preceded by a validation of the package, to check if it is valid without executing a (expensive) call to purchase the package. + +_Required items_ + +| object | description | +| --- | --- | +| PURCHASE PACKAGE REQUEST | The purchase request | +| PURCHASE PACKAGE DELIVERY | The accompaning response | + +## PURCHASE REQUEST DETAILS + +| field | type | optional/conditions | description | +| --- | --- | --- | --- | +| requestId | string | condition: a-sync | a unique ID, the response to this request MUST have the same ID (in case of a-sync call) | +| packageId | string | required | the reference of the package to purchase | +| version | string | required | the version of the locked offer package to purchase | +| personalInformation | List of personal data | conditional | when personal information is required to purchase | +| contentLanguage | string | optional | The language/localization of user-facing content, One IETF BCP 47 (RFC 5646) language tag. If missing, the local accepted language | + +![alt text](image-2.png) + +```json +{ "packageId": "offer-1", + "version": "305e50bfa0767185c3f0987277b60f53" +} +``` + +## PURCHASE DELIVERY DETAILS + +![alt text](image-3.png) + +### Purchase Delivery + +| field | type | optional/conditions | description | +| --- | --- | --- | --- | +| requestId | string | condition: a-sync | a unique ID, the response to this request MUST have the same ID (in case of a-sync call) | +| package | Package | required, but nullable | when the purchases succeeds, there must be a package object | +| expiryTime | date-time | required | expiry time of rollback window, ISO 8601 | +| problems | list of string | required | a list of string, describing blocking issues, in the requested language (or local if not the requested language is not supported) | +| warnings | list of string | required | a list of string, describing non-blocking issues, in the requested language (or local if not the requested language is not supported) | + +**Note**: take a look at the PR for the Search-offer Delivery. It contains the `PACKAGE` concept. + +#### Effective Purchased Package +```yaml +type: object +required: + - packageId + - summary + - name + - matching + - status +properties: + packageId: + type: string + description: Unique identifier for the package + version: + type: string + description: > + The version of the package, which can be used for version control and tracking changes over time. + Avoid using an increasing integer as the version number, as it may not accurately reflect the content changes. + Instead, consider using a hash of the package content or a combination of an internal ID and version number + to ensure uniqueness and integrity. + summary: + type: string + description: A brief summary of the package, providing an overview of its contents or purpose. + name: + type: string + description: The name of the package, which can be used for display purposes in user interfaces. + status: + type: string + description: The current status of the package. + # enum: + # - offered + # - locked + # - expired + # - released + # - purchased + # - rollback + # - cancelled + # - fulfilled + # - refunded + # - exchanged + # - in_progress + # - completed + const: purchased # from Purchased Package + elements: + type: array + description: A list of elements that are part of the package + items: + oneOf: + - $ref: .\TravelRight.yaml + - $ref: .\Ancillary.yaml + - $ref: .\Allocation.yaml + - $ref: .\AfterSalesFee.yaml + discriminator: + propertyName: packageElementType + mapping: + travelRight: .\TravelRight.yaml + ancillary: .\Ancillary.yaml + allocation: .\Allocation.yaml + afterSalesFee: .\AfterSalesFee.yaml + minimumPrice: + $ref: .\Cost.yaml + matching: + type: string + description: Indicates the matching status of the package. + enum: [match, partial-match] + summaryDetails: + type: array + description: A list of detailed summaries related to the package, providing additional context or information. + items: + $ref: .\SummaryDetail.yaml + trip: + $ref: .\Trip.yaml + guarantees: + type: array + description: A list of guarantees + items: + $ref: .\Guarantee.yaml + travelDocuments: + type: array + description: a list of travel documents + items: + $ref: .\TravelDocument.yaml + links: + type: array + description: A list of links related to the package, which can provide additional information or actions. + items: + $ref: .\Link.yaml +example: + { + "packageId": "PK-123", + "summary": "This is a sample package.", + "name": "Sample Package", + "status": "purchased", + "minimumPrice": { "amount": 100.00, "currency": "USD" }, + "summaryDetails": [ + { + "detailType": "geospatial", + "description": "A route from San Francisco to Los Angeles.", + "content": { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [[-122.4194, 37.7749], [-118.2437, 34.0522]] } } + }, + { + "detailType": "condition", + "content": "No pets allowed" + } + ], + "elements": [ + { + "elementType": "travelRight", + "packageElementId": "PE-123", + "numberOfAvailableItems": "5", + "covering": [ { "startLeg": "L-789", "endLeg": "L-789" } ], + "price": { "amount": 23.20, "currency": "EUR" }, + "travellingEntities": [ "TE-123", "TE-456" ] + }, + { + "elementType": "allocation", + "packageElementId": "PE-124", + "allocationType": "spot", + "typeOfSpot": "seat", + "numberOfAllocatedUnits": 1, + "reference": "102/36B", + "appliesTo": [ "PE-123" ] + } + ], + "links": [ + { + "rel": "lock", + "href": "https://api.example.com/packages/PK-123/lock", + "method": "POST", + "type": "application/json" + } + ] + } +``` \ No newline at end of file diff --git a/deliverables/4 purchase package/purchaseDelivery.yaml b/deliverables/4 purchase package/purchaseDelivery.yaml new file mode 100644 index 0000000..29580d2 --- /dev/null +++ b/deliverables/4 purchase package/purchaseDelivery.yaml @@ -0,0 +1,21 @@ +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) condition a-sync + package: + $ref: .\PurchasedPackage.yaml + expiryTime: + type: string + format: date-time + description: expiry time of rollback window, ISO 8601 + problems: + type: array + items: + type: string + description: a list of string, describing blocking issues, in the requested language (or local if not the requested language is not supported) + warnings: + type: array + items: + type: string + description: a list of string, describing non-blocking issues, in the requested language (or local if not the requested language is not supported) diff --git a/deliverables/4 purchase package/purchaseRequest.yaml b/deliverables/4 purchase package/purchaseRequest.yaml new file mode 100644 index 0000000..46e59de --- /dev/null +++ b/deliverables/4 purchase package/purchaseRequest.yaml @@ -0,0 +1,38 @@ +type: object +required: + - packageId + - version +properties: + requestId: + type: string + message: >- + conditional, when using a-sync calls, a unique ID, the response to this request MUST have the same ID (in case of a-sync call) + packageId: + type: string + message: the reference of the package to validate + version: + type: string + message: the version of the locked offer package to validate + contentLanguage: + type: string + message: the requested language for the response content + personalInformation: + type: array + items: + type: object + properties: + travellingEntityId: + type: string + informationType: + $ref: .\personalInformationType.yaml + distributionType: + type: string + description: >- + the distribution type of the personal information. + enum: + - value + - reference + - VC + - referencedVC + value: + type: string diff --git a/deliverables/4 purchase package/validate.md b/deliverables/4 purchase package/validate.md new file mode 100644 index 0000000..e0a0f06 --- /dev/null +++ b/deliverables/4 purchase package/validate.md @@ -0,0 +1,95 @@ +# Validate Request - response + +The purchase can be preceded by a validation of the package, to check if it is valid without executing a (expensive) call to purchase the package. + +_Required items_ + +| object | description | +| --- | --- | +| VALIDATE PACKAGE REQUEST | The request to validate the package before purchase, optional | +| VALIDATE PACKAGE DELIVERY | The accompaning response | + +## VALIDATE PACKAGE REQUEST DETAILS + +| field | type | optional/conditions | description | +| --- | --- | --- | --- | +| requestId | string | condition: a-sync | a unique ID, the response to this request MUST have the same ID (in case of a-sync call) | +| packageId | string | required | the reference of the package to validate | +| version | string | required | the version of the locked offer package to validate | +| personalInformation | List of personal data | conditional | when personal information is required to validate | +| contentLanguage | string | optional | The language/localization of user-facing content, One IETF BCP 47 (RFC 5646) language tag. If missing, the local accepted language | + +### Personal Information Type +```yaml +type: string +x-extensible-enum: + - fullName + - firstName + - lastName + - dateOfBirth # always in the format YYYY-MM-DD, ISO 8601 + - gender # M for male, F for female, X for non-binary, U for unknown + - nationality # ISO 3166-1 alpha-2 country code + - email + - address # street, city, postal code, country + - phoneNumber + - mobileNumber + - passportNumber + - passportExpiryDate # always in the format YYYY-MM-DD, ISO 8601 + - passportIssuingCountry # ISO 3166-1 alpha-2 country code + - idCardNumber + - idCardAdditionalNumber + - idCardExpiryDate # always in the format YYYY-MM-DD, ISO 8601 + - idIssuingOrganisation + - drivingLicenseNumber + - drivingLicenseExpiryDate # always in the format YYYY-MM-DD, ISO 8601 + - drivingLicenseIssuingCountry # ISO 3166-1 alpha-2 country code +description: the type of personal information +``` + +![alt text](image.png) + + +## 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. + +```json +{ "packageId": "offer-1", + "version": "305e50bfa0767185c3f0987277b60f53", + "contentLanguage": "uk-EN" +} +``` + +A more advanced one, containing personal information: + +```json +{ "packageId": "offer-1", + "version": "305e50bfa0767185c3f0987277b60f53", + "contentLanguage": "uk-EN", + "personalInformation": [ { "travellingEntityId": "TR-3492", + "fullName": "E. van Dam" + } ] +} +``` + +## VALIDATE PACKAGE DELIVERY DETAILS + +| field | type | optional/conditions | description | +| --- | --- | --- | --- | +| requestId | string | condition: a-sync | a unique ID, the response to this request MUST have the same ID (in case of a-sync call) | +| packageId | string | required | the reference of the validated package | +| version | string | required | the version of the validated locked offer package | +| expiryTime | date-time | required | expiry time of the locked offer, ISO 8601 | +| problems | list of string | required | a list of string, describing blocking issues, in the requested language (or local if not the requested language is not supported) | +| warnings | list of string | required | a list of string, describing non-blocking issues, in the requested language (or local if not the requested language is not supported) | + +![alt text](image-1.png) + +```json +{ "packageId": "offer-1", + "version": "305e50bfa0767185c3f0987277b60f53", + "expiryTime": "2027-07-01T10:55:00Z", + "problems": [], + "warnings": [] +} +``` \ No newline at end of file diff --git a/deliverables/4 purchase package/validateDelivery.yaml b/deliverables/4 purchase package/validateDelivery.yaml new file mode 100644 index 0000000..877e967 --- /dev/null +++ b/deliverables/4 purchase package/validateDelivery.yaml @@ -0,0 +1,29 @@ +type: object +required: + - packageId + - version + - expiryTime +properties: + requestId: + type: string + description: a unique ID, the response to this request MUST have the same ID (in case of a-sync call) + packageId: + type: string + description: the reference of the validated package + version: + type: string + description: the version of the validated locked offer package + expiryTime: + type: string + format: date-time + description: expiry time of the locked offer, ISO 8601 + problems: + type: array + items: + type: string + description: a list of string, describing blocking issues, in the requested language (or local if not the requested language is not supported) + warnings: + type: array + items: + type: string + description: a list of string, describing non-blocking issues, in the requested language (or local if not the requested language is not supported) \ No newline at end of file diff --git a/deliverables/4 purchase package/validateRequest.yaml b/deliverables/4 purchase package/validateRequest.yaml new file mode 100644 index 0000000..a6d81ca --- /dev/null +++ b/deliverables/4 purchase package/validateRequest.yaml @@ -0,0 +1,23 @@ +type: object +required: + - packageId + - version +properties: + requestId: + type: string + description: >- + conditional, when using a-sync calls, a unique ID, the response to this request MUST have the same ID (in case of a-sync call) + packageId: + type: string + description: the reference of the package to validate + version: + type: string + description: the version of the locked offer package to validate + placeHolders: + type: array + items: + type: ./placeHolder.yaml + description: conditional, when personal information is required to validate + contentLanguage: + type: string + description: optional, The language/localization of user-facing content, One IETF BCP 47 (RFC 5646) language tag. If missing, the local accepted language \ No newline at end of file