{ "openapi": "3.1.1", "info": { "title": "Products (Draft)", "description": "**This API specification is a draft and is not yet implemented. Endpoints, schemas, and\nbehavior are subject to change without notice.**\n\nThis API provides services to read and maintain products and fare data for public transport in Norway.\n", "contact": { "name": "Team Produkt", "email": "teamprodukt@entur.org" }, "version": "2026.06.0" }, "servers": [ { "url": "https://api.entur.io/products", "description": "Production environment" }, { "url": "https://api.staging.entur.io/products", "description": "Staging environment" }, { "url": "https://api.dev.entur.io/products", "description": "Development environment" } ], "security": [ { "jwt": [] } ], "tags": [ { "name": "Entitlement Required", "description": "Manage EntitlementRequired instances. Defines what existing entitlement (e.g., a\nvalid ticket) is required to purchase a product.\n" }, { "name": "Purchase Window", "description": "Manage PurchaseWindow instances. Defines when a product can be purchased relative\nto departure (e.g., up to 120 days before, until departure).\n" }, { "name": "Supplement product", "description": "A supplement product can be purchased in addition to a preassigned fare product. Examples of supplement product types include:\n - Seat reservation\n - Bicycle\n - Animal\n - Meal\n - Wi-fi\n - Luggage\n - Parking\n" }, { "name": "Sales package assignment", "description": "Assign the supplement products to sales packages without knowledge of the full sales package structure.\n" }, { "name": "Sales package", "description": "Fine-grained modification of sales packages. The client sends a full request body and\nhas full control over the sales package content.\n" }, { "name": "Usage Validity Period", "description": "Manage UsageValidityPeriod instances. Defines how long a product is valid after\npurchase or activation (e.g., single trip, 60 minutes, 30 days).\n" }, { "name": "Version", "description": "Version management endpoints" } ], "paths": { "/v3/versions": { "post": { "tags": [ "Version" ], "summary": "Create a new version", "description": "Create a new version in DRAFT status. The version will be assigned the current date as startDate if not provided.", "operationId": "createVersion", "parameters": [], "requestBody": { "description": "The request body must include the netex ID and status (must be DRAFT). The startDate is optional and will default to the current date if not provided. The endDate is also optional.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionRequest" }, "examples": { "draft": { "$ref": "#/components/examples/draft" } } } }, "required": true }, "responses": { "201": { "description": "Version created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" }, "examples": { "draftVersion": { "$ref": "#/components/examples/draftVersion" } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalidDate": { "summary": "Illegal date", "value": { "type": "https://example.com/probs/illegal-transition", "title": "Illegal date for new version", "detail": "Invalid version dates: endDate must be strictly after startDate.", "status": 400 } }, "invalidStatus": { "summary": "Illegal status", "value": { "type": "https://example.com/probs/illegal-transition", "title": "Illegal status for new version", "detail": "Invalid version status VERSIONED. New versions must be created with status DRAFT.", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "conflict": { "summary": "Version already exists", "value": { "type": "https://example.com/probs/conflict", "title": "Conflict", "detail": "Version ENT:Version:001 exists already.", "status": 409 } }, "inProgress": { "summary": "Version already in progress", "value": { "type": "https://example.com/probs/conflict", "title": "Conflict with other in progress", "detail": "Cannot create new version: ENT:Version:001 are already in PROPOSED (only one in-progress version allowed).", "status": 409 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/versions/{id}": { "get": { "tags": [ "Version" ], "summary": "Get a version by ID", "description": "Retrieve a specific version by its netex ID.", "operationId": "getVersionById", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "responses": { "200": { "description": "Version found successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" }, "examples": { "draftVersion": { "$ref": "#/components/examples/draftVersion" }, "versionedVersion": { "$ref": "#/components/examples/versionedVersion" } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalidTransition": { "summary": "Invalid ID format", "value": { "type": "https://example.com/probs/illegal-transition", "title": "Illegal status transition", "detail": "Invalid netex ID format", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Version not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Version not found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "detail": "Version ENT:Version:001 not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "put": { "tags": [ "Version" ], "summary": "Update an existing version", "description": "Update an existing version. Can be used to change status (e.g., from DRAFT to PROPOSED or PROPOSED to VERSIONED) or modify dates.", "operationId": "updateVersion", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "requestBody": { "description": "The request body must include the new status and startDate. The endDate is optional. Valid status transitions are:\n - DRAFT -> PROPOSED\n - PROPOSED -> VERSIONED\n - DRAFT -> DEPRECATED\n - PROPOSED -> DEPRECATED\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionRequest" }, "examples": { "draft": { "$ref": "#/components/examples/draft" } } } }, "required": true }, "responses": { "200": { "description": "Version updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" }, "examples": { "draftVersion": { "$ref": "#/components/examples/draftVersion" } } } } }, "400": { "description": "Bad request - Invalid data or illegal status transition", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalidTransition": { "summary": "Illegal status transition", "value": { "type": "https://example.com/probs/illegal-transition", "title": "Illegal status transition", "detail": "Invalid status transition: DRAFT -> $to", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Version not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Version not found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "detail": "Version ENT:Version:001 not found.", "status": 404 } } } } } }, "409": { "description": "Conflict - Version already exists or overlaps with existing version", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "conflict": { "summary": "Version already exists", "value": { "type": "https://example.com/probs/conflict", "title": "Conflict", "detail": "Version ENT:Version:001 exists already.", "status": 409 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/supplement-products": { "post": { "tags": [ "Supplement product" ], "summary": "Create a new supplement product", "description": "Create a new supplement product. A new version will be created with version number 1.\n", "operationId": "createSupplementProduct", "parameters": [], "requestBody": { "description": "Supplement product to be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplementProductRequest" }, "examples": { "dog": { "$ref": "#/components/examples/dog" }, "bicycle": { "$ref": "#/components/examples/bicycle" }, "luggage": { "$ref": "#/components/examples/luggage" }, "parking": { "$ref": "#/components/examples/parking" }, "upgrade": { "$ref": "#/components/examples/upgrade" }, "seatReservation": { "$ref": "#/components/examples/seatReservation" } } } }, "required": true }, "responses": { "201": { "description": "Supplement product created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplementProductResponse" }, "examples": { "parking": { "$ref": "#/components/examples/parking-2" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "409": { "description": "Conflict - Supplement product already exists", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "conflict": { "summary": "Supplement product already exists", "value": { "type": "https://developer.entur.org/errors/conflict", "title": "Conflict", "detail": "Supplement product with privateCode '123' already exists.", "status": 409 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/versions/history/{id}": { "get": { "tags": [ "Version" ], "summary": "Get version history for a versionable element by ID", "description": "Retrieve the list for all version that is related to the given versionable element.", "operationId": "getVersionHistoryById", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "responses": { "200": { "description": "Version history found successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VersionResponse" } }, "examples": { "versionHistory": { "$ref": "#/components/examples/versionHistory" } } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalidTransition": { "summary": "Invalid ID format", "value": { "type": "https://example.com/probs/illegal-transition", "title": "Illegal status transition", "detail": "Invalid NetEx ID format", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/supplement-products/{id}": { "get": { "tags": [ "Supplement product" ], "summary": "List versions of a supplement product", "description": "Retrieve all versions of a supplement product by its NeTEx ID.\nReturns a lightweight list containing only the product ID and version ID for each version.\n", "operationId": "getSupplementProductVersions", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "responses": { "200": { "description": "List of supplement product versions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplementProductVersionListItem" } }, "examples": { "multipleVersions": { "$ref": "#/components/examples/multipleVersions" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Supplement product not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Supplement product not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "SupplementProduct 'EXA:SupplementProduct:456' not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "post": { "tags": [ "Supplement product" ], "summary": "Create a new version of a supplement product", "description": "Create a new version of existing supplement product. The added version will be in DRAFT status, and will be created with version number n+1. The version will not be active until a start date is set and the version is published.\n", "operationId": "createSupplementProductVersion", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "requestBody": { "description": "The updated version of supplement product. The existing data in supplement product will be replaced by this one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplementProductRequest" }, "examples": { "dog": { "$ref": "#/components/examples/dog" }, "bicycle": { "$ref": "#/components/examples/bicycle" }, "luggage": { "$ref": "#/components/examples/luggage" }, "parking": { "$ref": "#/components/examples/parking" }, "upgrade": { "$ref": "#/components/examples/upgrade" }, "seatReservation": { "$ref": "#/components/examples/seatReservation" } } } }, "required": true }, "responses": { "201": { "description": "Supplement product created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplementProductResponse" }, "examples": { "parking": { "$ref": "#/components/examples/parking-2" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "409": { "description": "Conflict - Supplement product already exists", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "conflict": { "summary": "Supplement product already exists", "value": { "type": "https://developer.entur.org/errors/conflict", "title": "Conflict", "detail": "Supplement product with privateCode '123' already exists.", "status": 409 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/sales-offer-packages/{id}": { "get": { "tags": [ "Sales package" ], "summary": "Get a sales package by ID", "description": "Retrieve a sales package by its NeTEx ID.\n", "operationId": "getSalesOfferPackageById", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "responses": { "200": { "description": "Sales package found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOfferPackageResponse" }, "examples": { "withFareProducts": { "$ref": "#/components/examples/withFareProducts" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Sales package not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Sales package not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "SalesOfferPackage 'VYG:SalesOfferPackage:07c4332c' not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "put": { "tags": [ "Sales package" ], "summary": "Update a sales package", "description": "Update a sales package with a full replacement of its content. The client should\nfirst retrieve the current sales package, modify the desired fields, and send the\ncomplete object back.\n\nThis creates a new version of the sales package. The status field controls whether\nthe version is auto-published (VERSIONED) or created as a draft.\n", "operationId": "updateSalesOfferPackage", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "requestBody": { "description": "Full sales package representation including all fare product references.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOfferPackageRequest" }, "examples": { "updateWithFareProducts": { "$ref": "#/components/examples/updateWithFareProducts" } } } }, "required": true }, "responses": { "200": { "description": "Sales package updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOfferPackageResponse" }, "examples": { "withFareProducts": { "$ref": "#/components/examples/withFareProducts" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Sales package not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Sales package not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "SalesOfferPackage 'VYG:SalesOfferPackage:07c4332c' not found.", "status": 404 } } } } } }, "409": { "description": "Conflict - e.g. draft already in progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "draftInProgress": { "summary": "Draft already in progress", "value": { "type": "https://developer.entur.org/errors/conflict", "title": "Conflict", "detail": "Cannot create new version: a draft version is already in progress for VYG:SalesOfferPackage:07c4332c.", "status": 409 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/supplement-products/{id}/{version}": { "get": { "tags": [ "Supplement product" ], "summary": "Get a supplement product version", "description": "Retrieve the complete supplement product for a specific version,\nidentified by NeTEx version ID or version number.\n", "operationId": "getSupplementProductVersion", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } }, { "name": "version", "in": "path", "description": "The netex ID or sequence number of the version to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^(([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)|[1-9][0-9]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:Version:001" } } } ], "responses": { "200": { "description": "Supplement product version found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplementProductResponse" }, "examples": { "parking": { "$ref": "#/components/examples/parking-2" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Supplement product or version not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Supplement product version not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "Version 'EXA:Version:SP-abc123-v1' not found for SupplementProduct 'EXA:SupplementProduct:456'.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "put": { "tags": [ "Supplement product" ], "summary": "Update a version of a supplement product", "description": "Update the version of a supplement product. The version will not be active until a start date is set and the version is published.\n", "operationId": "updateSupplementProductVersion", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } }, { "name": "version", "in": "path", "description": "The netex ID or sequence number of the version to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^(([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)|[1-9][0-9]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:Version:001" } } } ], "requestBody": { "description": "The updated version of supplement product. The existing data in supplement product will be replaced by this one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplementProductRequest" }, "examples": { "dog": { "$ref": "#/components/examples/dog" }, "bicycle": { "$ref": "#/components/examples/bicycle" }, "luggage": { "$ref": "#/components/examples/luggage" }, "parking": { "$ref": "#/components/examples/parking" }, "upgrade": { "$ref": "#/components/examples/upgrade" }, "seatReservation": { "$ref": "#/components/examples/seatReservation" } } } }, "required": true }, "responses": { "200": { "description": "Supplement product updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplementProductResponse" }, "examples": { "parking": { "$ref": "#/components/examples/parking-2" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Supplement product not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "conflict": { "summary": "Supplement product not found", "value": { "type": "https://developer.entur.org/errors/conflict", "title": "Not Found", "detail": "Supplement product not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/sales-offer-packages/{id}/publication": { "put": { "tags": [ "Sales package" ], "summary": "Publish or promote a sales package version", "description": "Change the status of a sales package version. Used to promote versions through the\npublication workflow: DRAFT -> (PROPOSED ->) VERSIONED (-> DEPRECATED) \nor send back: PROPOSED -> DRAFT.\n", "operationId": "publishSalesOfferPackageVersion", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "requestBody": { "description": "Version ID, target status, and validity period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOfferPackagePublicationRequest" }, "examples": { "publishVersion": { "$ref": "#/components/examples/publishVersion" } } } }, "required": true }, "responses": { "200": { "description": "Version status updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOfferPackagePublicationResponse" }, "examples": { "published": { "$ref": "#/components/examples/published" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Sales package or version not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Version not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "Version 'VYG:Version:SP-905ec954-...' not found for SalesOfferPackage 'VYG:SalesOfferPackage:07c4332c'.", "status": 404 } } } } } }, "409": { "description": "Invalid status transition", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalidTransition": { "summary": "Invalid status transition", "value": { "type": "https://developer.entur.org/errors/conflict", "title": "Conflict", "detail": "Cannot transition from VERSIONED to DRAFT for VYG:SalesOfferPackage:07c4332c.", "status": 409 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/parameters/limitations/purchase-window": { "get": { "tags": [ "Purchase Window" ], "summary": "List purchase window instances", "description": "Returns a paginated list of all PurchaseWindow instances.", "operationId": "listPurchaseWindows", "parameters": [ { "name": "page", "in": "query", "description": "Zero-based page number. Defaults to 0.", "required": false, "style": "form", "explode": true, "schema": { "minimum": 0, "type": "integer", "default": 0 }, "examples": { "default": { "value": 0 } } }, { "name": "size", "in": "query", "description": "Number of instances per page. Defaults to 100.", "required": false, "style": "form", "explode": true, "schema": { "maximum": 1000, "minimum": 1, "type": "integer", "default": 100 }, "examples": { "default": { "value": 100 } } } ], "responses": { "200": { "description": "Paginated list of PurchaseWindow instances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseWindowListResponse" }, "examples": { "default": { "value": { "page": 0, "size": 100, "instances": [ { "id": "ENT:PurchaseWindow:120days", "name": [ { "lang": "nb-NO", "value": "120 dager før avgang" } ], "purchaseWhen": "ADVANCE_ONLY", "maximumPeriodBeforeDeparture": "P120D", "minimumPeriodBeforeDeparture": "PT0S" } ], "totalCount": 1 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "post": { "tags": [ "Purchase Window" ], "summary": "Create a purchase window instance", "description": "Create a new PurchaseWindow instance.", "operationId": "createPurchaseWindow", "parameters": [], "requestBody": { "description": "The PurchaseWindow instance to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseWindowRequest" }, "examples": { "default": { "value": { "name": [ { "lang": "nb-NO", "value": "120 dager før avgang" } ], "purchaseWhen": "ADVANCE_ONLY", "maximumPeriodBeforeDeparture": "P120D", "minimumPeriodBeforeDeparture": "PT0S" } } } } }, "required": true }, "responses": { "201": { "description": "PurchaseWindow instance created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseWindow" }, "examples": { "default": { "value": { "id": "ENT:PurchaseWindow:120days", "name": [ { "lang": "nb-NO", "value": "120 dager før avgang" } ], "purchaseWhen": "ADVANCE_ONLY", "maximumPeriodBeforeDeparture": "P120D", "minimumPeriodBeforeDeparture": "PT0S" } } } } } }, "400": { "description": "Bad request - Invalid data or schema violation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "schemaViolation": { "summary": "Request does not match type schema", "value": { "type": "https://developer.entur.org/errors/bad-request", "title": "Bad Request", "detail": "Field 'purchaseWhen' is required for type 'purchase-window'.", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/sales-offer-packages/{id}/fare-products": { "get": { "tags": [ "Sales package" ], "summary": "List fare products on a sales package", "description": "List all fare products currently assigned to a sales package.\n", "operationId": "listSalesOfferPackageFareProducts", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "responses": { "200": { "description": "List of fare products", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FareProductListItem" } }, "examples": { "fareProducts": { "$ref": "#/components/examples/fareProducts" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Sales package not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Sales package not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "SalesOfferPackage 'VYG:SalesOfferPackage:07c4332c' not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/parameters/limitations/entitlement-required": { "get": { "tags": [ "Entitlement Required" ], "summary": "List entitlement required instances", "description": "Returns a paginated list of all EntitlementRequired instances.", "operationId": "listEntitlementRequireds", "parameters": [ { "name": "page", "in": "query", "description": "Zero-based page number. Defaults to 0.", "required": false, "style": "form", "explode": true, "schema": { "minimum": 0, "type": "integer", "default": 0 }, "examples": { "default": { "value": 0 } } }, { "name": "size", "in": "query", "description": "Number of instances per page. Defaults to 100.", "required": false, "style": "form", "explode": true, "schema": { "maximum": 1000, "minimum": 1, "type": "integer", "default": 100 }, "examples": { "default": { "value": 100 } } } ], "responses": { "200": { "description": "Paginated list of EntitlementRequired instances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementRequiredListResponse" }, "examples": { "default": { "value": { "page": 0, "size": 100, "instances": [ { "id": "ENT:EntitlementRequired:SingleTicket", "name": [ { "lang": "nb-NO", "value": "Enkeltbillett påkrevd" } ], "fareProductRef": "ENT:PreassignedFareProduct:SingleTrip", "entitlementType": "SINGLE_TRIP" } ], "totalCount": 1 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "post": { "tags": [ "Entitlement Required" ], "summary": "Create an entitlement required instance", "description": "Create a new EntitlementRequired instance.", "operationId": "createEntitlementRequired", "parameters": [], "requestBody": { "description": "The EntitlementRequired instance to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementRequiredRequest" }, "examples": { "default": { "value": { "name": [ { "lang": "nb-NO", "value": "Enkeltbillett påkrevd" } ], "fareProductRef": "ENT:PreassignedFareProduct:SingleTrip", "entitlementType": "SINGLE_TRIP" } } } } }, "required": true }, "responses": { "201": { "description": "EntitlementRequired instance created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementRequired" }, "examples": { "default": { "value": { "id": "ENT:EntitlementRequired:SingleTicket", "name": [ { "lang": "nb-NO", "value": "Enkeltbillett påkrevd" } ], "fareProductRef": "ENT:PreassignedFareProduct:SingleTrip", "entitlementType": "SINGLE_TRIP" } } } } } }, "400": { "description": "Bad request - Invalid data or schema violation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "schemaViolation": { "summary": "Request does not match type schema", "value": { "type": "https://developer.entur.org/errors/bad-request", "title": "Bad Request", "detail": "Field 'entitlementType' is required for type 'entitlement-required'.", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/parameters/limitations/purchase-window/{id}": { "get": { "tags": [ "Purchase Window" ], "summary": "Get a purchase window instance", "description": "Retrieve the full detail of a single PurchaseWindow instance.", "operationId": "getPurchaseWindow", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "responses": { "200": { "description": "PurchaseWindow instance found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseWindow" }, "examples": { "default": { "value": { "id": "ENT:PurchaseWindow:120days", "name": [ { "lang": "nb-NO", "value": "120 dager før avgang" } ], "purchaseWhen": "ADVANCE_ONLY", "maximumPeriodBeforeDeparture": "P120D", "minimumPeriodBeforeDeparture": "PT0S" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "PurchaseWindow instance not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Instance not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "PurchaseWindow instance ENT:PurchaseWindow:nonexistent not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "put": { "tags": [ "Purchase Window" ], "summary": "Update a purchase window instance", "description": "Update an existing PurchaseWindow instance.", "operationId": "updatePurchaseWindow", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "requestBody": { "description": "The updated PurchaseWindow data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseWindowRequest" }, "examples": { "default": { "value": { "name": [ { "lang": "nb-NO", "value": "120 dager før avgang" } ], "purchaseWhen": "ADVANCE_ONLY", "maximumPeriodBeforeDeparture": "P120D", "minimumPeriodBeforeDeparture": "PT0S" } } } } }, "required": true }, "responses": { "200": { "description": "PurchaseWindow instance updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseWindow" }, "examples": { "default": { "value": { "id": "ENT:PurchaseWindow:120days", "name": [ { "lang": "nb-NO", "value": "120 dager før avgang" } ], "purchaseWhen": "ADVANCE_ONLY", "maximumPeriodBeforeDeparture": "P120D", "minimumPeriodBeforeDeparture": "PT0S" } } } } } }, "400": { "description": "Bad request - Invalid data or schema violation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "schemaViolation": { "summary": "Request does not match type schema", "value": { "type": "https://developer.entur.org/errors/bad-request", "title": "Bad Request", "detail": "Field 'purchaseWhen' is required for type 'purchase-window'.", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "PurchaseWindow instance not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Instance not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "PurchaseWindow instance ENT:PurchaseWindow:nonexistent not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/parameters/limitations/usage-validity-period": { "get": { "tags": [ "Usage Validity Period" ], "summary": "List usage validity period instances", "description": "Returns a paginated list of all UsageValidityPeriod instances.", "operationId": "listUsageValidityPeriods", "parameters": [ { "name": "page", "in": "query", "description": "Zero-based page number. Defaults to 0.", "required": false, "style": "form", "explode": true, "schema": { "minimum": 0, "type": "integer", "default": 0 }, "examples": { "default": { "value": 0 } } }, { "name": "size", "in": "query", "description": "Number of instances per page. Defaults to 100.", "required": false, "style": "form", "explode": true, "schema": { "maximum": 1000, "minimum": 1, "type": "integer", "default": 100 }, "examples": { "default": { "value": 100 } } } ], "responses": { "200": { "description": "Paginated list of UsageValidityPeriod instances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageValidityPeriodListResponse" }, "examples": { "default": { "value": { "page": 0, "size": 100, "instances": [ { "id": "ENT:UsageValidityPeriod:DuringTravel", "name": [ { "lang": "nb-NO", "value": "Under reise" } ], "activationType": "ON_CHECK_IN", "validityPeriod": "PT60M", "usageValidityType": "SINGLE_TRIP" } ], "totalCount": 1 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "post": { "tags": [ "Usage Validity Period" ], "summary": "Create a usage validity period instance", "description": "Create a new UsageValidityPeriod instance.", "operationId": "createUsageValidityPeriod", "parameters": [], "requestBody": { "description": "The UsageValidityPeriod instance to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageValidityPeriodRequest" }, "examples": { "default": { "value": { "name": [ { "lang": "nb-NO", "value": "Under reise" } ], "activationType": "ON_CHECK_IN", "validityPeriod": "PT60M", "usageValidityType": "SINGLE_TRIP" } } } } }, "required": true }, "responses": { "201": { "description": "UsageValidityPeriod instance created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageValidityPeriod" }, "examples": { "default": { "value": { "id": "ENT:UsageValidityPeriod:DuringTravel", "name": [ { "lang": "nb-NO", "value": "Under reise" } ], "activationType": "ON_CHECK_IN", "validityPeriod": "PT60M", "usageValidityType": "SINGLE_TRIP" } } } } } }, "400": { "description": "Bad request - Invalid data or schema violation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "schemaViolation": { "summary": "Request does not match type schema", "value": { "type": "https://developer.entur.org/errors/bad-request", "title": "Bad Request", "detail": "Field 'usageValidityType' is required for type 'usage-validity-period'.", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/parameters/limitations/entitlement-required/{id}": { "get": { "tags": [ "Entitlement Required" ], "summary": "Get an entitlement required instance", "description": "Retrieve the full detail of a single EntitlementRequired instance.", "operationId": "getEntitlementRequired", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "responses": { "200": { "description": "EntitlementRequired instance found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementRequired" }, "examples": { "default": { "value": { "id": "ENT:EntitlementRequired:SingleTicket", "name": [ { "lang": "nb-NO", "value": "Enkeltbillett påkrevd" } ], "fareProductRef": "ENT:PreassignedFareProduct:SingleTrip", "entitlementType": "SINGLE_TRIP" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "EntitlementRequired instance not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Instance not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "EntitlementRequired instance ENT:EntitlementRequired:nonexistent not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "put": { "tags": [ "Entitlement Required" ], "summary": "Update an entitlement required instance", "description": "Update an existing EntitlementRequired instance.", "operationId": "updateEntitlementRequired", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "requestBody": { "description": "The updated EntitlementRequired data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementRequiredRequest" }, "examples": { "default": { "value": { "name": [ { "lang": "nb-NO", "value": "Enkeltbillett påkrevd" } ], "fareProductRef": "ENT:PreassignedFareProduct:SingleTrip", "entitlementType": "SINGLE_TRIP" } } } } }, "required": true }, "responses": { "200": { "description": "EntitlementRequired instance updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementRequired" }, "examples": { "default": { "value": { "id": "ENT:EntitlementRequired:SingleTicket", "name": [ { "lang": "nb-NO", "value": "Enkeltbillett påkrevd" } ], "fareProductRef": "ENT:PreassignedFareProduct:SingleTrip", "entitlementType": "SINGLE_TRIP" } } } } } }, "400": { "description": "Bad request - Invalid data or schema violation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "schemaViolation": { "summary": "Request does not match type schema", "value": { "type": "https://developer.entur.org/errors/bad-request", "title": "Bad Request", "detail": "Field 'entitlementType' is required for type 'entitlement-required'.", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "EntitlementRequired instance not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Instance not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "EntitlementRequired instance ENT:EntitlementRequired:nonexistent not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/parameters/limitations/usage-validity-period/{id}": { "get": { "tags": [ "Usage Validity Period" ], "summary": "Get a usage validity period instance", "description": "Retrieve the full detail of a single UsageValidityPeriod instance.", "operationId": "getUsageValidityPeriod", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "responses": { "200": { "description": "UsageValidityPeriod instance found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageValidityPeriod" }, "examples": { "default": { "value": { "id": "ENT:UsageValidityPeriod:DuringTravel", "name": [ { "lang": "nb-NO", "value": "Under reise" } ], "activationType": "ON_CHECK_IN", "validityPeriod": "PT60M", "usageValidityType": "SINGLE_TRIP" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "UsageValidityPeriod instance not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Instance not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "UsageValidityPeriod instance ENT:UsageValidityPeriod:nonexistent not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "put": { "tags": [ "Usage Validity Period" ], "summary": "Update a usage validity period instance", "description": "Update an existing UsageValidityPeriod instance.", "operationId": "updateUsageValidityPeriod", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "requestBody": { "description": "The updated UsageValidityPeriod data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageValidityPeriodRequest" }, "examples": { "default": { "value": { "name": [ { "lang": "nb-NO", "value": "Under reise" } ], "activationType": "ON_CHECK_IN", "validityPeriod": "PT60M", "usageValidityType": "SINGLE_TRIP" } } } } }, "required": true }, "responses": { "200": { "description": "UsageValidityPeriod instance updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageValidityPeriod" }, "examples": { "default": { "value": { "id": "ENT:UsageValidityPeriod:DuringTravel", "name": [ { "lang": "nb-NO", "value": "Under reise" } ], "activationType": "ON_CHECK_IN", "validityPeriod": "PT60M", "usageValidityType": "SINGLE_TRIP" } } } } } }, "400": { "description": "Bad request - Invalid data or schema violation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "schemaViolation": { "summary": "Request does not match type schema", "value": { "type": "https://developer.entur.org/errors/bad-request", "title": "Bad Request", "detail": "Field 'usageValidityType' is required for type 'usage-validity-period'.", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "UsageValidityPeriod instance not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Instance not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "UsageValidityPeriod instance ENT:UsageValidityPeriod:nonexistent not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/supplement-products/{id}/sales-offer-package-assignments": { "get": { "tags": [ "Sales package assignment" ], "summary": "List sales package assignments for a supplement product", "description": "List all sales packages that a supplement product is currently assigned to,\nincluding the version reference for each assignment.\n", "operationId": "listSalesOfferPackageAssignments", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "responses": { "200": { "description": "List of sales package assignments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SalesOfferPackageAssignmentListItem" } }, "examples": { "assignmentList": { "$ref": "#/components/examples/assignmentList" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Supplement product not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Supplement product not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "SupplementProduct 'BNR:SupplementProduct:e006fb5c' not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:les" } }, "post": { "tags": [ "Sales package assignment" ], "summary": "Assign supplement product to sales packages", "description": "Assign a supplement product to one or more sales packages. Each assignment creates a new\nversion of the target sales package containing the supplement product reference.\n\nThis is a best-effort batch operation — failure on one sales package does not prevent\nprocessing of the others. The response body conveys per-item results; callers must\ninspect each item's status rather than relying solely on the HTTP status code.\n\nIf the supplement product is already assigned to a sales package but with a different version,\nthe version reference is updated (upsert semantics).\n\nThe caller must have an agreement with the sales package owner (verified against the agreement\nregister). The caller must also own the supplement product.\n", "operationId": "createSalesOfferPackageAssignments", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } } ], "requestBody": { "description": "Supplement product version and target sales packages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOfferPackageAssignmentRequest" }, "examples": { "assignParking": { "$ref": "#/components/examples/assignParking" }, "assignParkingAsDraft": { "$ref": "#/components/examples/assignParkingAsDraft" } } } }, "required": true }, "responses": { "200": { "description": "Per-sales-offer-package results. Each item indicates SUCCESS or FAILED with details;\ninspect individual results rather than relying solely on the HTTP status.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOfferPackageAssignmentResponse" }, "examples": { "allSuccess": { "$ref": "#/components/examples/allSuccess" }, "multiStatus": { "$ref": "#/components/examples/multiStatus" }, "draftCreated": { "$ref": "#/components/examples/draftCreated" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Supplement product not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Supplement product not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "SupplementProduct 'BNR:SupplementProduct:e006fb5c' not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v3/supplement-products/{id}/sales-offer-package-assignments/{salesOfferPackageId}": { "delete": { "tags": [ "Sales package assignment" ], "summary": "Remove supplement product from a sales package", "description": "Remove the assignment of a supplement product from a sales package. This creates a new\nversion of the sales package without the supplement product reference.\n\nOnly the supplement product owner or the sales package owner can remove the assignment.\n", "operationId": "deleteSalesOfferPackageAssignment", "parameters": [ { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } }, { "name": "salesOfferPackageId", "in": "path", "description": "NeTEx ID of the sales package to remove the assignment from.", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):SalesOfferPackage:([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "VYG:SalesOfferPackage:07c4332c" } } } ], "responses": { "204": { "description": "Assignment removed successfully" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Supplement product or sales package not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notFound": { "summary": "Assignment not found", "value": { "type": "https://developer.entur.org/errors/not-found", "title": "Not Found", "detail": "Assignment of 'BNR:SupplementProduct:e006fb5c' to 'VYG:SalesOfferPackage:07c4332c' not found.", "status": 404 } } } } } } }, "x-entur-permissions": { "value": "product-api-access:endre" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] } }, "components": { "schemas": { "VatGrpupType": { "type": "string", "description": "VAT group type. This is used to determine which VAT rate applies to a product. The VAT group type is determined by the product type and the country of sale. For example, in Norway, food products are subject to a reduced VAT rate of 15%, while other products are subject to the standard VAT rate of 25%. In this case, food products would be classified as FOOD_VAT, while other products would be classified as GENERAL_VAT.", "default": "TRANSPORT_AND_TICKETS_VAT", "enum": [ "EXCEPTION_FROM_VAT", "GENERAL_VAT", "FOOD_VAT", "TRANSPORT_AND_TICKETS_VAT" ] }, "VersionStatus": { "type": "string", "enum": [ "DRAFT", "PROPOSED", "VERSIONED", "DEPRECATED" ] }, "FareProductRef": { "required": [ "fareProductId", "fareProductVersionId" ], "type": "object", "properties": { "fareProductId": { "type": "string", "description": "NeTEx ID of the fare product.", "examples": [ "EXA:SupplementProduct:e006fb5c" ] }, "fareProductVersionId": { "pattern": "^([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx version ID of the fare product.", "examples": [ "EXA:Version:FP-4725c71a-abcd-1234-efgh-567890abcdef" ] }, "fareProductVersionNumber": { "type": "integer", "description": "Sequence number of the fare product version. Optional — set at publication.", "examples": [ 5 ] } }, "description": "Reference to a specific version of a fare product (e.g. SupplementProduct, PreassignedFareProduct)." }, "ProblemDetails": { "required": [ "detail", "status", "title", "type" ], "type": "object", "properties": { "type": { "type": "string", "description": "A URI reference that identifies the problem type.", "format": "uri", "examples": [ "https://developer.entur.org/errors/bad-request" ] }, "title": { "type": "string", "description": "Short, human-readable summary of the problem type.", "examples": [ "Bad Request" ] }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence.", "examples": [ "The supplied ruleId is not a valid UUID." ] }, "status": { "type": "integer", "description": "The HTTP status code.", "format": "int32", "examples": [ 400 ] }, "instance": { "type": "string", "description": "A URI reference that identifies the specific occurrence.", "format": "uri", "examples": [ "https://api.example.com/requests/12345" ] } }, "description": "RFC 9457 Problem Details" }, "PurchaseWindow": { "required": [ "id", "maximumPeriodBeforeDeparture", "name", "purchaseWhen" ], "type": "object", "properties": { "id": { "pattern": "^([A-Z]{3}):PurchaseWindow:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "The NeTEx ID of this PurchaseWindow.", "examples": [ "ENT:PurchaseWindow:120days" ] }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "purchaseWhen": { "type": "string", "description": "When the product can be purchased relative to departure.", "enum": [ "ADVANCE_ONLY", "UNTIL_DEPARTURE", "AFTER_BOARDING", "ANY_TIME" ] }, "maximumPeriodBeforeDeparture": { "type": "string", "description": "Maximum time before departure that a purchase can be made. ISO 8601 duration.", "examples": [ "P120D" ] }, "minimumPeriodBeforeDeparture": { "type": "string", "description": "Minimum time before departure that a purchase can be made. ISO 8601 duration.", "examples": [ "PT0S" ] } } }, "VersionRequest": { "required": [ "startDate", "status" ], "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/VersionStatus" }, { "description": "Must be DRAFT for new versions." } ] }, "endDate": { "type": "string", "description": "The end date of the version (optional).", "format": "date" }, "startDate": { "type": "string", "description": "The start date of the version. Defaults to current date if not provided.", "format": "date" }, "ownerOrganisationId": { "type": "integer", "description": "The ID of the organisation that owns the version. The service will fetch the owner organisation from auth token if no organizsation i set here." } } }, "AssignmentError": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code.", "enum": [ "NO_AGREEMENT", "NOT_FOUND", "ACCESS_DENIED", "VALIDITY_CONFLICT", "DRAFT_IN_PROGRESS" ], "examples": [ "NO_AGREEMENT" ] }, "message": { "type": "string", "description": "Human-readable error message.", "examples": [ "Ingen avtale med SJN for denne salgspakka" ] } }, "description": "Error details for a failed assignment." }, "LocalizedString": { "type": "array", "items": { "required": [ "lang", "value" ], "type": "object", "properties": { "lang": { "pattern": "^[a-z]{2}-[A-Z]{2}$", "type": "string", "description": "BCP-47 language tag (e.g., 'nb-NO', 'en-GB').", "examples": [ "nb-NO" ] }, "value": { "type": "string", "description": "The localized string value for the specified lang." } } } }, "VersionResponse": { "required": [ "changed", "created", "id", "startDate", "status" ], "type": "object", "properties": { "id": { "pattern": "^([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "The netex id reference to the object.", "examples": [ "EXA:Version:001" ] }, "number": { "type": "integer", "description": "Version number of the version. Only present when versionStatus is VERSIONED. Starts at 1 for a new product and is incremented by 1 for each new version.", "format": "int64", "examples": [ 1 ] }, "status": { "$ref": "#/components/schemas/VersionStatus" }, "changed": { "type": "string", "description": "Changed datetime", "format": "date-time" }, "created": { "type": "string", "description": "Created datetime", "format": "date-time" }, "endDate": { "type": "string", "description": "The end date of the version.", "format": "date" }, "published": { "type": "string", "description": "Timestamp for when the version was published (set to status VERSIONED).", "format": "date-time" }, "startDate": { "type": "string", "description": "The start date of the version.", "format": "date" } } }, "ConditionsSummary": { "required": [ "exchangeable", "fareStructureType", "refundable" ], "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether the supplement product is refundable.", "examples": [ false ] }, "exchangeable": { "type": "boolean", "description": "Whether the supplement product is exchangeable.", "examples": [ true ] }, "fareStructureType": { "$ref": "#/components/schemas/FareStructureType" } } }, "FareStructureType": { "type": "string", "description": "The type of fare structure. This indicates the method by which the fare is calculated, e.g. flat fare, zonal fare, point-to-point fare, etc.", "enum": [ "CAPPED_FLAT_FARE", "CAPPED_POINT_TO_POINT_FARE", "CAPPED_ZONAL_FARE", "LINE_FLAT_FARE", "NETWORK_FLAT_FARE", "POINT_TO_POINT_FARE", "POINT_TO_POINT_DISTANCE_FARE", "STAGE_FARE", "ZONE_FLAT_FARE", "ZONE_SEQUENCE_FARE", "ZONE_TO_ZONE_FARE", "ZONE_COUNT_FARE", "PENALTY_FARE", "OTHER" ] }, "ChargingMomentType": { "type": "string", "description": "Charging moment type.\n\nNote: Currently, only `BEFORE_TRAVEL` is supported in Entur sales platform.\n", "enum": [ "BEFORE_TRAVEL", "ON_START_OF_TRAVEL", "BEFORE_END_OF_TRAVEL", "BEFORE_TRAVEL_THEN_ADJUST_AT_END_OF_TRAVEL", "ON_START_THEN_ADJUST_AT_END_OF_TRAVEL", "ON_START_THEN_ADJUST_AT_END_OF_FARE_DAY", "ON_START_THEN_ADJUST_AT_END_OF_CHARGE_PERIOD", "AT_END_OF_TRAVEL", "AT_END_OF_FARE_DAY", "AT_END_OF_CHARGE_PERIOD", "FREE", "ANY_TIME", "OTHER" ] }, "ValidityParameters": { "required": [ "groupingType", "validityParameterRefs", "validityParameterType" ], "type": "object", "properties": { "groupingType": { "$ref": "#/components/schemas/GenericParameterAssignmentGroupingType" }, "validityParameterRefs": { "type": "array", "description": "List of references for the validity parameters", "items": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx reference to validity parameter" } }, "validityParameterType": { "type": "string", "enum": [ "LINE", "ZONE", "ZONE_GROUP", "STOP_PLACE", "PARKING", "ROUTE_SECTION", "TARIFF_AUTHORITY", "OPERATOR", "TRANSPORT_MODE", "FLEXIBLE_LINE", "CLASS_OF_USE", "FACILITY", "SALES_CHANNEL", "AUTHORITY" ] } }, "examples": [ { "groupingType": "OR", "validityParameterRefs": [ "VYG:Line:L1", "VYG:Line:L2" ], "validityParameterType": "LINE" } ] }, "EntitlementRequired": { "required": [ "entitlementType", "fareProductRef", "id", "name" ], "type": "object", "properties": { "id": { "pattern": "^([A-Z]{3}):EntitlementRequired:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "The NeTEx ID of this EntitlementRequired.", "examples": [ "ENT:EntitlementRequired:SingleTicket" ] }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "fareProductRef": { "pattern": "^([A-Z]{3}):PreassignedFareProduct:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "Reference to the fare product that satisfies this entitlement.", "examples": [ "ENT:PreassignedFareProduct:SingleTrip" ] }, "entitlementType": { "type": "string", "description": "The type of entitlement that is required.", "enum": [ "SINGLE_TRIP", "PERIOD_PASS", "DAY_PASS", "CARNET" ] } } }, "FareProductListItem": { "required": [ "id", "productType", "versionId" ], "type": "object", "properties": { "id": { "type": "string", "description": "NeTEx ID of the fare product.", "examples": [ "EXA:SupplementProduct:e006fb5c" ] }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "versionId": { "pattern": "^([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx version ID of the fare product.", "examples": [ "EXA:Version:FP-4725c71a-abcd-1234-efgh-567890abcdef" ] }, "productType": { "type": "string", "description": "Type of the fare product.", "enum": [ "SUPPLEMENT_PRODUCT", "PREASSIGNED_FARE_PRODUCT" ], "examples": [ "SUPPLEMENT_PRODUCT" ] } } }, "UsageValidityPeriod": { "required": [ "id", "name", "usageValidityType" ], "type": "object", "properties": { "id": { "pattern": "^([A-Z]{3}):UsageValidityPeriod:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "The NeTEx ID of this UsageValidityPeriod.", "examples": [ "ENT:UsageValidityPeriod:DuringTravel" ] }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "activationType": { "type": "string", "description": "What triggers the start of the validity period.", "enum": [ "ON_PURCHASE", "ON_FIRST_USE", "ON_CHECK_IN" ] }, "validityPeriod": { "type": "string", "description": "How long the product is valid after activation. ISO 8601 duration.", "examples": [ "PT60M" ] }, "usageValidityType": { "type": "string", "description": "The type of usage validity.", "enum": [ "SINGLE_TRIP", "RETURN_TRIP", "CARNET", "DAY_PASS", "WEEKLY_PASS", "MONTHLY_PASS", "ANNUAL_PASS", "CUSTOM_PERIOD" ] } } }, "PurchaseWindowRequest": { "required": [ "maximumPeriodBeforeDeparture", "name", "purchaseWhen" ], "type": "object", "properties": { "name": { "$ref": "#/components/schemas/LocalizedString" }, "purchaseWhen": { "type": "string", "description": "When the product can be purchased relative to departure.", "enum": [ "ADVANCE_ONLY", "UNTIL_DEPARTURE", "AFTER_BOARDING", "ANY_TIME" ] }, "maximumPeriodBeforeDeparture": { "type": "string", "description": "Maximum time before departure that a purchase can be made. ISO 8601 duration.", "examples": [ "P120D" ] }, "minimumPeriodBeforeDeparture": { "type": "string", "description": "Minimum time before departure that a purchase can be made. ISO 8601 duration.", "examples": [ "PT0S" ] } } }, "SupplementProductType": { "type": "string", "description": "The type of the supplement product. This can be used to determine which parameters are relevant for the product.", "enum": [ "SEAT_RESERVATION", "BICYCLE", "DOG", "ANIMAL", "MEAL", "WIFI", "EXTRA_LUGGAGE", "PENALTY", "UPGRADE", "JOURNEY_EXTENSION", "JOURNEY_ADD_ON", "EVENT_ADD_ON", "PARKING" ] }, "SalesOfferPackageRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "$ref": "#/components/schemas/LocalizedString" }, "status": { "allOf": [ { "$ref": "#/components/schemas/VersionStatus" }, { "description": "Status of the created sales package version. Defaults to VERSIONED.\n\n- **DRAFT** - Creates a draft version.\n- **PROPOSED** - Creates a proposed version pending review.\n- **VERSIONED** - Publishes the version immediately (default).\n", "examples": [ "VERSIONED" ] } ] }, "fareProducts": { "type": "array", "description": "List of fare product references to include in this sales package.", "items": { "$ref": "#/components/schemas/FareProductRef" } } } }, "SupplementProductRequest": { "required": [ "chargingMomentType", "conditionsSummary", "entitlementRequiredRefs", "farePrice", "names", "ownerOrganisationId", "purchaseWindowRef", "startDate", "status", "supplementProductType", "usageValidityPeriodRef", "validityParameters", "vatGroup" ], "type": "object", "properties": { "names": { "$ref": "#/components/schemas/LocalizedString" }, "status": { "allOf": [ { "$ref": "#/components/schemas/VersionStatus" }, { "description": "Status of the supplement product. Defaults to VERSIONED.\n\n- **DRAFT** - Under construction and not ready for operational use.\n- **PROPOSED** - Complete but pending review and approval.\n- **VERSIONED** - Finalized and frozen; a new version must be created for further modifications. Remains authoritative for its validity period even after expiry.\n- **DEPRECATED** - Explicitly withdrawn and should not be used; indicates an active decision to retract, not a natural expiry.\n", "examples": [ "VERSIONED" ] } ] }, "endDate": { "type": "string", "description": "The end date of the version (optional).", "format": "date" }, "vatGroup": { "$ref": "#/components/schemas/VatGrpupType" }, "farePrice": { "required": [ "amount", "currency" ], "type": "object", "properties": { "amount": { "type": "number", "description": "The price amount in the major currency unit (e.g., kroner, not ore).", "examples": [ 400 ] }, "currency": { "type": "string", "description": "The currency code for the price (e.g., 'NOK', 'EUR')." } } }, "startDate": { "type": "string", "description": "The start date of the version.", "format": "date" }, "privateCode": { "type": "string", "description": "Optional external system identifier. Used to generate the NeTEx ID as the last segment (e.g., privateCode '123' produces 'XXX:SupplementProduct:123'). If not provided, the NeTEx ID will be generated automatically.", "examples": [ "123" ] }, "descriptions": { "$ref": "#/components/schemas/LocalizedString" }, "conditionsSummary": { "$ref": "#/components/schemas/ConditionsSummary" }, "purchaseWindowRef": { "pattern": "^([A-Z]{3}):PurchaseWindow:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx ID of a PurchaseWindow instance (limitations/purchase-window). Available values are listed in the Parameter Catalog API.\n", "examples": [ "ENT:PurchaseWindow:120days" ] }, "chargingMomentType": { "$ref": "#/components/schemas/ChargingMomentType" }, "validityParameters": { "type": "array", "description": "List of validity parameters. The specified parameter tells where the supplement product is valid. This can be lines, zones, stops etc.", "items": { "$ref": "#/components/schemas/ValidityParameters" } }, "ownerOrganisationId": { "type": "integer", "description": "The ID of the organization that owns the supplement product. Available organizations can be retrieved from the Organization Management API (external to this specification).", "format": "int64" }, "supplementProductType": { "$ref": "#/components/schemas/SupplementProductType" }, "usageValidityPeriodRef": { "pattern": "^([A-Z]{3}):UsageValidityPeriod:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx ID of a UsageValidityPeriod instance (limitations/usage-validity-period). Available values are listed in the Parameter Catalog API.\n", "examples": [ "ENT:UsageValidityPeriod:DuringTravel" ] }, "entitlementRequiredRefs": { "minItems": 1, "type": "array", "description": "List of NeTEx IDs of EntitlementRequired instances (limitations/entitlement-required). Available values are listed in the Parameter Catalog API.\n", "items": { "pattern": "^([A-Z]{3}):EntitlementRequired:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx ID of an EntitlementRequired instance.", "examples": [ "ENT:EntitlementRequired:SingleTicket" ] } } } }, "SalesOfferPackageResponse": { "required": [ "id", "name", "status", "versionId" ], "type": "object", "properties": { "id": { "pattern": "^([A-Z]{3}):SalesOfferPackage:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx ID of the sales package.", "examples": [ "VYG:SalesOfferPackage:07c4332c" ] }, "name": { "$ref": "#/components/schemas/LocalizedString" }, "status": { "allOf": [ { "$ref": "#/components/schemas/VersionStatus" }, { "description": "Status of this sales package version.", "examples": [ "VERSIONED" ] } ] }, "validTo": { "type": "string", "description": "End of the validity period. No specified date means that the validity period has no end-date.", "format": "date", "examples": [ "2026-12-31" ] }, "validFrom": { "type": "string", "description": "Start of the validity period (travel dates, not version date).", "format": "date", "examples": [ "2026-03-18" ] }, "versionId": { "pattern": "^([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx version ID.", "examples": [ "VYG:Version:SP-905ec954-abcd-1234-efgh-567890abcdef" ] }, "fareProducts": { "type": "array", "description": "List of fare product references included in this sales package.", "items": { "$ref": "#/components/schemas/FareProductRef" } }, "publishedDate": { "type": "string", "description": "System-assigned timestamp of when the version was published. Only present for VERSIONED status.", "format": "date-time", "examples": [ "2026-03-18T10:30:00Z" ] }, "versionNumber": { "type": "integer", "description": "The version number. Only present for published versions.", "examples": [ 14 ] }, "ownerOrganisationId": { "type": "integer", "description": "The ID of the organization that owns the sales package.", "examples": [ 1 ] } } }, "SupplementProductResponse": { "required": [ "chargingMomentType", "conditionsSummary", "entitlementRequiredRefs", "farePrice", "id", "names", "ownerOrganisationId", "purchaseWindowRef", "startDate", "status", "supplementProductType", "usageValidityPeriodRef", "validityParameters", "vatGroup", "versionId" ], "type": "object", "properties": { "id": { "pattern": "^([A-Z]{3}):SupplementProduct:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "The NeTEx ID of the supplement product.", "examples": [ "BNR:SupplementProduct:123" ] }, "names": { "$ref": "#/components/schemas/LocalizedString" }, "status": { "allOf": [ { "$ref": "#/components/schemas/VersionStatus" }, { "description": "Status of the supplement product.\n\n- **DRAFT** - Under construction and not ready for operational use.\n- **PROPOSED** - Complete but pending review and approval.\n- **VERSIONED** - Finalized and frozen; a new version must be created for further modifications. Remains authoritative for its validity period even after expiry.\n- **DEPRECATED** - Explicitly withdrawn and should not be used; indicates an active decision to retract, not a natural expiry.\n", "examples": [ "VERSIONED" ] } ] }, "endDate": { "type": "string", "description": "The end date of the version (optional).", "format": "date" }, "vatGroup": { "$ref": "#/components/schemas/VatGrpupType" }, "farePrice": { "required": [ "amount", "currency" ], "type": "object", "properties": { "amount": { "type": "number", "description": "The price amount in the major currency unit (e.g., kroner, not ore).", "examples": [ 400 ] }, "currency": { "type": "string", "description": "The currency code for the price (e.g., 'NOK', 'EUR')." } } }, "startDate": { "type": "string", "description": "The start date of the version.", "format": "date" }, "versionId": { "pattern": "^([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "The netex id reference to the object.", "examples": [ "EXA:Version:001" ] }, "datasource": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the datasource.", "examples": [ "entur" ] } }, "description": "The datasource that owns this supplement product." }, "privateCode": { "type": "string", "description": "Optional external system identifier. Used to generate the NeTEx ID as the last segment (e.g., privateCode '123' produces 'XXX:SupplementProduct:123'). If not provided, the NeTEx ID will be generated automatically.", "examples": [ "123" ] }, "descriptions": { "$ref": "#/components/schemas/LocalizedString" }, "versionNumber": { "type": "integer", "description": "Version number of the version. Only present when versionStatus is VERSIONED. Starts at 1 for a new product and is incremented by 1 for each new version.", "format": "int64", "examples": [ 1 ] }, "conditionsSummary": { "$ref": "#/components/schemas/ConditionsSummary" }, "purchaseWindowRef": { "pattern": "^([A-Z]{3}):PurchaseWindow:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx ID of a PurchaseWindow instance (limitations/purchase-window). Available values are listed in the Parameter Catalog API.\n", "examples": [ "ENT:PurchaseWindow:120days" ] }, "chargingMomentType": { "$ref": "#/components/schemas/ChargingMomentType" }, "validityParameters": { "type": "array", "description": "List of validity parameters. The specified parameter tells where the supplement product is valid. This can be lines, zones, stops etc.", "items": { "$ref": "#/components/schemas/ValidityParameters" } }, "ownerOrganisationId": { "type": "integer", "description": "The ID of the organization that owns the supplement product. Refer to your organization management service or documentation for how to obtain valid organization IDs.", "format": "int64" }, "supplementProductType": { "$ref": "#/components/schemas/SupplementProductType" }, "usageValidityPeriodRef": { "pattern": "^([A-Z]{3}):UsageValidityPeriod:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx ID of a UsageValidityPeriod instance (limitations/usage-validity-period). Available values are listed in the Parameter Catalog API.\n", "examples": [ "ENT:UsageValidityPeriod:DuringTravel" ] }, "entitlementRequiredRefs": { "minItems": 1, "type": "array", "description": "List of NeTEx IDs of EntitlementRequired instances (limitations/entitlement-required). Available values are listed in the Parameter Catalog API.\n", "items": { "pattern": "^([A-Z]{3}):EntitlementRequired:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx ID of an EntitlementRequired instance.", "examples": [ "ENT:EntitlementRequired:SingleTicket" ] } } } }, "EntitlementRequiredRequest": { "required": [ "entitlementType", "fareProductRef", "name" ], "type": "object", "properties": { "name": { "$ref": "#/components/schemas/LocalizedString" }, "fareProductRef": { "pattern": "^([A-Z]{3}):PreassignedFareProduct:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "Reference to the fare product that satisfies this entitlement.", "examples": [ "ENT:PreassignedFareProduct:SingleTrip" ] }, "entitlementType": { "type": "string", "description": "The type of entitlement that is required.", "enum": [ "SINGLE_TRIP", "PERIOD_PASS", "DAY_PASS", "CARNET" ] } } }, "PurchaseWindowListResponse": { "required": [ "instances", "page", "size", "totalCount" ], "type": "object", "properties": { "page": { "type": "integer", "description": "Current zero-based page number.", "examples": [ 0 ] }, "size": { "type": "integer", "description": "Number of instances per page.", "examples": [ 100 ] }, "instances": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseWindow" } }, "totalCount": { "type": "integer", "description": "Total number of PurchaseWindow instances.", "examples": [ 5 ] } } }, "UsageValidityPeriodRequest": { "required": [ "name", "usageValidityType" ], "type": "object", "properties": { "name": { "$ref": "#/components/schemas/LocalizedString" }, "activationType": { "type": "string", "description": "What triggers the start of the validity period.", "enum": [ "ON_PURCHASE", "ON_FIRST_USE", "ON_CHECK_IN" ] }, "validityPeriod": { "type": "string", "description": "How long the product is valid after activation. ISO 8601 duration.", "examples": [ "PT60M" ] }, "usageValidityType": { "type": "string", "description": "The type of usage validity.", "enum": [ "SINGLE_TRIP", "RETURN_TRIP", "CARNET", "DAY_PASS", "WEEKLY_PASS", "MONTHLY_PASS", "ANNUAL_PASS", "CUSTOM_PERIOD" ] } } }, "EntitlementRequiredListResponse": { "required": [ "instances", "page", "size", "totalCount" ], "type": "object", "properties": { "page": { "type": "integer", "description": "Current zero-based page number.", "examples": [ 0 ] }, "size": { "type": "integer", "description": "Number of instances per page.", "examples": [ 100 ] }, "instances": { "type": "array", "items": { "$ref": "#/components/schemas/EntitlementRequired" } }, "totalCount": { "type": "integer", "description": "Total number of EntitlementRequired instances.", "examples": [ 4 ] } } }, "UsageValidityPeriodListResponse": { "required": [ "instances", "page", "size", "totalCount" ], "type": "object", "properties": { "page": { "type": "integer", "description": "Current zero-based page number.", "examples": [ 0 ] }, "size": { "type": "integer", "description": "Number of instances per page.", "examples": [ 100 ] }, "instances": { "type": "array", "items": { "$ref": "#/components/schemas/UsageValidityPeriod" } }, "totalCount": { "type": "integer", "description": "Total number of UsageValidityPeriod instances.", "examples": [ 8 ] } } }, "SupplementProductVersionListItem": { "required": [ "id", "versionId" ], "type": "object", "properties": { "id": { "pattern": "^([A-Z]{3}):SupplementProduct:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx ID of the supplement product.", "examples": [ "EXA:SupplementProduct:456" ] }, "versionId": { "pattern": "^([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx version ID.", "examples": [ "EXA:Version:SP-abc123-v1" ] } } }, "SalesOfferPackageAssignmentRequest": { "required": [ "fareProductVersionId", "salesOfferPackageIds" ], "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/VersionStatus" }, { "description": "Status of the created sales package version. Defaults to VERSIONED (auto-publish).\n\n- **DRAFT** - Creates a draft version that must be manually published via PUT /sales-offer-packages/{id}/publication.\n- **PROPOSED** - Creates a proposed version pending review.\n- **VERSIONED** - Auto-publishes the new version immediately (default).\n", "examples": [ "VERSIONED" ] } ] }, "fareProductVersionId": { "pattern": "^([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx version ID of the fare product version to assign.", "examples": [ "EXA:Version:FP-4725c71a-abcd-1234-efgh-567890abcdef" ] }, "salesOfferPackageIds": { "minItems": 1, "type": "array", "description": "List of sales package NeTEx IDs to assign the fare product to.", "items": { "pattern": "^([A-Z]{3}):SalesOfferPackage:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx ID of a sales package.", "examples": [ "VYG:SalesOfferPackage:07c4332c" ] } } } }, "SalesOfferPackageAssignmentListItem": { "required": [ "fareProductId", "fareProductVersionId", "salesOfferPackageId" ], "type": "object", "properties": { "fareProductId": { "type": "string", "description": "NeTEx ID of the fare product.", "examples": [ "EXA:SupplementProduct:e006fb5c" ] }, "salesOfferPackageId": { "pattern": "^([A-Z]{3}):SalesOfferPackage:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx ID of the sales package.", "examples": [ "VYG:SalesOfferPackage:07c4332c" ] }, "fareProductVersionId": { "pattern": "^([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx version ID of the assigned fare product version.", "examples": [ "EXA:Version:FP-4725c71a-abcd-1234-efgh-567890abcdef" ] }, "salesOfferPackageName": { "$ref": "#/components/schemas/LocalizedString" } } }, "SalesOfferPackageAssignmentResponse": { "required": [ "results" ], "type": "object", "properties": { "results": { "type": "array", "description": "Per-sales-offer-package result. Best-effort — failure on one sales package does not stop others.", "items": { "$ref": "#/components/schemas/SalesOfferPackageAssignmentResultItem" } } } }, "SalesOfferPackagePublicationRequest": { "required": [ "status", "validFrom", "versionId" ], "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/VersionStatus" }, { "description": "Target status. Valid transitions: DRAFT → PROPOSED → VERSIONED, PROPOSED → DRAFT.\n", "examples": [ "VERSIONED" ] } ] }, "validTo": { "type": "string", "description": "End of the validity period. No specified date means that the validity period has no end-date.", "format": "date", "examples": [ "2026-12-31" ] }, "validFrom": { "type": "string", "description": "Start of the validity period (travel dates).", "format": "date", "examples": [ "2026-03-18" ] }, "versionId": { "pattern": "^([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx version ID of the sales package version to publish.", "examples": [ "VYG:Version:SP-905ec954-abcd-1234-efgh-567890abcdef" ] } } }, "SalesOfferPackagePublicationResponse": { "required": [ "salesOfferPackageId", "status", "validFrom", "versionId" ], "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/VersionStatus" }, { "description": "The resulting version status.", "examples": [ "VERSIONED" ] } ] }, "validTo": { "type": "string", "description": "End of the validity period. No specified date means that the validity period has no end-date.", "format": "date", "examples": [ "2026-12-31" ] }, "validFrom": { "type": "string", "description": "Start of the validity period.", "format": "date", "examples": [ "2026-03-18" ] }, "versionId": { "pattern": "^([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx version ID.", "examples": [ "VYG:Version:SP-905ec954-abcd-1234-efgh-567890abcdef" ] }, "publishedDate": { "type": "string", "description": "System-assigned publication timestamp. Only present for VERSIONED status.", "format": "date-time", "examples": [ "2026-03-18T10:30:00Z" ] }, "versionNumber": { "type": "integer", "description": "Version number assigned at publication. Only present for VERSIONED status.", "examples": [ 14 ] }, "salesOfferPackageId": { "pattern": "^([A-Z]{3}):SalesOfferPackage:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx ID of the sales package.", "examples": [ "VYG:SalesOfferPackage:07c4332c" ] } } }, "SalesOfferPackageAssignmentResultItem": { "required": [ "salesOfferPackageId", "status" ], "type": "object", "properties": { "error": { "$ref": "#/components/schemas/AssignmentError" }, "status": { "type": "string", "description": "Whether the assignment succeeded or failed for this sales package.", "enum": [ "SUCCESS", "FAILED" ], "examples": [ "SUCCESS" ] }, "versionNumber": { "type": "integer", "description": "Version number of the created version. Only present when versionStatus is VERSIONED.", "examples": [ 14 ] }, "versionStatus": { "allOf": [ { "$ref": "#/components/schemas/VersionStatus" }, { "description": "The status of the created sales package version. Only present on success.", "examples": [ "VERSIONED" ] } ] }, "createdVersionId": { "pattern": "^([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx version ID of the newly created sales package version. Only present on success.", "examples": [ "VYG:Version:SP-905ec954-abcd-1234-efgh-567890abcdef" ] }, "salesOfferPackageId": { "pattern": "^([A-Z]{3}):SalesOfferPackage:([0-9A-Za-z_\\-]*)$", "type": "string", "description": "NeTEx ID of the sales package.", "examples": [ "VYG:SalesOfferPackage:07c4332c" ] } } }, "GenericParameterAssignmentGroupingType": { "type": "string", "description": "How multiple GPA parameters should be combined (AND/OR)", "enum": [ "AND", "OR" ] } }, "responses": { "ForbiddenError": { "description": "Forbidden - Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden": { "summary": "Access forbidden", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "detail": "You do not have permission to access this resource.", "status": 403 } } } } } }, "BadRequestError": { "description": "Bad request - Invalid data or schema violation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "schemaViolation": { "summary": "Request does not match schema", "value": { "type": "https://developer.entur.org/errors/bad-request", "title": "Bad Request", "detail": "Field 'name' is required.", "status": 400 } }, "purchaseWindowNotFound": { "summary": "Referenced purchase window not found", "value": { "type": "https://developer.entur.org/errors/bad-request", "title": "Bad Request", "detail": "PurchaseWindow with id 'ENT:PurchaseWindow:120days' not found.", "status": 400 } } } } } }, "UnauthorizedError": { "description": "Unauthorized - Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized": { "summary": "Authentication required", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "detail": "Authentication credentials were missing or invalid.", "status": 401 } } } } } } }, "parameters": { "id": { "name": "id", "in": "path", "description": "The netex ID of the element to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\\-]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:PreassignedFareProduct:001" } } }, "page": { "name": "page", "in": "query", "description": "Zero-based page number. Defaults to 0.", "required": false, "style": "form", "explode": true, "schema": { "minimum": 0, "type": "integer", "default": 0 }, "examples": { "default": { "value": 0 } } }, "size": { "name": "size", "in": "query", "description": "Number of instances per page. Defaults to 100.", "required": false, "style": "form", "explode": true, "schema": { "maximum": 1000, "minimum": 1, "type": "integer", "default": 100 }, "examples": { "default": { "value": 100 } } }, "version": { "name": "version", "in": "path", "description": "The netex ID or sequence number of the version to retrieve", "required": true, "style": "simple", "explode": false, "schema": { "pattern": "^(([A-Z]{3}):Version:([0-9A-Za-z_\\-]*)|[1-9][0-9]*)$", "type": "string" }, "examples": { "default": { "value": "ENT:Version:001" } } }, "ET-Client-Name": { "in": "header", "name": "ET-Client-Name", "description": "\nEntur Client Header.\nIt is required that all consumers identify themselves by using this header.\nEntur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers.\nThe structure of ET-Client-Name should be: `-` for companies, and `-` for individuals.", "schema": { "type": "string" } }, "X-Correlation-Id": { "in": "header", "name": "X-Correlation-Id", "description": "Correlation id", "schema": { "type": "string" } } }, "examples": { "dog": { "summary": "Dog onboard", "value": { "names": [ { "lang": "en-GB", "value": "Dog" }, { "lang": "nb-NO", "value": "Hund" } ], "status": "DRAFT", "vatGroup": "TRANSPORT_AND_TICKETS_VAT", "farePrice": { "amount": 30, "currency": "NOK" }, "startDate": "2025-01-01", "descriptions": [ { "lang": "en-GB", "value": "Bring your dog onboard the train." }, { "lang": "nb-NO", "value": "Ta med hunden din ombord på toget." } ], "conditionsSummary": { "refundable": true, "exchangeable": true, "fareStructureType": "POINT_TO_POINT_FARE" }, "purchaseWindowRef": "EXA:PurchaseWindow:90days", "chargingMomentType": "BEFORE_TRAVEL", "validityParameters": [ { "groupingType": "OR", "validityParameterRefs": [ "EXA:FareZone:A", "EXA:FareZone:B" ], "validityParameterType": "ZONE" } ], "ownerOrganisationId": 1, "supplementProductType": "DOG", "usageValidityPeriodRef": "EXA:UsageValidityPeriod:60minutes", "entitlementRequiredRefs": [ "EXA:EntitlementRequired:StandardTicket" ] } }, "draft": { "summary": "Create a new version in DRAFT", "value": { "id": "EXA:Version:7775e5aa-eb05-4190-9330-25c7f62b0b53", "status": "DRAFT", "startDate": "2025-01-01" } }, "bicycle": { "summary": "Bicycle reservation", "value": { "names": [ { "lang": "en-GB", "value": "Bike reservation" }, { "lang": "nb-NO", "value": "Sykkelreservasjon" } ], "status": "DRAFT", "vatGroup": "TRANSPORT_AND_TICKETS_VAT", "farePrice": { "amount": 200, "currency": "NOK" }, "startDate": "2025-01-01", "descriptions": [ { "lang": "en-GB", "value": "Valid on the given departure and require a valid ticket for traveller who brings the bike." }, { "lang": "nb-NO", "value": "Gyldig på en gitt avgang og krever gyldig billett for den reisende som reiser med sykkel." } ], "conditionsSummary": { "refundable": true, "exchangeable": true, "fareStructureType": "NETWORK_FLAT_FARE" }, "purchaseWindowRef": "EXA:PurchaseWindow:120days", "chargingMomentType": "BEFORE_TRAVEL", "validityParameters": [ { "groupingType": "OR", "validityParameterRefs": [ "EXA:Line:X1" ], "validityParameterType": "LINE" } ], "ownerOrganisationId": 1, "supplementProductType": "BICYCLE", "usageValidityPeriodRef": "EXA:UsageValidityPeriod:DuringTravel", "entitlementRequiredRefs": [ "EXA:EntitlementRequired:SingleTicket", "EXA:EntitlementRequired:PeriodTicket" ] } }, "luggage": { "summary": "Extra luggage", "value": { "names": [ { "lang": "en-GB", "value": "Extra luggage" }, { "lang": "nb-NO", "value": "Ekstra bagasje" } ], "status": "DRAFT", "endDate": "2025-12-31", "vatGroup": "TRANSPORT_AND_TICKETS_VAT", "farePrice": { "amount": 195, "currency": "NOK" }, "startDate": "2025-01-01", "descriptions": [ { "lang": "en-GB", "value": "Bring additional luggage beyond the standard allowance." }, { "lang": "nb-NO", "value": "Ta med ekstra bagasje utover standard bagasjemengde." } ], "conditionsSummary": { "refundable": true, "exchangeable": true, "fareStructureType": "POINT_TO_POINT_FARE" }, "purchaseWindowRef": "EXA:PurchaseWindow:120days", "chargingMomentType": "BEFORE_TRAVEL", "validityParameters": [ { "groupingType": "OR", "validityParameterRefs": [ "EXA:Line:X1" ], "validityParameterType": "LINE" } ], "ownerOrganisationId": 1, "supplementProductType": "EXTRA_LUGGAGE", "usageValidityPeriodRef": "EXA:UsageValidityPeriod:DuringTravel", "entitlementRequiredRefs": [ "EXA:EntitlementRequired:StandardTicket", "EXA:EntitlementRequired:FlexibleTicket" ] } }, "parking": { "summary": "Parking reservation", "value": { "names": [ { "lang": "en-GB", "value": "Parking reservation" }, { "lang": "nb-NO", "value": "Parkeringsreservasjon" } ], "status": "DRAFT", "vatGroup": "TRANSPORT_AND_TICKETS_VAT", "farePrice": { "amount": 400, "currency": "NOK" }, "startDate": "2025-01-01", "privateCode": "123", "descriptions": [ { "lang": "en-GB", "value": "Reserve a parking spot at the station." }, { "lang": "nb-NO", "value": "Reserver parkeringsplass på stasjonen." } ], "conditionsSummary": { "refundable": false, "exchangeable": false, "fareStructureType": "NETWORK_FLAT_FARE" }, "purchaseWindowRef": "EXA:PurchaseWindow:120days", "chargingMomentType": "BEFORE_TRAVEL", "validityParameters": [ { "groupingType": "OR", "validityParameterRefs": [ "NSR:Parking:P01", "NSR:Parking:P02", "NSR:Parking:P03" ], "validityParameterType": "PARKING" } ], "ownerOrganisationId": 47, "supplementProductType": "PARKING", "usageValidityPeriodRef": "EXA:UsageValidityPeriod:30days", "entitlementRequiredRefs": [ "EXA:EntitlementRequired:PeriodTicket30days" ] } }, "upgrade": { "summary": "First class upgrade with entitlement requirement", "value": { "names": [ { "lang": "en-GB", "value": "First Class Upgrade" }, { "lang": "nb-NO", "value": "Oppgradering til 1. klasse" } ], "status": "DRAFT", "vatGroup": "TRANSPORT_AND_TICKETS_VAT", "farePrice": { "amount": 500, "currency": "NOK" }, "startDate": "2025-01-01", "descriptions": [ { "lang": "en-GB", "value": "Valid on the given departure and require a valid ticket." }, { "lang": "nb-NO", "value": "Gyldig på en gitt avgang og krever gyldig billett." } ], "conditionsSummary": { "refundable": false, "exchangeable": false, "fareStructureType": "NETWORK_FLAT_FARE" }, "purchaseWindowRef": "EXA:PurchaseWindow:120days", "chargingMomentType": "BEFORE_TRAVEL", "validityParameters": [ { "groupingType": "OR", "validityParameterRefs": [ "EXA:Line:X1" ], "validityParameterType": "LINE" } ], "ownerOrganisationId": 1, "supplementProductType": "UPGRADE", "usageValidityPeriodRef": "EXA:UsageValidityPeriod:DuringTravel", "entitlementRequiredRefs": [ "EXA:EntitlementRequired:StandardTicket", "EXA:EntitlementRequired:FlexibleTicket" ] } }, "parking-2": { "summary": "Parking reservation response", "value": { "id": "EXA:SupplementProduct:456", "names": [ { "lang": "en-GB", "value": "Parking reservation" }, { "lang": "nb-NO", "value": "Parkeringsreservasjon" } ], "status": "VERSIONED", "vatGroup": "TRANSPORT_AND_TICKETS_VAT", "farePrice": { "amount": 400, "currency": "NOK" }, "startDate": "2025-01-01", "versionId": "EXA:Version:07ce871e-b84d-47c0-99ba-c7fdb5fa4df9", "datasource": { "id": "some-client-system" }, "privateCode": "123", "descriptions": [ { "lang": "en-GB", "value": "Reserve a parking spot at the station." }, { "lang": "nb-NO", "value": "Reserver parkeringsplass på stasjonen." } ], "versionNumber": 1, "conditionsSummary": { "refundable": false, "exchangeable": false, "fareStructureType": "NETWORK_FLAT_FARE" }, "purchaseWindowRef": "EXA:PurchaseWindow:120days", "chargingMomentType": "BEFORE_TRAVEL", "validityParameters": [ { "groupingType": "OR", "validityParameterRefs": [ "NSR:Parking:P01", "NSR:Parking:P02", "NSR:Parking:P03" ], "validityParameterType": "PARKING" } ], "ownerOrganisationId": 47, "supplementProductType": "PARKING", "usageValidityPeriodRef": "EXA:UsageValidityPeriod:30days", "entitlementRequiredRefs": [ "EXA:EntitlementRequired:PeriodTicket30days" ] } }, "published": { "summary": "Successfully published sales package version", "value": { "status": "VERSIONED", "validFrom": "2026-03-18", "versionId": "TOG:Version:SP-b3c4d5e6-abcd-1234-efgh-112233aabbcc", "publishedDate": "2026-03-18T10:30:00Z", "versionNumber": 14, "salesOfferPackageId": "TOG:SalesOfferPackage:a1b2c3d4" } }, "allSuccess": { "summary": "All assignments succeeded", "value": { "results": [ { "status": "SUCCESS", "versionNumber": 14, "versionStatus": "VERSIONED", "createdVersionId": "TOG:Version:SP-b3c4d5e6-abcd-1234-efgh-112233aabbcc", "salesOfferPackageId": "TOG:SalesOfferPackage:a1b2c3d4" } ] } }, "multiStatus": { "summary": "Mixed success and failure response", "value": { "results": [ { "status": "SUCCESS", "versionNumber": 14, "versionStatus": "VERSIONED", "createdVersionId": "TOG:Version:SP-b3c4d5e6-abcd-1234-efgh-112233aabbcc", "salesOfferPackageId": "TOG:SalesOfferPackage:a1b2c3d4" }, { "error": { "code": "NO_AGREEMENT", "message": "Ingen avtale med KYS for denne salgspakka" }, "status": "FAILED", "salesOfferPackageId": "KYS:SalesOfferPackage:q7r8s9" } ] } }, "draftCreated": { "summary": "Draft version created (no version number)", "value": { "results": [ { "status": "SUCCESS", "versionStatus": "DRAFT", "createdVersionId": "TOG:Version:SP-b3c4d5e6-abcd-1234-efgh-112233aabbcc", "salesOfferPackageId": "TOG:SalesOfferPackage:a1b2c3d4" } ] } }, "draftVersion": { "summary": "Draft version", "value": { "id": "EXA:Version:bf4d317a-8e61-49fd-b095-906b79c05872", "status": "DRAFT", "changed": "2025-01-01T10:00:00Z", "created": "2025-01-01T10:00:00Z", "startDate": "2025-01-01" } }, "fareProducts": { "summary": "Fare products on a sales package", "value": [ { "id": "FJO:SupplementProduct:f9e8d7c6", "name": [ { "lang": "nb-NO", "value": "Parkeringsreservasjon" } ], "versionId": "FJO:Version:FP-d7e8f9a0-abcd-1234-efgh-112233aabbcc", "productType": "SUPPLEMENT_PRODUCT" }, { "id": "TOG:PreassignedFareProduct:trainTicket", "name": [ { "lang": "nb-NO", "value": "Togbillett Oslo-Bergen" } ], "versionId": "TOG:Version:FP-x1y-5678", "productType": "PREASSIGNED_FARE_PRODUCT" } ] }, "assignParking": { "summary": "Assign parking supplement to two sales packages", "value": { "fareProductVersionId": "FJO:Version:FP-d7e8f9a0-abcd-1234-efgh-112233aabbcc", "salesOfferPackageIds": [ "TOG:SalesOfferPackage:a1b2c3d4", "KYS:SalesOfferPackage:q7r8s9" ] } }, "assignmentList": { "summary": "List of sales package assignments for a fare product", "value": [ { "fareProductId": "FJO:SupplementProduct:f9e8d7c6", "salesOfferPackageId": "TOG:SalesOfferPackage:a1b2c3d4", "fareProductVersionId": "FJO:Version:FP-d7e8f9a0-abcd-1234-efgh-112233aabbcc", "salesOfferPackageName": [ { "lang": "nb-NO", "value": "Salgspakke tog + parkering" } ] }, { "fareProductId": "FJO:SupplementProduct:f9e8d7c6", "salesOfferPackageId": "KYS:SalesOfferPackage:t4u5v6", "fareProductVersionId": "FJO:Version:FP-d7e8f9a0-abcd-1234-efgh-112233aabbcc", "salesOfferPackageName": [ { "lang": "nb-NO", "value": "Salgspakke buss + parkering" } ] } ] }, "publishVersion": { "summary": "Publish a draft sales package version", "value": { "status": "VERSIONED", "validFrom": "2026-03-18", "versionId": "TOG:Version:SP-b3c4d5e6-abcd-1234-efgh-112233aabbcc" } }, "versionHistory": { "summary": "Example version history", "value": [ { "id": "EXA:Version:853a7d14-794e-4af5-b569-301711a26e26", "number": 1, "status": "VERSIONED", "changed": "2024-12-01T10:00:00Z", "created": "2024-12-01T10:00:00Z", "endDate": "2025-12-31", "published": "2024-12-30T10:00:00Z", "startDate": "2025-01-01" }, { "id": "EXA:Version:e7104d26-16a5-4db5-aa42-b32ae0a3f684", "number": 2, "status": "VERSIONED", "changed": "2025-12-01T10:00:00Z", "created": "2025-12-01T10:00:00Z", "published": "2025-12-01T13:00:00Z", "startDate": "2026-01-01" }, { "id": "EXA:Version:6be856a5-dd98-496b-b3f2-ad9939270ec3", "status": "PROPOSED", "changed": "2026-06-01T10:00:00Z", "created": "2026-06-01T10:00:00Z", "startDate": "2026-07-01" } ] }, "seatReservation": { "summary": "Seat reservation", "value": { "names": [ { "lang": "en-GB", "value": "Seat reservation" }, { "lang": "nb-NO", "value": "Setereservasjon" } ], "status": "DRAFT", "endDate": "2025-12-31", "vatGroup": "TRANSPORT_AND_TICKETS_VAT", "farePrice": { "amount": 50, "currency": "NOK" }, "startDate": "2025-01-01", "descriptions": [ { "lang": "en-GB", "value": "Mandatory seat reservation for all passengers on Bergensbanen." }, { "lang": "nb-NO", "value": "Obligatorisk setereservasjon for alle passasjerer på Bergensbanen." } ], "conditionsSummary": { "refundable": false, "exchangeable": true, "fareStructureType": "NETWORK_FLAT_FARE" }, "purchaseWindowRef": "EXA:PurchaseWindow:120days", "chargingMomentType": "BEFORE_TRAVEL", "validityParameters": [ { "groupingType": "OR", "validityParameterRefs": [ "EXA:Line:X1" ], "validityParameterType": "LINE" } ], "ownerOrganisationId": 1, "supplementProductType": "SEAT_RESERVATION", "usageValidityPeriodRef": "EXA:UsageValidityPeriod:DuringTravel", "entitlementRequiredRefs": [ "EXA:EntitlementRequired:StandardTicket", "EXA:EntitlementRequired:FlexibleTicket" ] } }, "multipleVersions": { "summary": "Supplement product with multiple versions", "value": [ { "id": "EXA:SupplementProduct:456", "versionId": "EXA:Version:SP-abc123-v1" }, { "id": "EXA:SupplementProduct:456", "versionId": "EXA:Version:SP-abc123-v2" }, { "id": "EXA:SupplementProduct:456", "versionId": "EXA:Version:SP-abc123-v3" } ] }, "versionedVersion": { "summary": "Versioned version", "value": { "id": "EXA:Version:d88d0af0-4fe1-4457-a3a6-dbe1db5b3005", "number": 1, "status": "VERSIONED", "changed": "2025-01-01T10:00:00Z", "created": "2025-01-01T10:00:00Z", "endDate": "2025-12-31", "published": "2025-01-15T10:00:00Z", "startDate": "2025-01-01" } }, "withFareProducts": { "summary": "Sales package with fare products", "value": { "id": "TOG:SalesOfferPackage:a1b2c3d4", "name": [ { "lang": "nb-NO", "value": "Salgspakke tog + parkering" } ], "status": "VERSIONED", "validFrom": "2026-03-18", "versionId": "TOG:Version:SP-b3c4d5e6-abcd-1234-efgh-112233aabbcc", "fareProducts": [ { "fareProductId": "TOG:PreassignedFareProduct:trainTicket", "fareProductVersionId": "TOG:Version:FP-x1y-5678", "fareProductVersionNumber": 3 }, { "fareProductId": "FJO:SupplementProduct:f9e8d7c6", "fareProductVersionId": "FJO:Version:FP-d7e8f9a0-abcd-1234-efgh-112233aabbcc", "fareProductVersionNumber": 7 } ], "publishedDate": "2026-03-18T10:30:00Z", "versionNumber": 14, "ownerOrganisationId": 1 } }, "assignParkingAsDraft": { "summary": "Assign parking supplement as draft (requires manual publication)", "value": { "status": "DRAFT", "fareProductVersionId": "FJO:Version:FP-d7e8f9a0-abcd-1234-efgh-112233aabbcc", "salesOfferPackageIds": [ "TOG:SalesOfferPackage:a1b2c3d4" ] } }, "updateWithFareProducts": { "summary": "Update sales package with fare products", "value": { "name": [ { "lang": "nb-NO", "value": "Salgspakke tog + parkering" } ], "status": "VERSIONED", "fareProducts": [ { "fareProductId": "TOG:PreassignedFareProduct:trainTicket", "fareProductVersionId": "TOG:Version:FP-x1y-5678" }, { "fareProductId": "FJO:SupplementProduct:f9e8d7c6", "fareProductVersionId": "FJO:Version:FP-d7e8f9a0-abcd-1234-efgh-112233aabbcc" } ] } } }, "securitySchemes": { "jwt": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } }