{
  "openapi": "3.1.1",
  "info": {
    "title": "Third Party Product - Partner",
    "description": "Third party product is a catalog for products that does not exist in Enturs standard product database.\nTherefore, third party products must be provided by the client when creating an order. This means third party products are always connected to a specific order line within an order.\nThird party products enable selling products from another marketplace, using Entur's payment and order apis, which also includes that the sale is settled correctly in Entur's accounting.",
    "version": "2026.04.0"
  },
  "servers": [
    {
      "url": "https://api.entur.io/sales",
      "description": "production"
    },
    {
      "url": "https://api.staging.entur.io/sales",
      "description": "staging"
    },
    {
      "url": "https://api.dev.entur.io/sales",
      "description": "dev"
    }
  ],
  "security": [
    {
      "jwt": []
    }
  ],
  "tags": [
    {
      "name": "Third Party Products by Order",
      "description": "Get third party products for an order"
    }
  ],
  "paths": {
    "/v1/third-party-products/orders/{orderId}": {
      "get": {
        "tags": [
          "Third Party Products by Order"
        ],
        "summary": "Get third party products for an order",
        "description": "Returns third party products for given orderId",
        "operationId": "getThirdPartyProducts",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "description": "The id of the order.",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThirdPartyProductsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/badRequest"
          },
          "403": {
            "$ref": "#/components/responses/forbidden"
          },
          "404": {
            "$ref": "#/components/responses/notFound"
          },
          "500": {
            "$ref": "#/components/responses/internalServerError"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/ET-Client-Name"
        },
        {
          "$ref": "#/components/parameters/X-Correlation-Id"
        }
      ]
    },
    "/v1/third-party-products/orders/{orderId}/order-lines/{orderLineId}": {
      "get": {
        "tags": [
          "Third Party Products by Order"
        ],
        "summary": "Get specific third party product for an orderLine",
        "description": "Returns third party products for given orderId, orderLineId and orderLineVersion. A Third party product is a product in the system that belongs to an external provider/operator, but is sold or handled through our platform.",
        "operationId": "getThirdPartyProductByOrderLine",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "description": "The id of the order.",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "orderLineId",
            "in": "path",
            "description": "The id of the order line.",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "orderLineVersion",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThirdPartyProduct"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/badRequest"
          },
          "403": {
            "$ref": "#/components/responses/forbidden"
          },
          "404": {
            "$ref": "#/components/responses/notFound"
          },
          "500": {
            "$ref": "#/components/responses/internalServerError"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/ET-Client-Name"
        },
        {
          "$ref": "#/components/parameters/X-Correlation-Id"
        }
      ]
    }
  },
  "components": {
    "schemas": {
      "RefType": {
        "required": [
          "id"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The identifier to distinguish the product",
            "examples": [
              "ENT:ThirdPartyProduct:MyProduct"
            ]
          },
          "version": {
            "type": "string",
            "description": "Version for the id",
            "examples": [
              "ENT:Version:MyProduct-1"
            ]
          }
        },
        "description": "Versioned ID of the product."
      },
      "ApiError": {
        "required": [
          "error",
          "exception",
          "message",
          "path",
          "status",
          "timestamp",
          "title"
        ],
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "description": "Short, human-readable summary of the problem"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "integer",
            "format": "int32"
          },
          "message": {
            "type": "string"
          },
          "exception": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        },
        "examples": [
          {
            "path": "/v1/third-party-products/XYZ123",
            "error": "Bad Request",
            "title": "Bad Request",
            "status": 400,
            "message": "Validation failed",
            "exception": "ValidationException",
            "timestamp": "2025-01-01T12:00:00Z"
          }
        ]
      },
      "Parameters": {
        "title": "Parameters",
        "type": "object",
        "properties": {
          "userProfile": {
            "$ref": "#/components/schemas/UserProfile"
          }
        },
        "description": "Similar to OrderLine.fareProducts.parameters, but with additional fields for third party products."
      },
      "UserProfile": {
        "title": "UserProfile",
        "required": [
          "name",
          "userProfileRef"
        ],
        "type": "object",
        "properties": {
          "name": {
            "minItems": 1,
            "uniqueItems": true,
            "type": "array",
            "description": "A human-readable list of names for the product",
            "items": {
              "$ref": "#/components/schemas/TextInLanguage"
            }
          },
          "price": {
            "$ref": "#/components/schemas/PriceWithTax"
          },
          "userProfileRef": {
            "$ref": "#/components/schemas/RefType"
          },
          "priceContribution": {
            "$ref": "#/components/schemas/PriceWithTax"
          }
        },
        "description": ""
      },
      "PriceWithTax": {
        "title": "PriceWithTax",
        "required": [
          "amount",
          "currency",
          "taxAmount"
        ],
        "type": "object",
        "properties": {
          "amount": {
            "type": "string",
            "description": "Amount including tax amount.",
            "examples": [
              "399"
            ]
          },
          "taxCode": {
            "type": "string",
            "description": "Tax code for this tax rate",
            "examples": [
              "12"
            ]
          },
          "taxRate": {
            "type": "string",
            "description": "Tax rate",
            "examples": [
              "12"
            ]
          },
          "currency": {
            "type": "string",
            "description": "Currency",
            "default": "NOK",
            "examples": [
              "NOK"
            ]
          },
          "taxAmount": {
            "type": "string",
            "description": "Tax amount",
            "examples": [
              "36.27"
            ]
          }
        },
        "description": "Price with included tax amounts and an optional rate."
      },
      "TextInLanguage": {
        "required": [
          "lang",
          "value"
        ],
        "type": "object",
        "properties": {
          "lang": {
            "type": "string",
            "description": "The language of the text"
          },
          "value": {
            "type": "string",
            "description": "The value of the text in the given language"
          }
        },
        "description": "Contains a text value in a given language",
        "x-examples": {
          "example-1": {
            "lang": "nob",
            "value": "Bergen Stasjon"
          }
        }
      },
      "ThirdPartyProduct": {
        "required": [
          "name",
          "orderId",
          "orderLineId",
          "orderLineVersion",
          "orderVersion",
          "parameters",
          "price",
          "priceContribution",
          "productRef"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "array",
            "description": "A human-readable list of names for the product",
            "items": {
              "$ref": "#/components/schemas/TextInLanguage"
            }
          },
          "price": {
            "$ref": "#/components/schemas/PriceWithTax"
          },
          "orderId": {
            "type": "string",
            "description": "The orderId for which the product belongs to."
          },
          "parameters": {
            "$ref": "#/components/schemas/Parameters"
          },
          "productRef": {
            "$ref": "#/components/schemas/RefType"
          },
          "authorityId": {
            "type": "string",
            "description": "Owner of the product."
          },
          "orderLineId": {
            "type": "string",
            "description": "The orderLineId for which the product belongs to."
          },
          "orderVersion": {
            "type": "integer",
            "description": "The version of the order for which the product belongs to."
          },
          "orderLineVersion": {
            "type": "integer",
            "description": "The version of the order line for which the product belongs to."
          },
          "priceContribution": {
            "$ref": "#/components/schemas/PriceWithTax"
          }
        },
        "description": "A third party product for given order and order line.",
        "examples": [
          {
            "name": [
              {
                "lang": "eng",
                "value": "Wayfare luggage space reservation"
              },
              {
                "lang": "nob",
                "value": "Wayfare bagasjeplassreservasjon"
              }
            ],
            "price": {
              "amount": "59.00",
              "taxCode": "03",
              "taxRate": "25.00",
              "currency": "NOK",
              "taxAmount": "11.80"
            },
            "orderId": "WAYFARE-ORDER-98765",
            "parameters": {},
            "productRef": {
              "id": "WAYFARE:ThirdPartyProduct:LuggageReservation",
              "version": "WAYFARE:Version:LuggageReservation-1"
            },
            "authorityId": "WAYFARE:Authority:WAYFARE",
            "orderLineId": "WAYFARE-ORDERLINE-2",
            "orderVersion": 1,
            "orderLineVersion": 1,
            "priceContribution": {
              "amount": "59.00",
              "taxCode": "03",
              "taxRate": "25.00",
              "currency": "NOK",
              "taxAmount": "11.80"
            }
          }
        ]
      },
      "ThirdPartyProductsResponse": {
        "required": [
          "thirdPartyProducts"
        ],
        "type": "object",
        "properties": {
          "thirdPartyProducts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThirdPartyProduct"
            }
          }
        },
        "description": "Response containing third party products.",
        "examples": [
          {
            "thirdPartyProducts": [
              {
                "name": [
                  {
                    "lang": "eng",
                    "value": "Wayfare luggage space reservation"
                  },
                  {
                    "lang": "nob",
                    "value": "Wayfare bagasjeplassreservasjon"
                  }
                ],
                "price": {
                  "amount": "59.00",
                  "taxCode": "03",
                  "taxRate": "25.00",
                  "currency": "NOK",
                  "taxAmount": "11.80"
                },
                "orderId": "WAYFARE-ORDER-98765",
                "parameters": {},
                "productRef": {
                  "id": "WAYFARE:ThirdPartyProduct:LuggageReservation",
                  "version": "WAYFARE:Version:LuggageReservation-1"
                },
                "authorityId": "WAYFARE:Authority:WAYFARE",
                "orderLineId": "WAYFARE-ORDERLINE-2",
                "orderVersion": 1,
                "orderLineVersion": 1,
                "priceContribution": {
                  "amount": "59.00",
                  "taxCode": "03",
                  "taxRate": "25.00",
                  "currency": "NOK",
                  "taxAmount": "11.80"
                }
              }
            ]
          }
        ]
      }
    },
    "responses": {
      "notFound": {
        "description": "Not Found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "examples": {
              "default": {
                "value": {
                  "path": "/v1/third-party-products/XYZ123",
                  "error": "Not Found",
                  "title": "Not Found",
                  "status": 404,
                  "message": "Entity not found",
                  "exception": "EntityNotFoundException",
                  "timestamp": "2025-01-01T12:00:00Z"
                }
              }
            }
          }
        }
      },
      "forbidden": {
        "description": "Forbidden",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "examples": {
              "default": {
                "value": {
                  "path": "/v1/third-party-products/XYZ123",
                  "error": "Forbidden",
                  "title": "Forbidden",
                  "status": 403,
                  "message": "Access denied",
                  "exception": "AccessDeniedException",
                  "timestamp": "2025-01-01T12:00:00Z"
                }
              }
            }
          }
        }
      },
      "badRequest": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "examples": {
              "default": {
                "value": {
                  "path": "/v1/third-party-products/XYZ123",
                  "error": "Bad Request",
                  "title": "Bad Request",
                  "status": 400,
                  "message": "Validation failed",
                  "exception": "ValidationException",
                  "timestamp": "2025-01-01T12:00:00Z"
                }
              }
            }
          }
        }
      },
      "internalServerError": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "examples": {
              "default": {
                "value": {
                  "path": "/v1/third-party-products/XYZ123",
                  "error": "Internal Server Error",
                  "title": "Internal Server Error",
                  "status": 500,
                  "message": "An unexpected error occurred",
                  "exception": "RuntimeException",
                  "timestamp": "2025-01-01T12:00:00Z"
                }
              }
            }
          }
        }
      }
    },
    "parameters": {
      "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: `<company>-<application>` for companies, and `<personal name>-<application>` for individuals.",
        "schema": {
          "type": "string"
        }
      },
      "X-Correlation-Id": {
        "in": "header",
        "name": "X-Correlation-Id",
        "description": "Correlation id",
        "schema": {
          "type": "string"
        }
      }
    },
    "securitySchemes": {
      "jwt": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}