A **Change Order Document** is a file attached to a **Change Order** (for example the amendment offer or supporting evidence). You can upload and download them; a document left unlinked is removed automatically after a grace period.
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 Change Order Document 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 **Change Order Document** is a file attached to a **Change Order** (for example the amendment offer or supporting evidence). You can upload and download them; a document left unlinked is removed automatically after a grace period.
name: Change Order Document
paths:
/change_orders/{change_order_id}/documents/:
get:
operationId: get_change_order_documents_change_orders__change_order_id__documents__get
parameters:
- in: path
name: change_order_id
required: true
schema:
format: uuid
title: Change Order Id
type: string
- 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:
* `less_than_equal`: Expects one value
* `greater_than_equal`: Expects one value
* `range`: Expects two values
* `in`: Expects one or multiple values
* `not_in`: Expects one or multiple values
The following attributes support filtering:
| **Attribute** | `less_than_equal` | `greater_than_equal` | `range` | `in` | `not_in` |
| :--- | :---: | :---: | :---: | :---: | :---: |
| `document_type` | | | | x | x |
| `uploaded_at` | x | 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:
* `less_than_equal`: Expects one value
* `greater_than_equal`: Expects one value
* `range`: Expects two values
* `in`: Expects one or multiple values
* `not_in`: Expects one or multiple values
The following attributes support filtering:
| **Attribute** | `less_than_equal` | `greater_than_equal` | `range` | `in` | `not_in` |
| :--- | :---: | :---: | :---: | :---: | :---: |
| `document_type` | | | | x | x |
| `uploaded_at` | x | x | x | | |
'
title: Filter[Attribute.Operation]
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeOrderDocumentListResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
- API Token: []
summary: Get Change Order Documents
tags:
- Change Order Document
post:
operationId: create_change_order_document_change_orders__change_order_id__documents__post
parameters:
- in: path
name: change_order_id
required: true
schema:
format: uuid
title: Change Order Id
type: string
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_create_change_order_document_change_orders__change_order_id__documents__post'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeOrderDocumentResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
- API Token: []
summary: Create Change Order Document
tags:
- Change Order Document
/change_orders/{change_order_id}/documents/{document_id}/:
get:
operationId: get_change_order_document_change_orders__change_order_id__documents__document_id___get
parameters:
- in: path
name: document_id
required: true
schema:
format: uuid
title: Document Id
type: string
- in: path
name: change_order_id
required: true
schema:
format: uuid
title: Change Order Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeOrderDocumentResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
- API Token: []
summary: Get Change Order Document
tags:
- Change Order Document
/change_orders/{change_order_id}/documents/{document_id}/download-annotated/:
get:
operationId: download_annotated_change_order_document_change_orders__change_order_id__documents__document_id__download_annotated__get
parameters:
- in: path
name: change_order_id
required: true
schema:
format: uuid
title: Change Order Id
type: string
- in: path
name: document_id
required: true
schema:
format: uuid
title: Document Id
type: string
responses:
'200':
description: '
Returns the document with annotations if available, otherwise returns the original document.
'
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
- API Token: []
summary: Download Annotated Change Order Document
tags:
- Change Order Document
/change_orders/{change_order_id}/documents/{document_id}/download/:
get:
operationId: download_change_order_document_change_orders__change_order_id__documents__document_id__download__get
parameters:
- in: path
name: change_order_id
required: true
schema:
format: uuid
title: Change Order Id
type: string
- in: path
name: document_id
required: true
schema:
format: uuid
title: Document Id
type: string
responses:
'302':
description: '
Redirect to the temporary download link
'
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- API Key: []
- API Token: []
summary: Download Change Order Document
tags:
- Change Order Document
components:
schemas:
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
title: Detail
type: array
title: HTTPValidationError
type: object
ChangeOrderDocumentDataLinks:
properties:
download:
examples:
- https://api.alasco.de/fincon/v1/change-orders/<change_order_id>/documents/<document_id>/download/
title: Download
type: string
download_annotated:
examples:
- https://api.alasco.de/fincon/v1/change-orders/<change_order_id>/documents/<document_id>/download-annotated/
title: Download Annotated
type: string
self:
examples:
- https://api.alasco.de/fincon/v1/change-orders/<change_order_id>/documents/<document_id>/
title: Self
type: string
required:
- self
- download
- download_annotated
title: ChangeOrderDocumentDataLinks
type: object
ChangeOrderDocumentData:
properties:
attributes:
$ref: '#/components/schemas/ChangeOrderDocumentAttributes'
id:
format: uuid
title: Id
type: string
links:
$ref: '#/components/schemas/ChangeOrderDocumentDataLinks'
relationships:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
description: '
Contains links to related objects.
'
examples:
- change_order:
data:
id: 503671b0-c9b4-47a9-b859-763fcf8a9f28
type: CHANGE_ORDER
title: Relationships
type:
default: CHANGE_ORDER_DOCUMENT
title: Type
type: string
required:
- id
- attributes
- links
title: ChangeOrderDocumentData
type: object
ChangeOrderDocumentType:
description: 'Change order documents can be of different types such as `CHANGE_ORDER_OFFER`, `ATTACHMENT`, `COVERSHEET_EXTERNAL`,
`AUDITED_CHANGE_ORDER`, `INTERNAL_CORRESPONDENCE`, `EXTERNAL_CORRESPONDENCE`, `VALUATIONS`, `PLANS`,
`CHANGE_ORDER`, `PROTOCOL` and `OTHER`.'
enum:
- CHANGE_ORDER_OFFER
- ATTACHMENT
- COVERSHEET_EXTERNAL
- AUDITED_CHANGE_ORDER
- INTERNAL_CORRESPONDENCE
- EXTERNAL_CORRESPONDENCE
- VALUATIONS
- PLANS
- CHANGE_ORDER
- PROTOCOL
- OTHER
title: ChangeOrderDocumentType
type: string
Body_create_change_order_document_change_orders__change_order_id__documents__post:
properties:
document_type:
$ref: '#/components/schemas/ChangeOrderDocumentType'
description: 'Available values / Verfügbare Werte:
| Value | English | Deutsch |
| --- | --- | --- |
| `CHANGE_ORDER_OFFER` | Change order offer | Nachtragsangebot |
| `ATTACHMENT` | Attachment | Anhang |
| `COVERSHEET_EXTERNAL` | External coversheet | Externes Deckblatt |
| `AUDITED_CHANGE_ORDER` | Audited change order | Nachtragsprüfung |
| `INTERNAL_CORRESPONDENCE` | Internal correspondence | Interne Korrespondenz |
| `EXTERNAL_CORRESPONDENCE` | External correspondence | Externe Korrespondenz |
| `VALUATIONS` | Valuations | Aufmaß |
| `PLANS` | Plans | Planunterlagen |
| `CHANGE_ORDER` | Change order | Nachtragsbeauftragung |
| `PROTOCOL` | Protocol | Protokoll |
| `OTHER` | Other | Sonstiges |'
upload:
contentMediaType: application/octet-stream
description: '
The file to submit. The file must be a valid PDF.
'
title: Upload
type: string
required:
- document_type
- upload
title: Body_create_change_order_document_change_orders__change_order_id__documents__post
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:
title: Type
type: string
required:
- id
- type
title: BaseDataSchema
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
ChangeOrderDocumentAttributes:
properties:
document_type:
$ref: '#/components/schemas/ChangeOrderDocumentType'
description: '**Document type** · **Dokumentenart**
Available values / Verfügbare Werte:
| Value | English | Deutsch |
| --- | --- | --- |
| `CHANGE_ORDER_OFFER` | Change order offer | Nachtragsangebot |
| `ATTACHMENT` | Attachment | Anhang |
| `COVERSHEET_EXTERNAL` | External coversheet | Externes Deckblatt |
| `AUDITED_CHANGE_ORDER` | Audited change order | Nachtragsprüfung |
| `INTERNAL_CORRESPONDENCE` | Internal correspondence | Interne Korrespondenz |
| `EXTERNAL_CORRESPONDENCE` | External correspondence | Externe Korrespondenz |
| `VALUATIONS` | Valuations | Aufmaß |
| `PLANS` | Plans | Planunterlagen |
| `CHANGE_ORDER` | Change order | Nachtragsbeauftragung |
| `PROTOCOL` | Protocol | Protokoll |
| `OTHER` | Other | Sonstiges |'
filename:
description: '**Filename** · **Dateiname**'
title: Filename
type: string
uploaded_at:
description: '**Uploaded at** · **Hochgeladen am**'
format: date-time
title: Uploaded At
type: string
required:
- document_type
- filename
- uploaded_at
title: ChangeOrderDocumentAttributes
type: object
ChangeOrderDocumentResponse:
properties:
data:
anyOf:
- $ref: '#/components/schemas/ChangeOrderDocumentData'
- type: 'null'
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:
- additionalProperties:
anyOf:
- type: string
- type: 'null'
type: object
- type: 'null'
title: Links
title: ChangeOrderDocumentResponse
type: object
ChangeOrderDocumentListResponse:
properties:
data:
items:
$ref: '#/components/schemas/ChangeOrderDocumentData'
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:
- additionalProperties:
anyOf:
- type: string
- type: 'null'
type: object
- type: 'null'
title: Links
required:
- data
title: ChangeOrderDocumentListResponse
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