{ "openapi": "3.1.0", "info": { "title": "Clearing Reports", "description": "Documentation for self-service synchronisation of data products generated by the Clearing system. See the [developer guide](https://developer.entur.no/guides/clearing/reports) for more information.", "contact": { "name": "Team Salgsdata", "email": "regnskapservice@entur.org" }, "version": "2026.09.1" }, "externalDocs": { "description": "Clearing Reports Developer Guide", "url": "https://developer.entur.no/guides/clearing/reports" }, "servers": [ { "url": "https://api.entur.io/cleos-reporting", "description": "Entur's Production environment" }, { "url": "https://api.staging.entur.io/cleos-reporting", "description": "Entur's Staging environment" }, { "url": "https://api.dev.entur.io/cleos-reporting", "description": "Entur's Development environment" } ], "security": [ { "bearerToken": [] } ], "tags": [ { "name": "Outgoing Data Products", "description": "Discover, inspect and download generated data products" } ], "paths": { "/api/v2/partner-data/dataset/{datasetId}/report": { "post": { "tags": [ "Outgoing Data Products" ], "summary": "Create download job for report", "description": "Creates an asynchronous download job that will format the dataset and make it available as a report via a signed bucket URL. Note that targetFormat CSV and CSV2 will both produce the same CSV2 format.", "operationId": "createDatasetDownloadJob", "parameters": [ { "name": "datasetId", "in": "path", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "targetFormat", "in": "query", "description": "Optional conversion format for Parquet datasets (PARQUET, XLSX, CSV2) ", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "enum": [ "UNKNOWN", "PDF", "CSV", "CSV2", "XLSX", "SAFT_GL", "PROFF1", "PROFF2", "ZIP", "TXT", "BINARY", "BCC", "FICHE", "FICHE_A", "FICHE_B", "CSV3", "EXTERNAL", "ACCOUNTED", "PARQUET", "BIGQUERY" ] } } ], "responses": { "201": { "description": "Created", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } }, "400": { "description": "Bad request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } }, "403": { "description": "Forbidden. Client Organisation not on the copy list" }, "404": { "description": "Dataset unavailable", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } }, "409": { "description": "Conflict", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } }, "500": { "description": "Internal Server Error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } } }, "x-entur-permissions": { "value": "cleos-reports:les" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/api/v2/partner-data/report/{jobId}": { "get": { "tags": [ "Outgoing Data Products" ], "summary": "Fetch formatted report metadata", "description": "Wait for asynchronous job and and return formatted report metadata. The report itself can be downloaded by the client using the provided signed bucket URL. ", "operationId": "getReportContents", "parameters": [ { "name": "jobId", "in": "path", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "waitFor", "in": "query", "description": "Wait in seconds, max 40", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int32", "default": 0 } } ], "responses": { "200": { "description": "OK. The report is available for download.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } }, "202": { "description": "Accepted. Returned if the optional waitFor has passed but the content is not yet available", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } }, "204": { "description": "No report content. No signed URL will be provided.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } }, "400": { "description": "Bad request. The Job failed.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } }, "403": { "description": "Forbidden. The job was not created for the authenticated user's organisation." }, "404": { "description": "No job exists.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } }, "409": { "description": "Conflict. The job has failed. Consult Entur.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } }, "410": { "description": "Gone. The job has expired and should not be used to download content", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } }, "500": { "description": "Internal Server Error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetDownloadJobDto" } } } } }, "x-entur-permissions": { "value": "cleos-reports:les" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/api/v2/partner-data/dataset/{datasetId}": { "get": { "tags": [ "Outgoing Data Products" ], "summary": "Get dataset metadata", "description": "Get dataset metadata. This does not include a download URL, create a download job for that.", "operationId": "getPartnerDatasetMetadata", "parameters": [ { "name": "datasetId", "in": "path", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Ok", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetRpt" } } } }, "400": { "description": "Bad request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetRpt" } } } }, "403": { "description": "Forbidden. Client Organisation not on the copy list" }, "404": { "description": "Not found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetRpt" } } } }, "409": { "description": "Conflict", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetRpt" } } } }, "500": { "description": "Internal Server Error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerDatasetRpt" } } } } }, "x-entur-permissions": { "value": "cleos-reports:les" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] }, "/api/v2/partner-data/dataproduct/{dataProductVersion}/next": { "get": { "tags": [ "Outgoing Data Products" ], "summary": "Find next dataset id", "description": "Find next dataset in the dataproduct identified by the dataProductVersion. The dataset must have the clients authenticated Organisation on the copy list. A dataset is defined as newer by having a greater ID than the provided (typically the previous successfully downloaded ID). The ID sequence may have holes but is always increasing. When synchronizing a new dataproduct with a backlog of datasets, the initial idAfter can be identified via the self service portal. Alternatively use idAfter=0 in combination with a fromDate to limit backlogged downloads. ", "operationId": "getNextDataset", "parameters": [ { "name": "dataProductVersion", "in": "path", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "idAfter", "in": "query", "description": "Return the first dataset ID from DataProduct with ID larger than this", "required": true, "style": "form", "explode": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "fromDate", "in": "query", "description": "Limit to datasets ordered on or after this date", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Ok", "content": { "*/*": { "schema": { "type": "integer", "format": "int64" } } } }, "204": { "description": "No new dataset available", "content": { "*/*": { "schema": { "type": "integer", "format": "int64" } } } }, "400": { "description": "Bad request", "content": { "*/*": { "schema": { "type": "integer", "format": "int64" } } } }, "404": { "description": "Data product version does not exist", "content": { "*/*": { "schema": { "type": "integer", "format": "int64" } } } }, "409": { "description": "Conflict. The next dataset has failed. Consult Entur before proceeding.", "content": { "*/*": { "schema": { "type": "integer", "format": "int64" } } } }, "410": { "description": "Data product version permanently disabled, no more datasets will be produced", "content": { "*/*": { "schema": { "type": "integer", "format": "int64" } } } }, "500": { "description": "Internal Server Error", "content": { "*/*": { "schema": { "type": "integer", "format": "int64" } } } } }, "x-entur-permissions": { "value": "cleos-reports:les" } }, "parameters": [ { "$ref": "#/components/parameters/ET-Client-Name" }, { "$ref": "#/components/parameters/X-Correlation-Id" } ] } }, "components": { "schemas": { "PartnerDatasetDownloadJobDto": { "type": "object", "description": "DTO for an asynchronous dataset download job. The formatted report itself can be downloaded by the client using the provided signed bucket URL. A formatted report is considered transient, and is identified by the download job that formats it. Note that a signed bucket URL will expire after a fixed period of time, typically 24 hours.", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID of this download job. The job will automatically expire after a fixed period of time after completion.", "example": "1170fca5-b0d6-4661-a002-112a21bde824" }, "status": { "type": "integer", "format": "int32", "description": "Current status of the job: 0=Ordered, 1=COMPLETED, 2=Failed, 3=Expired, 5=Processing.", "example": 0 }, "description": { "type": "string", "description": "Best effort explanation for the status.", "example": "0" }, "reportName": { "type": "string", "description": "Suggested report filename for the formatted dataset.", "example": "SD-GL-1_ATB_AS_-_2024100772511_v1.1.1.csv" }, "contentType": { "type": "string", "description": "MIME Type of the formatted dataset.", "example": "text/csv" }, "datasetIDs": { "type": "array", "description": "List of Dataset IDs that will be included in the download job. The API will always return a single ID since it does not support merging datasets.", "example": [ 7315613 ], "items": { "type": "integer", "format": "int64" } }, "jobCreatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the download job was created.", "example": "2024-12-06T09:09:47.713993" }, "rows": { "type": "integer", "format": "int64", "description": "The number of rows in the formatted dataset when COMPLETED.", "example": 1340 }, "signedBucketUrl": { "type": "string", "description": "The signed URL to download the formatted dataset when COMPLETED.", "example": "https://storage.googleapis.com/cleos-rep-test-bucket/060852c8-5fc8-4c55-a5ce-ee3ef3849ec3?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=cleos-rep-bucket-sa%40ent-clerep-dev.iam.gserviceaccount.com%2F20241204%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20241204T144627Z&X-Goog-Expires=86400&X-Goog-SignedHeaders=host&X-Goog-Signature=68a825a7dd51cde...." }, "crc32c": { "type": "string", "description": "Checksum of a formatted dataset when COMPLETED, this can be used by the client to verify the download. Not available for legacy reports.", "example": "+1nWcg==" } } }, "PartnerDatasetRpt": { "type": "object", "description": "Metadata for a Dataset. A Dataset is a batch of data that contributes to a Data Product. The Dataset may be downloaded as a formatted Report via this API, or via BigQuery depending on Dataset Type.", "properties": { "id": { "type": "integer", "format": "int64", "description": "ID of this dataset.", "example": 7232958 }, "dataProductVersion": { "type": "integer", "format": "int64", "description": "Id of the specific version of the data product template used.", "example": 1108 }, "dataProductCode": { "type": "string", "description": "The data product code, this may be contributed to by several template versions over time.", "example": "SD-GL-1" }, "orderDate": { "type": "string", "format": "date", "description": "The System Date for the dataset creation.", "example": "2024-12-03" }, "orderBy": { "type": "string", "description": "Created by user or system.", "example": "CLEOS" }, "datasetType": { "type": "string", "description": "Classification of the dataset. PARQUET sets can be formatted and downloaded on demand. BIGQUERY can not be downloaded, only accessed via BigQuery. LEGACY reports (CSV, XLSX) are preformatted.", "example": "PARQUET" }, "datasetName": { "type": "string", "description": "Userfriendly name of the dataset, typically used as the filename when downloaded.", "example": "SD-GL-1_ATB_AS_-_2024100772511_v1.1.1.parquet" }, "status": { "type": "integer", "format": "int32", "description": "Current status of the dataset: 0=Ordered, 1=COMPLETED, 2=Failed, 4=On Demand (DEPRECATED), 3=Cancelled, 9=Processing." }, "rows": { "type": "integer", "format": "int32", "description": "Number of rows in the dataset when COMPLETED. Not available for legacy reports.", "example": 1340 }, "bqProject": { "type": "string", "description": "Destination BigQuery project when dataset is of type BIGQUERY.", "example": "ent-data-vyg-ext-tst" }, "chartOfAccountsRef": { "type": "string", "description": "The Chart of Accounts this dataset is derived from, if defined.", "example": "EOS:ChartOfAccounts:210" }, "ownerOrgRef": { "type": "string", "description": "Organisation owning the dataset with self-service access.", "example": "4" }, "copyOrgRefs": { "type": "array", "description": "Recipients of the dataset with self-service and M2M access.", "example": [ 5, 6 ], "items": { "type": "string" } }, "acctMonthId": { "type": "integer", "format": "int64", "description": "Clearing system Accounting Month ID used by this dataset.", "example": 3201 }, "glBatchId": { "type": "integer", "format": "int64", "description": "GL Batch ID potentially used by this dataset.", "example": 2024120172588 }, "apBatchId": { "type": "integer", "format": "int64", "description": "AP Batch ID potentially used by this dataset.", "example": 161004032 }, "arBatchId": { "type": "integer", "format": "int64", "description": "AR Batch ID potentially used by this dataset.", "example": 840007997 }, "inBatchId": { "type": "integer", "format": "int64", "description": "IN Batch ID potentially used by this dataset.", "example": 790 }, "agreementId": { "type": "integer", "format": "int64", "description": "Clearing system Agreement ID potentially used by this dataset.", "example": 3752 } } } }, "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: `-`.", "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" } } }, "securitySchemes": { "bearerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } }