A **Document** is a file attached to one or more **Buildings** (certificates, leases and similar). Documents can be uploaded, downloaded, given an external id, have their metadata read and updated, and be deleted; a `file-events` feed reports document changes over a time range. Metadata edits and deletion apply to API-sourced documents.
openapi: 3.1.0
info:
description: '
## Introduction
The **CAPEX API** enables you to integrate your application with the CAPEX system. The CAPEX API is REST-based and follows JSON:API principles for structuring responses.
Starting from version 1.0, the API is stable. We are continuously improving our API, and new endpoints will be added. Any updates or changes within this major version will be backward-compatible and can be found in this documentation.
For getting access to the CAPEX API, please reach out to us at: `kontakt@alasco.de`.
The base URL for all endpoints is:
`https://api.alasco.de/capex/v1`
The CAPEX API supports compressed payloads. If you would like to make use of this, you have to specify the `Accept-Encoding` header. Supported encodings are `gzip` and `br`.
### Domain model
Objects relate as follows (each `→` is a navigable sub-resource):
- **Assets** and **Measures** are the CapEx-specific top-level objects; a **Measure** → **Contracts**, and invoices are submitted against an **Asset**.
- **Contractor** and **Contracting Entity** → **Contracts**.
- **Contract** → **Change Orders**, **Invoices**, contract terms, **Documents** and **Custom Fields**.
- **Invoice** → **Documents** and **Tags** (Change Orders also carry **Documents**).
### CAPEX API Overview
The CAPEX API provides endpoints to:
- Retrieve and manage invoices, invoice tags, and invoice documents
- Retrieve assets, contracts, contractors, and measures
The CAPEX API uses pagination. The page size is 100, and additional pages can be accessed using a `next` link.
'
title: CAPEX Annual Consumption Documents API
version: '1.0'
x-logo:
url: https://assets-global.website-files.com/656ef2eb27ad41897248f866/659eebec190ae7aaf4162f09_Logotype_Alasco_white_RGB%202.png
servers:
- url: https://api.alasco.de/capex/v1
tags:
- description: A **Document** is a file attached to one or more **Buildings** (certificates, leases and similar). Documents can be uploaded, downloaded, given an external id, have their metadata read and updated, and be deleted; a `file-events` feed reports document changes over a time range. Metadata edits and deletion apply to API-sourced documents.
name: Documents
paths:
/file-events/:
get:
operationId: get_file_events_file_events__get
parameters:
- in: query
name: start_time
required: true
schema:
format: date-time
title: Start Time
type: string
- in: query
name: end_time
required: true
schema:
format: date-time
title: End Time
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentEventsResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
- API Token: []
summary: Get File Events
tags:
- Documents
/files/:
delete:
operationId: delete_file_files__delete
parameters:
- in: query
name: external_id
required: true
schema:
title: External Id
type: string
responses:
'204':
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
- API Token: []
summary: Delete File
tags:
- Documents
post:
operationId: upload_file_files__post
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_upload_file_files__post'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/FileUploadResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
- API Token: []
summary: Upload File
tags:
- Documents
/files/metadata/:
get:
operationId: get_file_metadata_files_metadata__get
parameters:
- in: query
name: external_id
required: true
schema:
title: External Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/FileMetadataResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
- API Token: []
summary: Get File Metadata
tags:
- Documents
patch:
operationId: patch_file_metadata_files_metadata__patch
parameters:
- in: query
name: external_id
required: true
schema:
title: External Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FileMetadataUpdateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/FileMetadataResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
- API Token: []
summary: Patch File Metadata
tags:
- Documents
/files/{file_id}/:
get:
operationId: get_file_files__file_id___get
parameters:
- in: path
name: file_id
required: true
schema:
format: uuid
title: File Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/FileGetResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
- API Token: []
summary: Get File
tags:
- Documents
/files/{file_id}/external-id/:
post:
operationId: create_file_external_id_files__file_id__external_id__post
parameters:
- in: path
name: file_id
required: true
schema:
format: uuid
title: File Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalIdRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalIdResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
- API Token: []
summary: Create File External Id
tags:
- Documents
components:
schemas:
DocumentEventAttributes:
properties:
event_type:
$ref: '#/components/schemas/DocumentEventType'
description: '**Event type** · **Ereignistyp**'
record:
$ref: '#/components/schemas/DocumentEventRecord'
description: '**Record** · **Datensatz**'
source:
$ref: '#/components/schemas/DocumentSource'
description: '**Source** · **Quelle**'
timestamp:
description: '**Timestamp** · **Zeitstempel**'
format: date-time
title: Timestamp
type: string
required:
- event_type
- timestamp
- source
- record
title: DocumentEventAttributes
type: object
ExternalIdRequest:
properties:
data:
$ref: '#/components/schemas/ExternalIdRequestData'
required:
- data
title: ExternalIdRequest
type: object
Links:
properties:
next:
anyOf:
- type: string
- type: 'null'
title: Next
prev:
anyOf:
- type: string
- type: 'null'
title: Prev
required:
- next
- prev
title: Links
type: object
FileUploadResponse:
properties:
data:
$ref: '#/components/schemas/FileUploadData'
errors:
anyOf:
- items:
$ref: '#/components/schemas/Error'
type: array
- type: 'null'
title: Errors
included:
anyOf:
- items:
$ref: '#/components/schemas/BaseDataSchema'
type: array
- type: 'null'
title: Included
links:
anyOf:
- $ref: '#/components/schemas/Links'
- type: 'null'
required:
- data
title: FileUploadResponse
type: object
FileGetAttributes:
properties:
building_external_ids:
description: '**Building external IDs** · **Externe Gebäude-IDs**'
items:
type: string
title: Building External Ids
type: array
document_type:
$ref: '#/components/schemas/DocumentType'
description: '**Document type** · **Dokumenttyp**'
download_url:
description: '**Download URL** · **Download-URL**'
title: Download Url
type: string
external_id:
anyOf:
- type: string
- type: 'null'
description: '**External ID** · **Externe ID**'
title: External Id
file_id:
description: '**File ID** · **Datei-ID**'
format: uuid
title: File Id
type: string
issued_at:
anyOf:
- format: date
type: string
- type: 'null'
description: '**Issued at** · **Ausstellungsdatum**'
title: Issued At
name:
anyOf:
- type: string
- type: 'null'
description: '**Name** · **Name**'
title: Name
source:
$ref: '#/components/schemas/DocumentSource'
description: '**Source** · **Quelle**'
valid_until:
anyOf:
- format: date
type: string
- type: 'null'
description: '**Valid until** · **Gültig bis**'
title: Valid Until
required:
- name
- external_id
- source
- file_id
- building_external_ids
- document_type
- issued_at
- valid_until
- download_url
title: FileGetAttributes
type: object
Body_upload_file_files__post:
properties:
file:
contentMediaType: application/octet-stream
title: File
type: string
required:
- file
title: Body_upload_file_files__post
type: object
DocumentEventRecord:
properties:
building_external_ids:
description: '**Building external IDs** · **Externe Gebäude-IDs**'
items:
type: string
title: Building External Ids
type: array
document_type:
$ref: '#/components/schemas/DocumentType'
description: '**Document type** · **Dokumenttyp**'
external_id:
anyOf:
- type: string
- type: 'null'
description: '**External ID** · **Externe ID**'
title: External Id
file_id:
description: '**File ID** · **Datei-ID**'
format: uuid
title: File Id
type: string
issued_at:
anyOf:
- format: date-time
type: string
- type: 'null'
description: '**Issued at** · **Ausstellungsdatum**'
title: Issued At
name:
anyOf:
- type: string
- type: 'null'
description: '**Name** · **Name**'
title: Name
valid_until:
anyOf:
- format: date-time
type: string
- type: 'null'
description: '**Valid until** · **Gültig bis**'
title: Valid Until
required:
- file_id
- name
- external_id
- document_type
- building_external_ids
- issued_at
- valid_until
title: DocumentEventRecord
type: object
FileMetadataAttributes:
properties:
building_external_ids:
description: '**Building external IDs** · **Externe Gebäude-IDs**'
items:
type: string
title: Building External Ids
type: array
document_type:
$ref: '#/components/schemas/DocumentType'
description: '**Document type** · **Dokumenttyp**'
external_id:
description: '**External ID** · **Externe ID**'
title: External Id
type: string
file_id:
description: '**File ID** · **Datei-ID**'
format: uuid
title: File Id
type: string
issued_at:
anyOf:
- format: date
type: string
- type: 'null'
description: '**Issued at** · **Ausstellungsdatum**'
title: Issued At
name:
anyOf:
- type: string
- type: 'null'
description: '**Name** · **Name**'
title: Name
source:
$ref: '#/components/schemas/DocumentSource'
description: '**Source** · **Quelle**'
valid_until:
anyOf:
- format: date
type: string
- type: 'null'
description: '**Valid until** · **Gültig bis**'
title: Valid Until
required:
- name
- external_id
- source
- file_id
- building_external_ids
- document_type
- issued_at
- valid_until
title: FileMetadataAttributes
type: object
DocumentType:
enum:
- ENERGY_CERTIFICATE
- TAXONOMY_PROOF
- BUILDING_CERTIFICATE
- UTILITY_BILL
- CLIMATE_RISK_ANALYSIS
- TENANT_LEASE
- WASTE_COLLECTION_INTERVAL
- EMISSION_FACTOR_PROOF
- WASTE_MANAGEMENT_CONCEPT
- WASTE_DOCUMENTATION
- WASTE_REPORT
- PUBLIC_DISPLAY_ENERGY_CERTIFICATE
- RENEWABLE_ELECTRICITY_CERTIFICATE
- ESG_ANALYSIS
- EU_TAXONOMY_ASSESSMENT
- ENERGY_RENOVATION_ROADMAP
- ENERGY_AUDIT
- INVESTOR_ESG_ANALYSIS
- ENERGY_REVIEW
- OTHER
- UNSET
title: DocumentType
type: string
DocumentEventData:
properties:
attributes:
$ref: '#/components/schemas/DocumentEventAttributes'
id:
format: uuid
title: Id
type: string
relationships:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Relationships
type:
const: DOCUMENT_EVENT
default: DOCUMENT_EVENT
title: Type
type: string
required:
- id
- attributes
title: DocumentEventData
type: object
ExternalIdResponse:
properties:
data:
$ref: '#/components/schemas/ExternalIdData'
errors:
anyOf:
- items:
$ref: '#/components/schemas/Error'
type: array
- type: 'null'
title: Errors
included:
anyOf:
- items:
$ref: '#/components/schemas/BaseDataSchema'
type: array
- type: 'null'
title: Included
links:
anyOf:
- $ref: '#/components/schemas/Links'
- type: 'null'
required:
- data
title: ExternalIdResponse
type: object
ExternalIdData:
properties:
attributes:
$ref: '#/components/schemas/ExternalIdAttributes'
id:
format: uuid
title: Id
type: string
relationships:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Relationships
type:
const: FILE_EXTERNAL_ID
default: FILE_EXTERNAL_ID
title: Type
type: string
required:
- id
- attributes
title: ExternalIdData
type: object
Error:
properties:
code:
anyOf:
- type: string
- type: 'null'
title: Code
detail:
anyOf:
- type: string
- type: 'null'
title: Detail
source:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Source
status:
anyOf:
- type: string
- type: 'null'
title: Status
title:
anyOf:
- type: string
- type: 'null'
title: Title
title: Error
type: object
ValidationError:
properties:
ctx:
title: Context
type: object
input:
title: Input
loc:
items:
anyOf:
- type: string
- type: integer
title: Location
type: array
msg:
title: Message
type: string
type:
title: Error Type
type: string
required:
- loc
- msg
- type
title: ValidationError
type: object
FileGetData:
properties:
attributes:
$ref: '#/components/schemas/FileGetAttributes'
id:
format: uuid
title: Id
type: string
relationships:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Relationships
type:
const: FILE
default: FILE
title: Type
type: string
required:
- id
- attributes
title: FileGetData
type: object
DocumentEventType:
enum:
- CREATE
- UPDATE
- DELETE
title: DocumentEventType
type: string
FileMetadataResponse:
properties:
data:
$ref: '#/components/schemas/FileMetadataData'
errors:
anyOf:
- items:
$ref: '#/components/schemas/Error'
type: array
- type: 'null'
title: Errors
included:
anyOf:
- items:
$ref: '#/components/schemas/BaseDataSchema'
type: array
- type: 'null'
title: Included
links:
anyOf:
- $ref: '#/components/schemas/Links'
- type: 'null'
required:
- data
title: FileMetadataResponse
type: object
ResourceType:
enum:
- BUILDING
- UTILITY_METER
- UTILITY_METER_IMPORT
- UTILITY_METER_READING
- CONSUMPTION_INTERVAL
- UTILITY_DATA_BATCH_INFO
- AUDIT_LOG
- USER_AUDIT_LOG
- DOCUMENT_EVENT
- FILE
- FILE_EXTERNAL_ID
- FILE_METADATA
- ANALYSIS_RESULT
- TENANT
- TENANT_ATTACHMENT
- CUSTOM_DATA_GROUP_INSTANCE
- ANNUAL_CONSUMPTION
- TENANT_CONSUMPTION_LINK
title: ResourceType
type: string
DocumentEventsResponse:
properties:
data:
items:
$ref: '#/components/schemas/DocumentEventData'
title: Data
type: array
errors:
anyOf:
- items:
$ref: '#/components/schemas/Error'
type: array
- type: 'null'
title: Errors
included:
anyOf:
- items:
$ref: '#/components/schemas/BaseDataSchema'
type: array
- type: 'null'
title: Included
links:
anyOf:
- $ref: '#/components/schemas/Links'
- type: 'null'
required:
- data
title: DocumentEventsResponse
type: object
DocumentSource:
enum:
- APP
- API
- SURVEY
title: DocumentSource
type: string
ExternalIdRequestAttributes:
properties:
external_id:
description: '**External ID** · **Externe ID**'
title: External Id
type: string
required:
- external_id
title: ExternalIdRequestAttributes
type: object
FileMetadataData:
properties:
attributes:
$ref: '#/components/schemas/FileMetadataAttributes'
id:
format: uuid
title: Id
type: string
relationships:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Relationships
type:
const: FILE_METADATA
default: FILE_METADATA
title: Type
type: string
required:
- id
- attributes
title: FileMetadataData
type: object
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
title: Detail
type: array
title: HTTPValidationError
type: object
FileUploadData:
properties:
attributes:
anyOf:
- {}
- type: 'null'
title: Attributes
id:
format: uuid
title: Id
type: string
relationships:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Relationships
type:
const: FILE
default: FILE
title: Type
type: string
required:
- id
title: FileUploadData
type: object
ExternalIdRequestData:
properties:
attributes:
$ref: '#/components/schemas/ExternalIdRequestAttributes'
type:
const: FILE_EXTERNAL_ID
default: FILE_EXTERNAL_ID
title: Type
type: string
required:
- attributes
title: ExternalIdRequestData
type: object
BaseDataSchema:
properties:
attributes:
anyOf:
- {}
- type: 'null'
title: Attributes
id:
format: uuid
title: Id
type: string
relationships:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Relationships
type:
$ref: '#/components/schemas/ResourceType'
required:
- id
- type
title: BaseDataSchema
type: object
FileMetadataUpdateData:
properties:
attributes:
$ref: '#/components/schemas/FileMetadataUpdateAttributes'
type:
const: FILE_METADATA
default: FILE_METADATA
title: Type
type: string
required:
- attributes
title: FileMetadataUpdateData
type: object
ExternalIdAttributes:
properties:
external_id:
description: '**External ID** · **Externe ID**'
title: External Id
type: string
file_id:
description: '**File ID** · **Datei-ID**'
format: uuid
title: File Id
type: string
required:
- file_id
- external_id
title: ExternalIdAttributes
type: object
FileMetadataUpdateRequest:
properties:
data:
$ref: '#/components/schemas/FileMetadataUpdateData'
required:
- data
title: FileMetadataUpdateRequest
type: object
FileGetResponse:
properties:
data:
$ref: '#/components/schemas/FileGetData'
errors:
anyOf:
- items:
$ref: '#/components/schemas/Error'
type: array
- type: 'null'
title: Errors
included:
anyOf:
- items:
$ref: '#/components/schemas/BaseDataSchema'
type: array
- type: 'null'
title: Included
links:
anyOf:
- $ref: '#/components/schemas/Links'
- type: 'null'
required:
- data
title: FileGetResponse
type: object
FileMetadataUpdateAttributes:
properties:
building_external_id:
anyOf:
- type: string
- type: 'null'
description: '**Building external ID** · **Externe Gebäude-ID**'
title: Building External Id
document_type:
anyOf:
- $ref: '#/components/schemas/DocumentType'
- type: 'null'
description: '**Document type** · **Dokumenttyp**'
name:
anyOf:
- type: string
- type: 'null'
description: '**Name** · **Name**'
title: Name
title: FileMetadataUpdateAttributes
type: object
securitySchemes:
API Key:
description: '
The Alasco API uses a combination of API keys and API tokens to authenticate requests. The API key
needs to be sent in a header field called `X-API-KEY`.
'
in: header
name: X-API-KEY
type: apiKey
API Token:
description: '
In addition to an API key, one has to specify an API token. There can be one or more tokens in use
for the same API key. The token needs to be sent in a header field called `X-API-TOKEN`.
Right now, it''s not possible to create API keys and API tokens from within Alasco.
If you are interested in using the Alasco API, please reach out to the
[support team](mailto:support@alasco.de). They will assist you in generating a key and token pair.
'
in: header
name: X-API-TOKEN
type: apiKey