A **Contract Unit** is a budget package within a **Project** (the FinCon counterpart of a CapEx Measure), carrying an initial budget and a lifecycle **state**. **Contracts** are assigned to a contract unit, and **Budget Shifts** move budget between units. Contract units can be created and updated through the API.
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 Contract Unit 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 **Contract Unit** is a budget package within a **Project** (the FinCon counterpart of a CapEx Measure), carrying an initial budget and a lifecycle **state**. **Contracts** are assigned to a contract unit, and **Budget Shifts** move budget between units. Contract units can be created and updated through the API.
name: Contract Unit
paths:
/contract_units/:
get:
operationId: get_contract_units_contract_units__get
parameters:
- description: '
List endpoint responses are paginated in the Alasco API. By calling the endpoint without the
pagination parameter you will receive the first page. If not all elements fit on one page there will
be a `next` link provided in the response''s `links` object. By calling this link you will receive
the next page.
'
in: query
name: cursor[position]
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: '
List endpoint responses are paginated in the Alasco API. By calling the endpoint without the
pagination parameter you will receive the first page. If not all elements fit on one page there will
be a `next` link provided in the response''s `links` object. By calling this link you will receive
the next page.
'
title: Cursor[Position]
- description: '
You can filter on certain attributes by specifying them as a GET parameter along
with an operation, e.g. `filter[name.exact]=abc`.
Currently supported operations are:
* `exact`: Expects one value
* `contains`: Expects one value
* `in`: Expects one or multiple values
* `not_in`: Expects one or multiple values
The following attributes support filtering:
| **Attribute** | `exact` | `contains` | `in` | `not_in` |
| :--- | :---: | :---: | :---: | :---: |
| `id` | | | x | x |
| `name` | x | x | | |
| `state` | | | x | x |
| `project` | | | x | x |
'
in: query
name: filter[attribute.operation]
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: '
You can filter on certain attributes by specifying them as a GET parameter along
with an operation, e.g. `filter[name.exact]=abc`.
Currently supported operations are:
* `exact`: Expects one value
* `contains`: Expects one value
* `in`: Expects one or multiple values
* `not_in`: Expects one or multiple values
The following attributes support filtering:
| **Attribute** | `exact` | `contains` | `in` | `not_in` |
| :--- | :---: | :---: | :---: | :---: |
| `id` | | | x | x |
| `name` | x | x | | |
| `state` | | | x | x |
| `project` | | | x | x |
'
title: Filter[Attribute.Operation]
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListResponse_ContractUnitAttributes_Literal_CONTRACT_UNIT__'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
API Token: []
summary: Get Contract Units
tags:
- Contract Unit
post:
operationId: create_contract_unit_contract_units__post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContractUnitCreateRequest'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Response_ContractUnitAttributes_Literal_CONTRACT_UNIT__'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
API Token: []
summary: Create Contract Unit
tags:
- Contract Unit
/contract_units/{id}/:
get:
operationId: get_contract_unit_details_contract_units__id___get
parameters:
- in: path
name: id
required: true
schema:
format: uuid
title: Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Response_ContractUnitAttributes_Literal_CONTRACT_UNIT__'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
API Token: []
summary: Get Contract Unit Details
tags:
- Contract Unit
patch:
operationId: patch_contract_unit_contract_units__id___patch
parameters:
- in: path
name: id
required: true
schema:
format: uuid
title: Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContractUnitPatchRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Response_ContractUnitAttributes_Literal_CONTRACT_UNIT__'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
API Token: []
summary: Patch Contract Unit
tags:
- Contract Unit
components:
schemas:
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
title: Detail
type: array
title: HTTPValidationError
type: object
ContractUnitPatchData:
properties:
attributes:
anyOf:
- $ref: '#/components/schemas/ContractUnitPatchAttributes'
- type: 'null'
id:
format: uuid
title: Id
type: string
type:
const: CONTRACT_UNIT
default: CONTRACT_UNIT
title: Type
type: string
required:
- id
title: ContractUnitPatchData
type: object
ContractRelationshipAttributes:
properties:
id:
format: uuid
title: Id
type: string
type:
title: Type
type: string
required:
- type
- id
title: ContractRelationshipAttributes
type: object
ContractUnitCreateData:
properties:
attributes:
$ref: '#/components/schemas/ContractUnitCreateAttributes'
relationships:
$ref: '#/components/schemas/ContractUnitCreateRelationships'
type:
const: CONTRACT_UNIT
default: CONTRACT_UNIT
title: Type
type: string
required:
- attributes
- relationships
title: ContractUnitCreateData
type: object
ContractUnitState:
enum:
- BUDGETED
- FULLY_AWARDED
- FINALIZED
- CONTINGENCY
- FINANCING
title: ContractUnitState
type: string
ContractUnitPatchRequest:
properties:
data:
$ref: '#/components/schemas/ContractUnitPatchData'
required:
- data
title: ContractUnitPatchRequest
type: object
ListResponse_ContractUnitAttributes_Literal_CONTRACT_UNIT__:
properties:
data:
items:
$ref: '#/components/schemas/Data_ContractUnitAttributes_Literal_CONTRACT_UNIT__'
title: Data
type: array
errors:
anyOf:
- items:
$ref: '#/components/schemas/Error'
type: array
- type: 'null'
title: Errors
included:
anyOf:
- items:
$ref: '#/components/schemas/Data_ContractUnitAttributes_Literal_CONTRACT_UNIT__'
type: array
- type: 'null'
title: Included
links:
anyOf:
- additionalProperties:
anyOf:
- type: string
- type: 'null'
type: object
- type: 'null'
description: '
Contains the pagination''s next link if results don''t fit on one page.
'
title: Links
required:
- data
title: 'ListResponse[ContractUnitAttributes, Literal[<ResourceType.CONTRACT_UNIT: ''CONTRACT_UNIT''>]]'
type: object
ContractUnitCreateRelationships:
properties:
project:
$ref: '#/components/schemas/ContractRelationshipData'
description: '**Project** · **Projekt**'
required:
- project
title: ContractUnitCreateRelationships
type: object
Response_ContractUnitAttributes_Literal_CONTRACT_UNIT__:
properties:
data:
anyOf:
- $ref: '#/components/schemas/Data_ContractUnitAttributes_Literal_CONTRACT_UNIT__'
- type: 'null'
errors:
anyOf:
- items:
$ref: '#/components/schemas/Error'
type: array
- type: 'null'
title: Errors
included:
anyOf:
- items:
$ref: '#/components/schemas/Data_ContractUnitAttributes_Literal_CONTRACT_UNIT__'
type: array
- type: 'null'
title: Included
links:
anyOf:
- additionalProperties:
anyOf:
- type: string
- type: 'null'
type: object
- type: 'null'
title: Links
title: 'Response[ContractUnitAttributes, Literal[<ResourceType.CONTRACT_UNIT: ''CONTRACT_UNIT''>]]'
type: object
ContractUnitCreateRequest:
properties:
data:
$ref: '#/components/schemas/ContractUnitCreateData'
required:
- data
title: ContractUnitCreateRequest
type: object
ContractUnitPatchAttributes:
properties:
description:
anyOf:
- type: string
- type: 'null'
description: '**Description** · **Beschreibung**'
title: Description
initial_budget:
anyOf:
- properties:
net:
example: '123.123456789012'
title: Net amount
type: string
tax:
example: '123.123456789012'
title: Tax amount
type: string
type: object
- type: 'null'
description: '**Initial budget** · **Ausgangsbudget**
When set, replaces the stored initial budget (non-cost-element projects only; same constraints as internal contract unit updates). Cannot be cleared via the API; omit the field to leave it unchanged.
Ersetzt das gespeicherte Ausgangsbudget (nur Projekte ohne Kostengruppen; gleiche Einschränkungen wie bei internen Vergabeeinheits-Updates). Kann über die API nicht geleert werden; Feld weglassen, um es unverändert zu lassen.'
title: Initial Budget
name:
anyOf:
- maxLength: 250
type: string
- type: 'null'
description: '**Name** · **Name**'
title: Name
state:
anyOf:
- $ref: '#/components/schemas/ContractUnitState'
- type: 'null'
description: '**State** · **Status**
When set, updates the lifecycle state subject to server rules (e.g. finalized only when all contracts are completed). Cannot transition into or out of contingency or financing through the API.
Aktualisiert den Status gemäß den Serverregeln (z. B. schlussgerechnet nur, wenn alle Aufträge abgeschlossen sind). Ein Wechsel in oder aus Rückstellung oder Finanzierung ist über die API nicht möglich.
Available values / Verfügbare Werte:
| Value | English | Deutsch |
| --- | --- | --- |
| `BUDGETED` | Budgeted | Budgetiert |
| `FULLY_AWARDED` | Fully awarded | Vergeben |
| `FINALIZED` | Finalised | Schlussgerechnet |
| `CONTINGENCY` | Contingency | Reserve |
| `FINANCING` | Financing | Finanzierung |'
title: ContractUnitPatchAttributes
type: object
Error:
properties:
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
ContractUnitPublicCreateState:
enum:
- BUDGETED
- CONTINGENCY
title: ContractUnitPublicCreateState
type: string
Data_ContractUnitAttributes_Literal_CONTRACT_UNIT__:
properties:
attributes:
$ref: '#/components/schemas/ContractUnitAttributes'
id:
format: uuid
title: Id
type: string
relationships:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
description: '
Contains links to related objects.
'
title: Relationships
type:
const: CONTRACT_UNIT
title: Type
type: string
required:
- id
- type
- attributes
title: 'Data[ContractUnitAttributes, Literal[<ResourceType.CONTRACT_UNIT: ''CONTRACT_UNIT''>]]'
type: object
ContractRelationshipData:
properties:
data:
$ref: '#/components/schemas/ContractRelationshipAttributes'
required:
- data
title: ContractRelationshipData
type: object
ContractUnitCreateAttributes:
properties:
description:
default: ''
description: '**Description** · **Beschreibung**'
title: Description
type: string
initial_budget:
anyOf:
- properties:
net:
example: '123.123456789012'
title: Net amount
type: string
tax:
example: '123.123456789012'
title: Tax amount
type: string
type: object
- type: 'null'
description: '**Initial budget** · **Ausgangsbudget**
Optional initial budget (net/tax). Only allowed when the target project does not use cost elements; otherwise omit or leave unset.
Optionales Ausgangsbudget (netto/USt.). Nur zulässig, wenn das Zielprojekt keine Kostengruppen verwendet; andernfalls weglassen.'
title: Initial Budget
name:
description: '**Name** · **Name**'
maxLength: 250
title: Name
type: string
state:
$ref: '#/components/schemas/ContractUnitPublicCreateState'
default: BUDGETED
description: '**State** · **Status**
Lifecycle state when creating the contract unit: BUDGETED or CONTINGENCY (contingency / reserve). Financing contract units cannot be created through the API.
Status beim Anlegen der Vergabeeinheit: BUDGETED oder CONTINGENCY (Rückstellung / Reserve). Finanzierungs-Vergabeeinheiten können nicht über die API angelegt werden.
Available values / Verfügbare Werte:
| Value | English | Deutsch |
| --- | --- | --- |
| `BUDGETED` | Budgeted | Budgetiert |
| `CONTINGENCY` | Contingency | Reserve |'
required:
- name
title: ContractUnitCreateAttributes
type: object
ContractUnitAttributes:
properties:
description:
description: '**Description** · **Beschreibung**'
title: Description
type: string
name:
description: '**Name** · **Name**'
maxLength: 250
title: Name
type: string
project:
description: '**Project** · **Projekt**'
format: uuid
title: Project
type: string
state:
$ref: '#/components/schemas/ContractUnitState'
description: '**State** · **Status**
Available values / Verfügbare Werte:
| Value | English | Deutsch |
| --- | --- | --- |
| `BUDGETED` | Budgeted | Budgetiert |
| `FULLY_AWARDED` | Fully awarded | Vergeben |
| `FINALIZED` | Finalised | Schlussgerechnet |
| `CONTINGENCY` | Contingency | Reserve |
| `FINANCING` | Financing | Finanzierung |'
examples:
- BUDGETED
required:
- project
- name
- state
- description
title: ContractUnitAttributes
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