{
  "openapi": "3.1.0",
  "info": {
    "title": "ABT Integration Entur API",
    "description": "Internal api specification for Entur integration module for ABT",
    "termsOfService": "https://developer.entur.no/terms-of-service",
    "version": "2026.10.1"
  },
  "servers": [
    {
      "url": "https://abt-integration-entur-production.entur.io/"
    }
  ],
  "tags": [
    {
      "name": "Internal",
      "description": "ABT Integration Entur Internal API"
    },
    {
      "name": "Fare Contracts",
      "description": "ABT Integration Entur Fare Contracts API"
    }
  ],
  "paths": {
    "/v1/fare-contracts/orders/{orderId}": {
      "post": {
        "tags": [
          "Fare Contracts"
        ],
        "summary": "Add or update fare contracts for an order",
        "description": "Triggers distribution of an order to ABT, creating or updating fare contracts. If the fare contract already exists, no duplicate will be created.",
        "operationId": "distribute",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "description": "orderId to add/update fare contract for.",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FareContractRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FareContractResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/internalServerError"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/ET-Client-Name"
        },
        {
          "$ref": "#/components/parameters/X-Correlation-Id"
        }
      ]
    },
    "/v1/customer-accounts/{customerAccountId}/transfer": {
      "post": {
        "tags": [
          "Internal"
        ],
        "summary": "Transfer CPPs of a fare contract to other customer accounts.",
        "description": "Transfer customer purchase packages within a fare contract to other customer accounts.",
        "operationId": "transfer",
        "parameters": [
          {
            "name": "customerAccountId",
            "in": "path",
            "description": "From Customer Account ID",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransferRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/internalServerError"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/ET-Client-Name"
        },
        {
          "$ref": "#/components/parameters/X-Correlation-Id"
        }
      ]
    },
    "/v1/customer-accounts/{customerAccountId}/update-validity": {
      "post": {
        "tags": [
          "Internal"
        ],
        "summary": "Update validity for CPP element accesses of fare contracts",
        "description": "Update to new start- and end of validity on customer purchase package element accesses within a fare contract.",
        "operationId": "updateValidity",
        "parameters": [
          {
            "name": "customerAccountId",
            "in": "path",
            "description": "Customer Account ID",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateValidityRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateValidityResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/internalServerError"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/ET-Client-Name"
        },
        {
          "$ref": "#/components/parameters/X-Correlation-Id"
        }
      ]
    },
    "/v1/customer-accounts/{customerAccountId}/fare-contracts/{fareContractId}/consume": {
      "post": {
        "tags": [
          "Internal"
        ],
        "summary": "Consume one access right of a fare contract",
        "description": "Consumes (activates) one of the consumable customer purchase package elements of a fare contract, e.g. one clip of a carnet (klippekort). Consumption is done with activation means USE_OF_MOBILE_DEVICE.",
        "operationId": "consume",
        "parameters": [
          {
            "name": "customerAccountId",
            "in": "path",
            "description": "Customer Account ID",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fareContractId",
            "in": "path",
            "description": "Fare Contract ID",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsumeFareContractRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsumeFareContractResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/notFound"
          },
          "409": {
            "$ref": "#/components/responses/conflict"
          },
          "500": {
            "$ref": "#/components/responses/internalServerError"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/ET-Client-Name"
        },
        {
          "$ref": "#/components/parameters/X-Correlation-Id"
        }
      ]
    }
  },
  "components": {
    "schemas": {
      "TransferRequest": {
        "type": "object",
        "properties": {
          "fareContractTransfers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FareContractTransfer"
            },
            "minItems": 1,
            "uniqueItems": true
          }
        },
        "required": [
          "fareContractTransfers"
        ]
      },
      "FareContractTransfer": {
        "type": "object",
        "description": "Specifies the whole or parts of fare contract to be transferred to other accounts.",
        "properties": {
          "fareContractId": {
            "type": "string"
          },
          "customerPurchasePackagesTransfers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomerPurchasePackageTransfer"
            },
            "minItems": 1,
            "uniqueItems": true
          }
        },
        "required": [
          "customerPurchasePackagesTransfers",
          "fareContractId"
        ]
      },
      "CustomerPurchasePackageTransfer": {
        "type": "object",
        "description": "Request with order line referencing customer purchase package to be transferred to other account.",
        "properties": {
          "toCustomerAccountId": {
            "type": "string"
          },
          "orderLineId": {
            "type": "string"
          }
        },
        "required": [
          "orderLineId",
          "toCustomerAccountId"
        ]
      },
      "TransferResponse": {
        "type": "object",
        "properties": {
          "successfulTransfers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SuccessfulCustomerPurchasePackageTransfer"
            }
          },
          "failedTransfers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FailedCustomerPurchasePackageTransfer"
            }
          }
        },
        "required": [
          "failedTransfers",
          "successfulTransfers"
        ]
      },
      "SuccessfulCustomerPurchasePackageTransfer": {
        "type": "object",
        "description": "Successful transfer of customer purchase package (given by orderLineId) to new fare contract and customer account.",
        "properties": {
          "toCustomerAccountId": {
            "type": "string"
          },
          "orderLineId": {
            "type": "string"
          },
          "newFareContractId": {
            "type": "string"
          }
        },
        "required": [
          "newFareContractId",
          "orderLineId",
          "toCustomerAccountId"
        ]
      },
      "FailedCustomerPurchasePackageTransfer": {
        "type": "object",
        "description": "Failed transfer of customer purchase package (given by orderLineId) along with reason of failure.",
        "properties": {
          "toCustomerAccountId": {
            "type": "string"
          },
          "orderLineId": {
            "type": "string"
          },
          "errorMessage": {
            "type": "string"
          }
        },
        "required": [
          "errorMessage",
          "orderLineId",
          "toCustomerAccountId"
        ]
      },
      "ConsumeFareContractRequest": {
        "type": "object",
        "properties": {
          "validableElementId": {
            "type": "string",
            "description": "elementId on validableElement in context of an order. Identifies which customer purchase package element (e.g. which klippekort) to consume, as a fare contract may contain several."
          }
        },
        "required": [
          "validableElementId"
        ]
      },
      "ConsumeFareContractResponse": {
        "type": "object",
        "properties": {
          "fareContractRef": {
            "type": "string"
          },
          "consumedElementAccesses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsumedElementAccess"
            }
          },
          "remainingNumberOfAccesses": {
            "type": "integer",
            "format": "int32",
            "description": "Number of accesses left on the consumed element after this consumption. Not set if the number of accesses is unlimited or unknown."
          }
        },
        "required": [
          "consumedElementAccesses",
          "fareContractRef"
        ]
      },
      "ConsumedElementAccess": {
        "type": "object",
        "description": "Customer purchase package element access created by the consumption.",
        "properties": {
          "elementAccessId": {
            "type": "string"
          },
          "customerPurchasePackageElementRef": {
            "type": "string"
          },
          "startOfValidity": {
            "type": "string",
            "format": "date-time"
          },
          "endOfValidity": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "customerPurchasePackageElementRef",
          "elementAccessId"
        ]
      },
      "UpdateValidityRequest": {
        "type": "object",
        "properties": {
          "fareContractUpdates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FareContractValidityUpdate"
            },
            "minItems": 1,
            "uniqueItems": true
          }
        },
        "required": [
          "fareContractUpdates"
        ]
      },
      "FareContractValidityUpdate": {
        "type": "object",
        "description": "Specifies the parts of fare contract to update validity",
        "properties": {
          "fareContractId": {
            "type": "string"
          },
          "customerPurchasePackagesValidityUpdates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomerPurchasePackageValidityUpdate"
            },
            "minItems": 1,
            "uniqueItems": true
          }
        },
        "required": [
          "customerPurchasePackagesValidityUpdates",
          "fareContractId"
        ]
      },
      "CustomerPurchasePackageValidityUpdate": {
        "type": "object",
        "description": "Request with order line referencing customer purchase package to update validity for.",
        "properties": {
          "orderLineId": {
            "type": "string"
          },
          "customerPurchasePackageElementValidityUpdate": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomerPurchasePackageElementValidityUpdate"
            },
            "minItems": 1,
            "uniqueItems": true
          }
        },
        "required": [
          "customerPurchasePackageElementValidityUpdate",
          "orderLineId"
        ]
      },
      "CustomerPurchasePackageElementValidityUpdate": {
        "type": "object",
        "description": "Request with validable element (elementId on order) referencing customer purchase package element to update validity for.",
        "properties": {
          "validableElementId": {
            "type": "string",
            "description": "elementId on validableElement in context of an order."
          },
          "startOfValidity": {
            "type": "string",
            "format": "date-time"
          },
          "endOfValidity": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "endOfValidity",
          "startOfValidity",
          "validableElementId"
        ]
      },
      "UpdateValidityResponse": {
        "type": "object",
        "properties": {
          "successfulValidityUpdates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SuccessfulCustomerPurchasePackageValidityUpdate"
            }
          },
          "failedValidityUpdates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FailedCustomerPurchasePackageValidityUpdate"
            }
          }
        },
        "required": [
          "failedValidityUpdates",
          "successfulValidityUpdates"
        ]
      },
      "SuccessfulCustomerPurchasePackageValidityUpdate": {
        "type": "object",
        "description": "Successful validity update of customer purchase package (given by orderLineId) to new fare contract and customer account.",
        "properties": {
          "orderLineId": {
            "type": "string"
          }
        },
        "required": [
          "orderLineId"
        ]
      },
      "FailedCustomerPurchasePackageValidityUpdate": {
        "type": "object",
        "description": "Failed update validity of customer purchase package (given by orderLineId) along with reason of failure.",
        "properties": {
          "orderLineId": {
            "type": "string"
          },
          "errorMessage": {
            "type": "string"
          }
        },
        "required": [
          "errorMessage",
          "orderLineId"
        ]
      },
      "FareContractRequest": {
        "type": "object",
        "description": "Request to add/update fare contracts for an order to ABT.",
        "properties": {
          "orderVersion": {
            "type": "integer",
            "format": "int32",
            "description": "The version of the order to distribute."
          }
        },
        "required": [
          "orderVersion"
        ]
      },
      "FareContractResponse": {
        "type": "object",
        "description": "Response from adding/updating fare contracts in ABT for an order.",
        "properties": {
          "orderId": {
            "type": "string",
            "description": "The order ID that fare contract was added/updated for."
          },
          "orderVersion": {
            "type": "integer",
            "format": "int32",
            "description": "The version of the order that fare contract was added/updated for."
          },
          "successfulDistributions": {
            "type": "array",
            "description": "Fare contracts that were successfully added/updated.",
            "items": {
              "$ref": "#/components/schemas/SuccessfulFareContract"
            }
          },
          "failedDistributions": {
            "type": "array",
            "description": "Customer accounts for which distribution failed.",
            "items": {
              "$ref": "#/components/schemas/FailedFareContract"
            }
          }
        },
        "required": [
          "failedDistributions",
          "orderId",
          "orderVersion",
          "successfulDistributions"
        ]
      },
      "FailedFareContract": {
        "type": "object",
        "description": "A failed fare contract that was rejected by ABT along with the reason.",
        "properties": {
          "customerAccountRef": {
            "type": "string",
            "description": "The customer account the fare contract was attempted to be added/updated to."
          },
          "orderLineIds": {
            "type": "array",
            "description": "The order line IDs that failed.",
            "items": {
              "type": "string"
            }
          },
          "errorMessage": {
            "type": "string",
            "description": "Description of why the fare contract was rejected by ABT."
          }
        },
        "required": [
          "customerAccountRef",
          "errorMessage",
          "orderLineIds"
        ]
      },
      "SuccessfulFareContract": {
        "type": "object",
        "description": "A fare contract that was added/updated.",
        "properties": {
          "customerAccountRef": {
            "type": "string"
          },
          "fareContractRef": {
            "type": "string"
          },
          "travelDocumentIssuedRef": {
            "type": "string",
            "description": "Reference to a new travel document (token) issued for the fare contract."
          },
          "travelDocumentAttachedRef": {
            "type": "string",
            "description": "Reference to an existing travel document (token) attached to the fare contract."
          },
          "orderLineIds": {
            "type": "array",
            "description": "The order line IDs that were added/updated in the fare contract.",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "customerAccountRef",
          "fareContractRef"
        ]
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": "integer",
            "format": "int32"
          },
          "error": {
            "type": "string"
          },
          "exception": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "path": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "exception",
          "message",
          "path",
          "status",
          "timestamp"
        ],
        "title": "ApiError"
      }
    },
    "responses": {
      "noContent": {
        "description": "No Content"
      },
      "badRequest": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "conflict": {
        "description": "Conflict",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "forbidden": {
        "description": "Forbidden",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "notFound": {
        "description": "Not Found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "internalServerError": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "serviceUnavailable": {
        "description": "Service unavailable",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    },
    "parameters": {
      "ET-Client-Name": {
        "name": "ET-Client-Name",
        "in": "header",
        "description": "Entur 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>`.",
        "required": false,
        "style": "simple",
        "explode": false,
        "schema": {
          "type": "string"
        }
      },
      "X-Correlation-Id": {
        "name": "X-Correlation-Id",
        "in": "header",
        "description": "Correlation id",
        "required": false,
        "style": "simple",
        "explode": false,
        "schema": {
          "type": "string"
        }
      }
    }
  }
}