{ "openapi": "3.1.0", "info": { "title": "Clearing", "description": "Partner API documentation for self serviced use of the Clearing services. See the developer guide for more information.", "contact": { "name": "Team Avregning" }, "version": "2026.06.0" }, "externalDocs": { "description": "Clearing Partner API Developer Guide", "url": "https://beta.developer.entur.no/partner/api/clearing/openapi-partner" }, "servers": [ { "url": "https://api.entur.io/clearing" }, { "url": "https://api.staging.entur.io/clearing" }, { "url": "https://api.dev.entur.io/clearing" } ], "security": [ { "bearerToken": [] } ], "tags": [ { "name": "Incoming Settlements", "description": "Create and manage settlements to be cleared by CLEOS" } ], "paths": { "/v1beta/settlement-import/{id}": { "get": { "tags": [ "Incoming Settlements" ], "summary": "Get a settlement by id.", "description": "Get the details of a settlement to see its status or any errors that occurred during clearing.", "operationId": "getSettlementImport", "parameters": [ { "name": "id", "in": "path", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerSettlementImportResponseDto" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CleosProblemJsonDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CleosProblemJsonDto" } } } }, "403": { "description": "No access to incoming settlement", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CleosProblemJsonDto" } } } }, "404": { "description": "Incoming settlement not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CleosProblemJsonDto" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CleosProblemJsonDto" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CleosProblemJsonDto" } } } } }, "x-entur-permissions": { "value": "cleos-settlements:opprett" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/v1beta/settlement-import/generic": { "post": { "tags": [ "Incoming Settlements" ], "summary": "Submit a Generic Settlement for asynchronous clearing. Read the Developer Guide before using.", "description": "Creates a GenericSettlementImport, in queue for for clearing. Use the returned result for further queries based on the assigned ID", "operationId": "importGenericSettlement", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerSettlementImportDto" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerSettlementImportResponseDto" } } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CleosProblemJsonDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CleosProblemJsonDto" } } } }, "403": { "description": "No access to settlement", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CleosProblemJsonDto" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CleosProblemJsonDto" } } } }, "409": { "description": "Conflict due to business rules, eg duplicate settlement", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CleosProblemJsonDto" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CleosProblemJsonDto" } } } } }, "x-entur-permissions": { "value": "cleos-settlements:opprett" }, "parameters": [] }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] } }, "components": { "schemas": { "PartnerRefDto": { "type": "object", "description": "A REF is a reference that is intended for business logic use, with best effort NAME lookups in GUI and reporting. For most practical purposes it can be considered a URN on the format NAMESPACE:TYPE:ID, but this is not guaranteed.", "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 0 }, "name": { "type": "string", "description": "The NAME corresponding to the REF, if found in the CLEOS REF lookup table (best effort). NOTE: This may be set for REFs returned by CLEOS, the client is not expected to submit this value." } }, "required": [ "id" ] }, "PartnerAnnexDto": { "type": "object", "description": "Generic representation of a node in a recursive transaction tree structure.", "properties": { "guid": { "type": "string", "maxLength": 38, "minLength": 0 }, "price": { "$ref": "#/components/schemas/PartnerMoneyDto", "description": "PriceContribution may be provided if a custom weight on Price is needed. The Amount will always be recalculated as the sum of PriceContributions." }, "cancel": { "type": "boolean", "description": "If true, this annex root (and all sub-annexes) will be accounted with DEBED/CREDIT switched. Typically used for reversing older versions of the transaction. Default false." }, "context": { "type": "object", "additionalProperties": {} }, "annexRef": { "type": "string", "maxLength": 50, "minLength": 0 }, "attributes": { "type": "object", "additionalProperties": { "type": "string" } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerAnnexDto" } }, "subAnnexes": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerAnnexDto" } }, "description": { "type": "string", "maxLength": 500, "minLength": 0 }, "foreignAmount": { "$ref": "#/components/schemas/PartnerMoneyDto" }, "priceContribution": { "$ref": "#/components/schemas/PartnerMoneyDto" } }, "required": [ "annexRef", "priceContribution" ] }, "PartnerMoneyDto": { "type": "object", "description": "Representation of an amount with relevant metadata such as currency and tax information. The Annex will be considered without Price Contribution if amount is 0.00", "properties": { "amount": { "type": "string", "description": "The monetary amount in a 12.2 format (up to 12 digits before decimal, exactly 2 after)", "example": "\"12345.34\"", "pattern": "^\\d{1,12}\\.\\d{2}$" }, "weight": { "type": "string", "description": "The weight associated with the amount, if any, in a 12.4 format (up to 12 digits before decimal, optionally followed by 1-4 after). Thw weight is used for proportional clearing based a custom weight instead of PriceContributions. For example representing distance or time.", "example": "\"1500.1234\"", "pattern": "^\\d{1,12}(\\.\\d{1,4})?$" }, "taxCode": { "type": "string", "description": "The standard tax code applicable to the amount, if any", "example": "\"25\"" }, "taxRate": { "type": "string", "description": "The tax rate applicable to the amount, if any. NOTE: This must be consistent with the CLEOS configuration for the Tax Code (SEGMENT7)", "example": "\"12.00\"", "pattern": "^\\d{1,2}(\\.\\d{1,2})?$" }, "currency": { "type": "string", "description": "The currency of the amount in ISO 4217 format. Default NOK if not provided", "example": "NOK" }, "localTaxCode": { "type": "string", "description": "The local tax code applicable to the amount, if any. NOTE: This is normally not necessary to set but may be relevant in scenarios where the tax rate for a code changes", "example": "25A" } }, "required": [ "amount" ] }, "PartnerCommentDto": { "type": "object", "description": "Any external comments relevant for clearing the settlement. This will not be part of the reporting context. Useful for guiding potential corrections.", "properties": { "comment": { "type": "string", "maxLength": 500, "minLength": 0 } }, "required": [ "comment" ] }, "CleosProblemJsonDto": { "type": "object", "description": "DTO representing the generic response of an error condition according to the JSON+ERROR content type (RFC 9457).", "properties": { "type": { "type": "string", "format": "uri", "description": "URI identifying the type of problem. NOTE: type about:blank may still be used for general errors.", "enum": [ "about:blank", "urn:problem-type:cleos-default", "urn:problem-type:cleos-ref" ], "example": "urn:problem-type:cleos-default" }, "title": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer", "format": "int32" }, "instance": { "type": "string", "format": "uri", "description": "Absolute URI to the the resource causing the error. Note that this is technically not a reference to the persistent error _instance_, but still useful default behaviour.", "example": "https://api.entur.io/clearing/v1/resource/123" }, "timestamp": { "type": "string", "format": "date-time", "description": "Server side timestamp of incident, used by cleos problem-types", "example": "2024-06-17T12:35:53.932Z" }, "domainRefs": { "type": "array", "description": "Domain object references that caused the error on problem type cleos-ref. NOTE: These _may_ be references to entities outside of CLEOS", "items": { "$ref": "#/components/schemas/PartnerRefDto", "description": "Domain object references that caused the error on problem type cleos-ref. NOTE: These _may_ be references to entities outside of CLEOS", "example": "EOS:Agreement:1234" } }, "properties": { "type": "object", "additionalProperties": {} }, "correlationId": { "type": "string", "description": "Correlation ID for tracking the error, used by cleos problem-types. Typically based on the request header X-Correlation-Id", "example": "1234-ABCDEFG-5678-HIJKL-91011-MNOPQ" } } }, "PartnerSettlementImportDto": { "type": "object", "description": "Generic Settlement submitted by Partner. This is a subset of the CLEOS settlement structure intended for self-serviced clearing. NOTE: The settlement does not currently support incoming and outgoing floats", "properties": { "id": { "type": "integer", "format": "int64" }, "posRef": { "type": "string", "description": "Reference to the PointOfSale (POS) for which the settlement is created.", "maxLength": 50, "minLength": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Context map containing additional key-value pairs relevant for the settlement. Only simple key-value pairs are supported (String, Number, Boolean) with a max length of 100 characters per value." }, "comments": { "type": "array", "description": "Optional comments associated with the settlement. Used for audit trail and additional information relevant for clearing.", "items": { "$ref": "#/components/schemas/PartnerCommentDto" } }, "msgSubjectId": { "type": "string" }, "settlementNo": { "type": "integer", "format": "int64", "description": "Settlement Sequence Number. This must be a continuous sequence for the settlement not to fail clearing. Negative sequences are typically used for corrections that are out of sequence. If not specified, the next number in a negative sequence will automatically be assigned based previous correction on the same POS. " }, "settlementDate": { "type": "string", "format": "date", "description": "Settlement Date for the settlement on the format YYYY.MM.DD" }, "correctionForSmntId": { "type": "integer", "format": "int64", "description": "If this settlement is a correction of a previous settlement, the internal CLEOS ID of the settlement being corrected must be provided." }, "genericTransactions": { "type": "array", "description": "List of Generic Transactions associated with the settlement.", "items": { "$ref": "#/components/schemas/PartnerTransactionImportDto" } }, "externalSettlementNo": { "type": "integer", "format": "int64", "description": "External Settlement Number provided by the Partner. If not provided, the settlementNo will be used as external reference as well." }, "distributionChannelRef": { "type": "string", "description": "Reference to the Distribution Channel for which the settlement is created.", "maxLength": 50, "minLength": 0 } }, "required": [ "distributionChannelRef", "genericTransactions", "posRef", "settlementDate" ] }, "PartnerTransactionImportDto": { "type": "object", "description": "A transaction to be cleared, represented in a generic format suitable for various transaction types.", "properties": { "orderId": { "type": "string", "description": "OrderID is a unique identifier for the transaction within the Partner's system. It is used to track and manage the transaction throughout its lifecycle. Note that several transactions may refer to the same OrderID (eg both the sale and the payment transaction)", "example": "ORD123456", "maxLength": 50, "minLength": 0 }, "orderVersion": { "type": "integer", "format": "int32", "description": "OrderVersion is a sequential version number for the transaction. It is used to track changes to the transaction over time.", "example": 1 }, "genericAnnexes": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerAnnexDto" } }, "transactionType": { "type": "string", "description": "Type of the transaction being submitted for clearing. This type MUST be assigned to the relevant Chart Of Accounts by the Cleos Administrator first.", "example": "ACMSALE", "maxLength": 30, "minLength": 0 } }, "required": [ "genericAnnexes", "transactionType" ] }, "PartnerSettlementImportResponseDto": { "type": "object", "description": "Relevant information on the successfully registered Settlement Import. See documentation for PartnerSettlementImportDto for details on fields that the client submitted.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier of queued Settlement Import.", "example": 12345 }, "posRef": { "type": "string" }, "status": { "type": "integer", "format": "int32", "description": "Status code indicating the result of the import operation. This will always be 0 (TO BE PROCESSED) on creation. 1 indicates SUCCESSFUL CLEARING", "examples": [ "0" ] }, "comments": { "type": "array", "items": { "type": "string" } }, "settlementNo": { "type": "integer", "format": "int64" }, "incomingFloat": { "$ref": "#/components/schemas/PartnerMoneyDto" }, "outgoingFloat": { "$ref": "#/components/schemas/PartnerMoneyDto" }, "ignoreSequence": { "type": "boolean", "description": "Indicates whether sequence errors will be ignored during import, typical for negative settlement sequences (corrections).", "example": false }, "settlementDate": { "type": "string", "format": "date" }, "statusDescription": { "type": "string", "description": "Message providing additional information on the import status.", "example": "Partner Settlement queued for processing." }, "externalSettlementNo": { "type": "integer", "format": "int64" }, "correctedSettlementId": { "type": "integer", "format": "int64" } } } }, "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": { "bearerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } }