Merge pull request 'Add activateBefore and description fields, update documentation; update POST/PATCH PurchasedTapConnectTicket CRUD spec' (#57) from feature/OVPAY-2493-tweaks into develop

Reviewed-on: #57
Reviewed-by: Bas Boterman <b.boterman@htm.nl>

src/openapi/customers/SE-customers-v2.yaml

@@ -3393,6 +3393,7 @@ paths:
                             "purchasedProductId": "0f0981bf-6d60-4b06-bc55-de1ba325f366",
                             "productId": 14,
                             "name": "HTM 2 uurskaart",
+                            "description": "Met deze kaart reis je 2 uur lang onbeperkt met de bussen en trams van HTM. Overstappen is natuurlijk toegestaan!",
                             "status": "PendingActivation",
                             "productCategory":
                               {
@@ -3403,13 +3404,14 @@ paths:
                             "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E",                            
                             "ticketReference": "KJj43nejhbTxhrfef287",
                             "serviceId": "HTM-4321-7654-7659",
-                            "issuedAt": "2026-03-21T09:01:35",
+                            "issuedAt": "2026-03-21T09:01:35+01:00",
                             "activatedAt": null,
                             "blocked": false,
-                            "cancelledAt": null,                            
+                            "cancelledAt": null,   
-                            "validityStart": "2026-03-21T09:01:35",
+                            "activateBefore": "2026-03-30",                        
-                            "validityEnd": "2026-04-21T23:59:59",
+                            "validityStart": null,
-                            "barcode": "barcodeBytes",
+                            "validityEnd": null,
+                            "barcode": null,
                             "externalDeviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d",
                             "_links": {
                               "get_order": {
@@ -3426,6 +3428,7 @@ paths:
                             "purchasedProductId": "0f0981bf-6d60-4b06-bc55-de1ba325f366",
                             "productId": 14,
                             "name": "HTM 2 uurskaart",
+                            "description": "Met deze kaart reis je 2 uur lang onbeperkt met de bussen en trams van HTM. Overstappen is natuurlijk toegestaan!",
                             "status": "Active",
                             "productCategory":
                               {
@@ -3436,13 +3439,14 @@ paths:
                             "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E",                            
                             "ticketReference": "KJj43nejhbTxhr897287",
                             "serviceId": "HTM-1234-7654-8945",
-                            "issuedAt": "2026-03-21T10:01:12",
+                            "issuedAt": "2026-03-21T10:01:12+01:00",
-                            "activatedAt": "2026-03-21T12:45:01",
+                            "activatedAt": "2026-03-21T12:45:01+01:00",
                             "blocked": false,
-                            "cancelledAt": null,                            
+                            "cancelledAt": null,    
-                            "validityStart": "2026-03-21T12:45:01",
+                            "activateBefore": null,                        
-                            "validityEnd": "2026-03-21T14:45:01",
+                            "validityStart": "2026-03-21T12:45:01+01:00",
-                            "barcode": "barcodeBytes",
+                            "validityEnd": "2026-03-21T14:45:01+01:00",
+                            "barcode": "iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcAQAAAACsbTuBAAAFDElEQVR4Xu2bQa6rOhBEGzHwMEtgKewMyM5YCkvIkAGif50yyc/Tl770piZW9HSNywzqVlW3nXcjc83cusxnvsbMjBieuelf/bzGYz1jWCKmeGS+4g5grSwlz/IaI+JgEfzcvzQZo2yhxQgW7wDutLJrvVLzEInbVHLpM/tK5T7kHmNdbxssgqSipQj/0KLA24yqNvEWWRclpJKpefNgE7YZr/lj1eZ55wMYIWkUbZb7Xj/wH+BezvPkFJhQetmD+7AI2VuSEQMevANYESzqZh49VlEXIKOT7SDtseqnpz0Iyc2DJZezkEB5aaVKSvuF5FMwaIdB7wCGOgb5fFgus2wlKhPDpUiTlogr1tsHG7lfzcqYLlVnDHq6ylYn1OE54qd5cNC6aQxL0UQRy2YJJxCS8N4m273Gm4BJFAhzlytb5T4A0QrCYmUTrxd1bYNVgGqqPndH7vHwYqHLHf9cpO1pHJxU3Nq6vUbAVhXaocnTKO5cpK+4AViLitRwf8IQdYFwBkkKW7FzZxNh/AN/g5NHqXyed5MOz45kjkvKofpLYNwBrNBR/Dz9SKpTDkGd8CApZYonT24B7un56XKnoMeXkOBNHqTDk/NOmrrwyfIWYHe51O4kn4FBnfYbnHjqKuw3AGMreKOvC07DCAebHS5lAXWq5eKVA0HjYA2xM0MYCSMnqTqpx48ZVSmPTd15tT03AF+LVBuOgJoMqc2HL6Gy8nr1/K2DU+YpmKerd45fQ2ypzSFyq8coUM2D1yBksNWqOTWnjqvLpVYPvrt17f6BP+AaQk85zR4MarfHbAlSu/XhgGCJNg6mQNmASXnGhpZY+tKp93lywaY+SjcPhroCWx1BHFAnVemR81mdjEikWlllzYNrCM27bKVt7nInLplEnef6SfPFhb19MDmCbewcjtL/d7FwAzCqmShYzMd/qaPnp0AxV+SOpq5xMCnLZJOhZCNCZuIR4BWwL6un4luF5sE9N7CKXIJ2Zecncnt3vZ0it+hN7wNC6+DU/Ene1gj+lOOr4BDGilyT3D74NZ4OlYm2Xmx9t2rJN+kb7P3A/wUzV6lSQaonIoR3DUdy7vR1WQt782CrzrbbvTOdxwu2ZKy4MZXXflPzYJoVLg6GpbIVtLSb2JxduzEg+6Mm+R3AXECaHYRjG4nH2UIak7jSm9zXNQ9OLha2yhbUCT/vOA1VHUAGXpVuhpsHE7H7O0d6d2+i7rxeI2EVVMTm4wZg5vZUV2/nBUmoG5befZ0XERKkNg9O8zR9Rexls+WgldPRmTYHp90BrAIkqqYYnkmNGfvEY1E2Ijeu/3SQLKar1Q/8AX88eDqCRe3wZKJ89sVCRdaTZfvg/u8uFhoH14J0apHvil2rFwrUNtuDcXLOruNdvRoGB9ezgJXP2OrwN+mz8jl9lPab3Ob0NwDbVteFpEuX+7ylbHGdo5Oeny8y4vJgy2DniHhzQQp3c4yCkLwZvPbXk+INwKeqj6grVB/ha+dC88LVfec3zR/q2gYnlyO5GD+Kvfp03unruKCUygJb1e8HmwdbPp2pg8fgr3XYnE6YQGUWUp20Dz6hSgReznmXY3hLJ5A2ozJT9wN/gfVIEbzBsxvdYSneL571OV279S+/jubBiuCzAL5qt5xHPNHMcHgciSuD15rXbYMtJFbE1piEkEi0fPp6AoLX5Lvjt+paBvOIRQjSEEHaCX5BSP4DBSalHh4bB/8DVeIFt2RfPhQAAAAASUVORK5CYII=",
                             "externalDeviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d",
                             "_links": {
                               "get_order": {
@@ -3602,6 +3606,7 @@ paths:
                             "purchasedProductId": "0f0981bf-6d60-4b06-bc55-de1ba325f366",
                             "productId": 14,
                             "name": "HTM 2 uurskaart",
+                            "description": "Met deze kaart reis je 2 uur lang onbeperkt met de bussen en trams van HTM. Overstappen is natuurlijk toegestaan!",
                             "status": "Active",
                             "productCategory": {
                               "productCategoryId": 5,
@@ -3611,13 +3616,14 @@ paths:
                             "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E",
                             "ticketReference": "KJj43nejhbTxhr897287",
                             "serviceId": "HTM-1234-7654-8945",
-                            "issuedAt": "2026-03-21T10:01:12",
+                            "issuedAt": "2026-03-21T10:01:12+01:00",
-                            "activatedAt": "2026-03-21T12:45:01",
+                            "activatedAt": "2026-03-21T12:45:01+01:00",
                             "blocked": false,
                             "cancelledAt": null,
-                            "validityStart": "2026-03-21T12:45:01",
+                            "activateBefore": null,
-                            "validityEnd": "2026-03-21T14:45:01",
+                            "validityStart": "2026-03-21T12:45:01+01:00",
-                            "barcode": "barcodeBytes",
+                            "validityEnd": "2026-03-21T14:45:01+01:00",
+                            "barcode": "iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcAQAAAACsbTuBAAAFDElEQVR4Xu2bQa6rOhBEGzHwMEtgKewMyM5YCkvIkAGif50yyc/Tl770piZW9HSNywzqVlW3nXcjc83cusxnvsbMjBieuelf/bzGYz1jWCKmeGS+4g5grSwlz/IaI+JgEfzcvzQZo2yhxQgW7wDutLJrvVLzEInbVHLpM/tK5T7kHmNdbxssgqSipQj/0KLA24yqNvEWWRclpJKpefNgE7YZr/lj1eZ55wMYIWkUbZb7Xj/wH+BezvPkFJhQetmD+7AI2VuSEQMevANYESzqZh49VlEXIKOT7SDtseqnpz0Iyc2DJZezkEB5aaVKSvuF5FMwaIdB7wCGOgb5fFgus2wlKhPDpUiTlogr1tsHG7lfzcqYLlVnDHq6ylYn1OE54qd5cNC6aQxL0UQRy2YJJxCS8N4m273Gm4BJFAhzlytb5T4A0QrCYmUTrxd1bYNVgGqqPndH7vHwYqHLHf9cpO1pHJxU3Nq6vUbAVhXaocnTKO5cpK+4AViLitRwf8IQdYFwBkkKW7FzZxNh/AN/g5NHqXyed5MOz45kjkvKofpLYNwBrNBR/Dz9SKpTDkGd8CApZYonT24B7un56XKnoMeXkOBNHqTDk/NOmrrwyfIWYHe51O4kn4FBnfYbnHjqKuw3AGMreKOvC07DCAebHS5lAXWq5eKVA0HjYA2xM0MYCSMnqTqpx48ZVSmPTd15tT03AF+LVBuOgJoMqc2HL6Gy8nr1/K2DU+YpmKerd45fQ2ypzSFyq8coUM2D1yBksNWqOTWnjqvLpVYPvrt17f6BP+AaQk85zR4MarfHbAlSu/XhgGCJNg6mQNmASXnGhpZY+tKp93lywaY+SjcPhroCWx1BHFAnVemR81mdjEikWlllzYNrCM27bKVt7nInLplEnef6SfPFhb19MDmCbewcjtL/d7FwAzCqmShYzMd/qaPnp0AxV+SOpq5xMCnLZJOhZCNCZuIR4BWwL6un4luF5sE9N7CKXIJ2Zecncnt3vZ0it+hN7wNC6+DU/Ene1gj+lOOr4BDGilyT3D74NZ4OlYm2Xmx9t2rJN+kb7P3A/wUzV6lSQaonIoR3DUdy7vR1WQt782CrzrbbvTOdxwu2ZKy4MZXXflPzYJoVLg6GpbIVtLSb2JxduzEg+6Mm+R3AXECaHYRjG4nH2UIak7jSm9zXNQ9OLha2yhbUCT/vOA1VHUAGXpVuhpsHE7H7O0d6d2+i7rxeI2EVVMTm4wZg5vZUV2/nBUmoG5befZ0XERKkNg9O8zR9Rexls+WgldPRmTYHp90BrAIkqqYYnkmNGfvEY1E2Ijeu/3SQLKar1Q/8AX88eDqCRe3wZKJ89sVCRdaTZfvg/u8uFhoH14J0apHvil2rFwrUNtuDcXLOruNdvRoGB9ezgJXP2OrwN+mz8jl9lPab3Ob0NwDbVteFpEuX+7ylbHGdo5Oeny8y4vJgy2DniHhzQQp3c4yCkLwZvPbXk+INwKeqj6grVB/ha+dC88LVfec3zR/q2gYnlyO5GD+Kvfp03unruKCUygJb1e8HmwdbPp2pg8fgr3XYnE6YQGUWUp20Dz6hSgReznmXY3hLJ5A2ozJT9wN/gfVIEbzBsxvdYSneL571OV279S+/jubBiuCzAL5qt5xHPNHMcHgciSuD15rXbYMtJFbE1piEkEi0fPp6AoLX5Lvjt+paBvOIRQjSEEHaCX5BSP4DBSalHh4bB/8DVeIFt2RfPhQAAAAASUVORK5CYII=",
                             "externalDeviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d",
                             "_links": {
                               "get_order": {
@@ -4393,6 +4399,7 @@ components:
                   - purchasedProductId
                   - productId
                   - name
+                  - description
                   - status
                   - productCategory
                   - orderId
@@ -4401,8 +4408,6 @@ components:
                   - serviceId
                   - issuedAt
                   - blocked
-                  - validityStart
-                  - validityEnd
                   - _links
                 properties:
                   purchasedProductId:
@@ -4415,10 +4420,26 @@ components:
                   name:
                     type: string
                     example: HTM 2 uurskaart
+                    description: |-
+                      The name of the originating HTM product definition. 
+                      Will be returned in the language as specified in the Accept-Language header or the customer profile. Otherwise defaults to NL.
+                  description:
+                    type: string
+                    example: "Met deze kaart reis je 2 uur lang onbeperkt met de bussen en trams van HTM. Overstappen is natuurlijk toegestaan!"
+                    description: |-
+                      The description of the originating HTM product definition. 
+                      Will be returned in the language as specified in the Accept-Language header or the customer profile. Otherwise defaults to NL.
                   status:
                     type: string
                     enum: ["PendingActivation", "Active", "Ended", "Blocked", "Refunded"]
                     example: Active
+                    description: |-
+                      The status of the barcode ticket.
+                      - PendingActivation: The ticket is in the validity range (activateBefore is in the future) and can be activated using the PATCH endpoint
+                      - Active: The ticket has been activated and can be used for travel within the validity range as denoted by the validityStart and validityEnd fields
+                      - Ended: The ticket is no longer active (validityEnd and/or activateBefore are in the past) and cannot be used for travel
+                      - Blocked: The ticket is blocked and cannot be used for travel
+                      - Refunded: The ticket is refunded and cannot be used for travel
                   productCategory:
                     type: object
                     description: The category of the originating HTM product definition
@@ -4459,31 +4480,30 @@ components:
                     type: string
                     format: date-time-offset
                     example: "2024-11-25T13:25:00+01:00"
+                  activateBefore:
+                    type: string
+                    format: date
+                    example: "2024-11-30"
+                    description: Only present for barcode tickets that are not yet activated. Tickets can only be activated BEFORE this date.
                   validityStart:
                     description: |- 
-                      The date-time at which the ticket will become valid for traveling. The ticket will not be valid before this date. 
+                      Only present for barcode tickets that have been activated. The date-time at which the ticket will become valid for traveling. 
-                      For tickets that require activation: Before activation this field will show the lower bound of the range in which 
+                      The ticket will not be valid before this date/time.
-                      a ticket can be activated, after activation the value of this field is updated to the final start of the validity 
-                      range. For example: a 1 hour product that has to be activated within 7 days. Before ticket activation (activatedAt 
-                      field returns null) this value (together with validityEnd) will return the 7 day range, after activation (activatedAt 
-                      field returns a date-time) the value will show the start of the final 1 hour validity range.
                     type: string
                     format: date-time-offset
                     example: "2024-11-25T13:25:00+01:00"
                   validityEnd:
                     description: |- 
-                      The date-time at which the ticket will become valid for traveling. The ticket will not be valid before this date. 
+                      Only present for barcode tickets that have been activated. The date-time at which the ticket will become invalid for traveling. 
-                      For tickets that require activation: Before activation this field will show the upper bound of the range in which 
+                      The ticket will not be valid after this date/time.
-                      a ticket can be activated, after activation the value of this field is updated to the final end of the validity 
-                      range. For example: a 1 hour product that has to be activated within 7 days. Before ticket activation (activatedAt 
-                      field returns null) this value (together with validityStart) will return the 7 day range, after activation (activatedAt 
-                      field returns a date-time) the value will show the end of the final 1 hour validity range.
                     type: string
                     format: date-time-offset
                     example: "2024-11-25T15:25:00+01:00"
                   barcode:
                     type: string
-                    example: barcodeBytes
+                    format: base64
+                    description: Base64 encoded barcode image of type `image/png`. Might not be present for barcode tickets that are not yet activated.
+                    example: iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcAQAAAACsbTuBAAAFDElEQVR4Xu2bQa6rOhBEGzHwMEtgKewMyM5YCkvIkAGif50yyc/Tl770piZW9HSNywzqVlW3nXcjc83cusxnvsbMjBieuelf/bzGYz1jWCKmeGS+4g5grSwlz/IaI+JgEfzcvzQZo2yhxQgW7wDutLJrvVLzEInbVHLpM/tK5T7kHmNdbxssgqSipQj/0KLA24yqNvEWWRclpJKpefNgE7YZr/lj1eZ55wMYIWkUbZb7Xj/wH+BezvPkFJhQetmD+7AI2VuSEQMevANYESzqZh49VlEXIKOT7SDtseqnpz0Iyc2DJZezkEB5aaVKSvuF5FMwaIdB7wCGOgb5fFgus2wlKhPDpUiTlogr1tsHG7lfzcqYLlVnDHq6ylYn1OE54qd5cNC6aQxL0UQRy2YJJxCS8N4m273Gm4BJFAhzlytb5T4A0QrCYmUTrxd1bYNVgGqqPndH7vHwYqHLHf9cpO1pHJxU3Nq6vUbAVhXaocnTKO5cpK+4AViLitRwf8IQdYFwBkkKW7FzZxNh/AN/g5NHqXyed5MOz45kjkvKofpLYNwBrNBR/Dz9SKpTDkGd8CApZYonT24B7un56XKnoMeXkOBNHqTDk/NOmrrwyfIWYHe51O4kn4FBnfYbnHjqKuw3AGMreKOvC07DCAebHS5lAXWq5eKVA0HjYA2xM0MYCSMnqTqpx48ZVSmPTd15tT03AF+LVBuOgJoMqc2HL6Gy8nr1/K2DU+YpmKerd45fQ2ypzSFyq8coUM2D1yBksNWqOTWnjqvLpVYPvrt17f6BP+AaQk85zR4MarfHbAlSu/XhgGCJNg6mQNmASXnGhpZY+tKp93lywaY+SjcPhroCWx1BHFAnVemR81mdjEikWlllzYNrCM27bKVt7nInLplEnef6SfPFhb19MDmCbewcjtL/d7FwAzCqmShYzMd/qaPnp0AxV+SOpq5xMCnLZJOhZCNCZuIR4BWwL6un4luF5sE9N7CKXIJ2Zecncnt3vZ0it+hN7wNC6+DU/Ene1gj+lOOr4BDGilyT3D74NZ4OlYm2Xmx9t2rJN+kb7P3A/wUzV6lSQaonIoR3DUdy7vR1WQt782CrzrbbvTOdxwu2ZKy4MZXXflPzYJoVLg6GpbIVtLSb2JxduzEg+6Mm+R3AXECaHYRjG4nH2UIak7jSm9zXNQ9OLha2yhbUCT/vOA1VHUAGXpVuhpsHE7H7O0d6d2+i7rxeI2EVVMTm4wZg5vZUV2/nBUmoG5befZ0XERKkNg9O8zR9Rexls+WgldPRmTYHp90BrAIkqqYYnkmNGfvEY1E2Ijeu/3SQLKar1Q/8AX88eDqCRe3wZKJ89sVCRdaTZfvg/u8uFhoH14J0apHvil2rFwrUNtuDcXLOruNdvRoGB9ezgJXP2OrwN+mz8jl9lPab3Ob0NwDbVteFpEuX+7ylbHGdo5Oeny8y4vJgy2DniHhzQQp3c4yCkLwZvPbXk+INwKeqj6grVB/ha+dC88LVfec3zR/q2gYnlyO5GD+Kvfp03unruKCUygJb1e8HmwdbPp2pg8fgr3XYnE6YQGUWUp20Dz6hSgReznmXY3hLJ5A2ozJT9wN/gfVIEbzBsxvdYSneL571OV279S+/jubBiuCzAL5qt5xHPNHMcHgciSuD15rXbYMtJFbE1piEkEi0fPp6AoLX5Lvjt+paBvOIRQjSEEHaCX5BSP4DBSalHh4bB/8DVeIFt2RfPhQAAAAASUVORK5CYII=
                   externalDeviceId:
                     type: string
                     example: e2be51ae-2701-4803-a2d7-97d4b714482d

src/openapi/products/purchased_products-crud.yaml

@@ -965,6 +965,8 @@ paths:
                 "activatedAt": "2024-10-05T12:34:56.000",
                 "cancelledAt": "2024-10-06T12:34:56.000",
                 "lastUpdatedOn": "2024-10-05T12:34:56.000",
+                "validityStart": "2024-10-05T12:34:56.000",
+                "validityEnd": "2024-10-06T12:34:56.000"
               }
       responses:
         "200":
@@ -1194,6 +1196,7 @@ components:
         - lastUpdatedOn
         - createdBy
         - serviceId
+        - activateBefore
       properties:
         issuedAt:
           type: string
@@ -1230,6 +1233,21 @@ components:
         serviceId:
           type: string
           example: HTM-1234-7654-8945
+        activateBefore:
+          type: string
+          format: date
+          description: Tickets can only be activated BEFORE this date. Should be equal to TapConnect's `lifeSpanEnd + P1D`
+          example: 2024-10-08
+        validityStart:
+          type: string
+          format: date-time
+          description: The date-time at which the ticket will become valid for for traveling. The ticket will not be valid before this date/time.
+          example: 2024-10-05T12:34:56.000
+        validityEnd:
+          type: string  
+          format: date-time
+          description: The date-time at which the ticket will become invalid for traveling. The ticket will not be valid after this date/time.
+          example: 2024-10-06T12:34:56.000
     BulkResponseBody:
       type: object
       properties: