{ "openapi": "3.1.1", "info": { "title": "Receipt Partner", "description": "Public API for generating and delivering receipts for customer orders. Provides endpoints to send receipts, determine the resulting receipt type for an order, and retrieve pickup-code messages in multiple formats and languages.\n", "termsOfService": "https://developer.entur.org/pages-intro-setup-and-access", "contact": { "name": "Entur Team Salg", "url": "https://www.entur.org", "email": "team.salg@entur.org" }, "license": { "name": "Proprietary" }, "version": "2026.06.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": "Partner Receipts", "description": "Create, send, and query receipts" } ], "paths": { "/v1/receipts/send": { "post": { "tags": [ "Partner Receipts" ], "summary": "Send receipt", "description": "Send a receipt. Content will be defined by order ID and version of order. Receipts can only be made for orderVersions where there been a payment or a credit.", "operationId": "sendReceipt", "parameters": [ { "name": "organisationId", "in": "query", "description": "", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "receiptType", "in": "query", "description": "Overwrite receipt type if present", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "enum": [ "SALE", "REFUND", "CANCEL", "CHANGE" ] } } ], "requestBody": { "description": "A send receipt request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendReceiptRequest" }, "examples": { "default": { "value": { "orderId": "2H1K65IM", "copyReceipt": false, "distribution": { "email": "customer@example.com", "telephone": { "number": "61051910", "countryCode": "47" } }, "orderVersion": 1, "serialNumber": "RCP-2024-000123", "receiptLanguage": "nob" } } } } }, "required": true }, "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserReceiptResponse" }, "examples": { "default": { "value": { "reference": "a49f7259-7285-42ce-b7b0-e48a77fbfb39" } } } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/notFound" }, "409": { "$ref": "#/components/responses/conflict" }, "500": { "$ref": "#/components/responses/internalServerError" } }, "deprecated": false }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/receipts/type": { "get": { "tags": [ "Partner Receipts" ], "summary": "Get receipt type", "description": "Returns the type of receipt a combination of order ID and version will result in.", "operationId": "getReceiptType", "parameters": [ { "name": "orderId", "in": "query", "description": "Filters by order ID", "required": true, "style": "form", "explode": true, "schema": { "type": "string" }, "examples": { "default": { "value": "S1P87KKP" } } }, { "name": "orderVersion", "in": "query", "description": "Filters by order version", "required": true, "style": "form", "explode": true, "schema": { "type": "string" }, "examples": { "default": { "value": "1" } } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptTypeResponse" }, "examples": { "default": { "value": { "receiptType": "SALE" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/internalServerError" } }, "deprecated": false }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1/receipts/pickup-code-message/{orderId}": { "get": { "tags": [ "Partner Receipts" ], "summary": "Get pickup code message", "description": "Get the text used for pickup code message for an order in given language to send as message to the customer.", "operationId": "getPickupCodeMessage", "parameters": [ { "name": "orderId", "in": "path", "description": "Order id to generate pickup code message for", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" }, "examples": { "default": { "value": "ABDC1234" } } }, { "name": "orderVersion", "in": "query", "description": "Which version of the order that should be used to generate a summary", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int32" }, "examples": { "default": { "value": 1 } } }, { "name": "language", "in": "query", "description": "Desired language of the message. Currently supporting 'nob', 'nno' and 'eng'", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "default": "nob" }, "examples": { "default": { "value": "nob" } } } ], "responses": { "200": { "description": "Ok", "content": { "text/html": { "schema": { "type": "string" }, "examples": { "default": { "value": "

Pickup code: AB12CD
Show this code and a valid ID when boarding.

" } } }, "application/json": { "schema": { "type": "string" }, "examples": { "default": { "value": "Pickup code: AB12CD. Show this code and a valid ID when boarding." } } } } }, "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": { "ApiError": { "title": "ApiError", "required": [ "error", "exception", "message", "path", "status", "timestamp" ], "type": "object", "properties": { "path": { "type": "string" }, "error": { "type": "string" }, "title": { "type": "string", "description": "Short, human-readable summary of the problem" }, "status": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "exception": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } }, "Telephone": { "title": "Telephone", "required": [ "countryCode", "number" ], "type": "object", "properties": { "number": { "type": "string", "description": "Phone number", "examples": [ "61051910" ] }, "countryCode": { "type": "string", "description": "Country code", "examples": [ "47" ] } }, "description": "Telephone model for distribution" }, "ReceiptType": { "type": "string", "description": "Type of receipt", "enum": [ "SALE", "REFUND", "CANCEL", "CHANGE", "DAY_SUMMARY" ], "examples": [ "SALE" ] }, "Distribution": { "title": "Distribution", "type": "object", "properties": { "email": { "type": "string", "description": "Email to receive receipt", "examples": [ "example@entur.org" ] }, "telephone": { "$ref": "#/components/schemas/Telephone" } }, "description": "Request for sending a receipt to a customer using one or more distribution methods. Will only send email if both email and telephone are provided. To send sms, leave email as null." }, "SendReceiptRequest": { "title": "SendReceiptRequest", "required": [ "distribution", "orderId", "orderVersion" ], "type": "object", "properties": { "orderId": { "type": "string", "description": "Order id to generate receipt", "examples": [ "1234567890" ] }, "copyReceipt": { "type": "boolean", "description": "Set to true when the receipt is a copy." }, "distribution": { "$ref": "#/components/schemas/Distribution" }, "orderVersion": { "type": "integer", "description": "Which version of the order that should be used to generate a receipt", "format": "int32", "examples": [ 1 ] }, "serialNumber": { "type": "string", "description": "The desired serial number for the receipt" }, "receiptLanguage": { "type": "string", "description": "Desired language of the receipt. Currently only supporting 'nob' and 'eng'", "default": "nob", "examples": [ "nob" ] } }, "description": "Request for sending a sale receipt to a customer using one or more distribution methods", "examples": [ { "orderId": "2H1K65IM", "copyReceipt": false, "distribution": { "email": "customer@example.com", "telephone": { "number": "61051910", "countryCode": "47" } }, "orderVersion": 1, "serialNumber": "RCP-2024-000123", "receiptLanguage": "nob" } ] }, "ReceiptTypeResponse": { "title": "ReceiptTypeResponse", "type": "object", "properties": { "receiptType": { "$ref": "#/components/schemas/ReceiptType" } }, "description": "Response from a successful type query." }, "UserReceiptResponse": { "title": "UserReceiptResponse", "required": [ "reference" ], "type": "object", "properties": { "reference": { "type": "string", "description": "Reference to receipt", "examples": [ "a49f7259-7285-42ce-b7b0-e48a77fbfb39" ] } }, "description": "Response from a accepted receipt request." } }, "responses": { "conflict": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "default": { "value": { "path": "/v1/receipts/1/versions", "error": "Conflict", "title": "Conflict", "status": 409, "message": "Receipt with ID 1 and organisation ID 1 is disabled.", "exception": "ConflictException", "timestamp": "2025-11-13T10:15:30+01:00" } } } } } }, "notFound": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "default": { "value": { "path": "/v1/receipts/1/latest-version", "error": "Not Found", "title": "Not Found", "status": 404, "message": "This receipt does not have any versions", "exception": "NotFoundException", "timestamp": "2025-11-13T10:15:30+01:00" } } } } } }, "forbidden": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "default": { "value": { "path": "/v1/receipts?organisationId=1", "error": "Forbidden", "title": "Forbidden", "status": 403, "message": "The request requires higher privileges than provided by the access token.", "exception": "ForbiddenException", "timestamp": "2025-11-13T10:15:30+01:00" } } } } } }, "badRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "default": { "value": { "path": "/v1/receipts", "error": "Bad Request", "title": "Bad Request", "status": 400, "message": "Required parameter 'orderId' is not present.", "exception": "BAD_REQUEST", "timestamp": "2025-11-13T10:15:30+01:00" } } } } } }, "internalServerError": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "default": { "value": { "path": "/v1/receipts/render-version", "error": "Internal Server Error", "title": "Internal Server Error", "status": 500, "message": "Unexpected error while rendering receipt template", "exception": "InternalServerException", "timestamp": "2025-11-13T10:15:30+01:00" } } } } } } }, "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: `-` for companies, and `-` 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" } } } }