comstruct logo
API docs by Redocly

comstruct Public API (1.0.1)

Download OpenAPI specification:

comstruct ICT GmbH: [email protected] URL: https://comstruct.com License: Proprietary Terms of Service

The comstruct API is a comprehensive and flexible solution designed to streamline the process of procuring materials for businesses. This API provides a simple interface for developers to access and manage materials procurement data, including supplier information, deliveries and projects.

Getting Started

To gain access to the comstruct API, interested developers should reach out to their dedicated customer success manager. Our team of experts is committed to providing top-notch support and guidance to help you get the most out of our API.

Authentication

All API endpoints under /v1 require authentication using an API key passed in the X-API-Key header. Each API key has specific scopes that determine which endpoints and operations are available. Authentication is enforced through middleware that validates the API key and scopes for each request.

Calendar endpoints under /calendars use token-based authentication instead of API keys.

Data Formats

  • All timestamps are in ISO 8601 format (UTC)
  • Monetary amounts are represented as decimal numbers
  • IDs are UUIDs unless specified otherwise

Request Size Limits

  • PDF invoice processing, custom invoice processing and workflow processing: 32MiB
  • All other endpoints: 10MiB

Error Handling

The API uses standard HTTP status codes and returns detailed error messages in JSON format. See the error response schemas for more details.

Integration Patterns

  • SAP Integration: Specialized endpoints for SAP ERP systems
  • Project Management: Complete project lifecycle management with user roles
  • Delivery Tracking: Multiple delivery note formats supported (OpenTrans, 1Lieferschein, PAHM, Q-Point, custom)
  • Invoice Processing: Automated invoice parsing and validation with AI/GPT support
  • Order Management: IDS order processing with XML parsing and project calendar integration
  • Calendar Integration: Separate calendar endpoints for iCalendar subscription feeds

Deliveries

Endpoints related to deliveries.

List deliveries

Returns a paginated list of deliveries with filtered item fields.

Authorizations:
ApiKey
query Parameters
limit
integer [ 1 .. 100 ]
Default: 25
Example: limit=25

Number of items per page (max 100, default 25)

offset
integer >= 0
Default: 0
Example: offset=0

Number of items to skip for pagination

Responses

Response samples

Content type
application/json
{
  • "deliveries": [
    ],
  • "total": 150,
  • "limit": 25,
  • "offset": 0,
  • "hasNext": true,
  • "hasPrevious": false,
  • "totalPages": 6,
  • "currentPage": 0
}

Uploads a new delivery note

Authorizations:
ApiKey
Request Body schema: application/json
deliveryNumber
string

The reference number for the delivery. Must be unique for the supplier.

deliveryDate
string <date-time>

The reference number for the delivery. Must be unique for the supplier.

projectNumber
string

the project name that the delivery belongs to. Should contain the project number of the contractor for easy matching.

supplierId
string <uuid>

The id of the supplier that the delivery belongs to.

projectId
string <uuid>

The id of the project that the delivery belongs to.

vehicleNumber
string

The license plate number of the vehicle the delivery is brought with.

documentUrl
string <url>

A link to the delivery note document. Can be the full document, base64 encoded.

comment
string

An optional comment.

Array of objects (LineItem)

A list of items included in the delivery.

Responses

Request samples

Content type
application/json
{
  • "deliveryNumber": "1234'23",
  • "deliveryDate": "2019-08-24T14:15:22Z",
  • "projectNumber": "string",
  • "supplierId": "e01eb4c4-8eb9-4fb7-b625-61f58c6148db",
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  • "vehicleNumber": "M-AB 1234",
  • "documentUrl": "https://example.com/delivery-note.pdf",
  • "comment": "string",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "deliveryNumber": "1234'23",
  • "deliveryDate": "2019-08-24T14:15:22Z",
  • "projectNumber": "string",
  • "project": {
    },
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  • "vehicleNumber": "M-AB 1234",
  • "documentUrl": "https://example.com/delivery-note.pdf",
  • "comment": "string",
  • "items": [
    ]
}

Create a delivery with a custom format. Please contact comstruct for assistance with this endpoint.

Authorizations:
ApiKey
Request Body schema: */*
optional

Any request body is accepted

any

Responses

Request samples

Content type
*/*
Custom Format

Projects

Endpoints related to projects.

List projects

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "projects": [
    ]
}

Creates or updates a project

Creates a new project or updates an existing project. This endpoint performs an upsert operation based on the external_id field.

Key Features:

  • Upsert Logic: If a project with the given external_id exists, it will be updated. Otherwise, a new project is created.
  • User Management: Automatically handles user invitations and role assignments for project team members.
  • Region Mapping: The region field is used to lookup and link the project to the appropriate project region.
  • Validation: All required fields are validated before processing.

Required Scopes: This endpoint requires multiple scopes for full functionality:

  • projects:write - To create/update the project
  • users:read - To lookup existing users for invitations
  • roles:read - To validate and assign user roles
  • tenant_settings:read - To access tenant-specific configurations

Best Practices:

  • Use meaningful external_id values that are unique within your organization
  • Ensure region values correspond to existing project regions in your tenant
  • Include complete address information when available for better project management
Authorizations:
ApiKey
Request Body schema: application/json
required
external_id
required
string

The external identifier of the project. Must be unique within the customer.

title
required
string

The title of the project

project_number
required
string

The project number

description
string

A description of the project

region
required
string

The region number where the project is located, used for filtering

active
boolean

Controls if the project is active

object

The address details of the project

Array of objects (UserInviteInput)

User invites for the project

ordering_enabled
boolean

Indicates if ordering is enabled for the project

appscan_enabled
boolean

Indicates if app scan is enabled for the project

Responses

Request samples

Content type
application/json
Example
{
  • "external_id": "EXT-2024-001",
  • "title": "Highway Construction Project",
  • "project_number": "HCP-2024-001",
  • "description": "Construction of highway section A1-A2",
  • "region": "Bavaria",
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "external_id": "EXT-001",
  • "title": "Example Site",
  • "project_number": "23423420",
  • "description": "string",
  • "region": "Bavaria",
  • "project_region_id": "fd92bd5e-269f-4c52-94e7-9589c0bb014c",
  • "active": true,
  • "status": "string",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "address": {
    },
  • "ordering_enabled": true,
  • "appscan_enabled": true,
  • "project_invites": [
    ]
}

Retrieves a project by external ID

Authorizations:
ApiKey
path Parameters
external_id
required
string

The external identifier of the project

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "external_id": "EXT-001",
  • "title": "Example Site",
  • "project_number": "23423420",
  • "description": "string",
  • "region": "Bavaria",
  • "project_region_id": "fd92bd5e-269f-4c52-94e7-9589c0bb014c",
  • "active": true,
  • "status": "string",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "address": {
    },
  • "ordering_enabled": true,
  • "appscan_enabled": true,
  • "project_invites": [
    ]
}

Retrieves a project by project number

Authorizations:
ApiKey
path Parameters
project_number
required
string

The project number

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "external_id": "EXT-001",
  • "title": "Example Site",
  • "project_number": "23423420",
  • "description": "string",
  • "region": "Bavaria",
  • "project_region_id": "fd92bd5e-269f-4c52-94e7-9589c0bb014c",
  • "active": true,
  • "status": "string",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "address": {
    },
  • "ordering_enabled": true,
  • "appscan_enabled": true,
  • "project_invites": [
    ]
}

Project Regions

Endpoints for managing project regions.

List project regions

Returns a list of all project regions for the authenticated tenant. Project regions are used to organize and categorize projects within hierarchical structures.

Required Scopes: projects:read Authentication: API key must be linked to a customer.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "project_regions": [
    ]
}

Create a project region

Creates a new project region for organizing projects within the tenant.

Required Scopes: projects:write Authentication: API key must be linked to a customer. Validation: Title and number are required and must be unique within the tenant.

Key Features:

  • Unique Constraints: Both title and number must be unique per tenant
  • Auto-assignment: tenant_id is automatically set from the API key
Authorizations:
ApiKey
Request Body schema: application/json
required
title
required
string

The title of the project region

number
required
string

The number of the project region

Responses

Request samples

Content type
application/json
{
  • "title": "North Region",
  • "number": "NR-001"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "North Region",
  • "number": "NR-001",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Invoices

Endpoints related to invoices.

Process invoice in custom format

Processes a custom invoice format using GPT/AI parsing. Accepts raw data up to 32MiB and processes them using generative AI for invoice data extraction.

Required Scopes: invoices:write Authentication: API key must be linked to a customer and tenant ID must match.

Authorizations:
ApiKey
Request Body schema: */*
required
string <binary>

Raw invoice data (up to 32MiB)

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Process PDF invoice using AI

Processes PDF invoices using GPT/AI parsing. Accepts raw PDF data and processes them using generative AI for invoice data extraction.

Required Scopes: invoices:write Authentication: API key must be linked to a customer and tenant ID must match.

Authorizations:
ApiKey
Request Body schema: */*
required
string <binary>

Raw PDF invoice data

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Process invoice in OAWD format using AI

Processes a custom invoice format (OAWD) for Hochtief using GPT/AI parsing. Accepts PDF files and processes them using generative AI for invoice data extraction.

Required Scopes: invoices:write Authentication: API key must be linked to a customer.

Authorizations:
ApiKey
header Parameters
id
required
string

External ID for the invoice

Request Body schema: */*
required
string <binary>

Raw PDF invoice data

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": { }
}

Receive SAP invoice response callback

Receives callback responses from SAP system regarding invoice processing status. Updates the invoice status based on the success/failure response from SAP.

Authorizations:
ApiKey
Request Body schema: application/json
required
external_id
required
string

External ID of the invoice

success
required
boolean

Whether the SAP processing was successful

messages
Array of strings

Messages from SAP processing

Responses

Request samples

Content type
application/json
{
  • "external_id": "string",
  • "success": true,
  • "messages": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Parse invoice without saving to database

Parses an invoice PDF using AI/GPT but does not save the result to the database. This is useful for testing invoice parsing or getting invoice data without persistence. Returns parsed invoice data without creating database records.

Authorizations:
ApiKey
Request Body schema: */*
required
string <binary>

Raw invoice data to parse

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": { }
}

Purchase Orders

Endpoints related to purchase orders.

Create purchase orders from SAP system

Receives and processes purchase orders from SAP system. Accepts an array of SAP purchase orders as raw JSON data.

Required Scopes: purchase_orders:write Authentication: API key must be linked to a customer. Validation: All purchase orders must pass schema validation and reference existing suppliers.

Authorizations:
ApiKey
Request Body schema: */*
required
string

Raw request body that will be parsed as JSON array of SAP purchase orders

Responses

Request samples

Content type
*/*
Example
[{"number":"PO-2024-001","title":"Concrete Materials Order","creditor_number":"SUPPLIER-123456","payment_term":"30T","items":[{"number":"001","title":"Concrete C25/30","quantity":50,"cost_bearer_number":"PROJECT-KTR-789","unit":"m3","account_number":"ACC-4000","tax_code":"VAT19"}]}]

Response samples

Content type
application/json
{
  • "message": "Purchase Order data received successfully"
}

Orders

Endpoints for order processing and management.

Process IDS order

Processes an IDS order by updating an existing order with XML data and redirects to the project calendar. Accepts XML data in the 'warenkorb' field via form-urlencoded format.

Authorizations:
ApiKey
path Parameters
order_id
required
string <uuid>

The UUID of the order to update

Request Body schema: application/x-www-form-urlencoded
required
warenkorb
required
string

XML data containing the order information

Responses

Response samples

Content type
application/json
Example
{
  • "error": "Missing order_id"
}

Deliveries (Supplier)

Supplier-specific delivery endpoints.

Uploads a new delivery note

Authorizations:
ApiKey
Request Body schema: application/json
deliveryNumber
string

The reference number for the delivery. Must be unique for the supplier.

deliveryDate
string <date-time>

The reference number for the delivery. Must be unique for the supplier.

projectNumber
string

the project name that the delivery belongs to. Should contain the project number of the contractor for easy matching.

supplierId
string <uuid>

The id of the supplier that the delivery belongs to.

projectId
string <uuid>

The id of the project that the delivery belongs to.

vehicleNumber
string

The license plate number of the vehicle the delivery is brought with.

documentUrl
string <url>

A link to the delivery note document. Can be the full document, base64 encoded.

comment
string

An optional comment.

Array of objects (LineItem)

A list of items included in the delivery.

Responses

Request samples

Content type
application/json
{
  • "deliveryNumber": "1234'23",
  • "deliveryDate": "2019-08-24T14:15:22Z",
  • "projectNumber": "string",
  • "supplierId": "e01eb4c4-8eb9-4fb7-b625-61f58c6148db",
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  • "vehicleNumber": "M-AB 1234",
  • "documentUrl": "https://example.com/delivery-note.pdf",
  • "comment": "string",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "deliveryNumber": "1234'23",
  • "deliveryDate": "2019-08-24T14:15:22Z",
  • "projectNumber": "string",
  • "project": {
    },
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  • "vehicleNumber": "M-AB 1234",
  • "documentUrl": "https://example.com/delivery-note.pdf",
  • "comment": "string",
  • "items": [
    ]
}

Create a delivery from an OpenTrans Dispatch Note

Authorizations:
ApiKey
Request Body schema: application/xml
required
object

XML representation of the OpenTrans Dispatch Note

Responses

Create a delivery from an Pahm Weighing System Dispatch Note

Authorizations:
ApiKey
Request Body schema: application/json
required
dsid
string

The unique identifier of the delivery

Responses

Request samples

Content type
application/json
{
  • "dsid": "string"
}

Create a delivery with a custom format. Please contact comstruct for assistance with this endpoint.

Authorizations:
ApiKey
Request Body schema: */*
optional

Any request body is accepted

any

Responses

Request samples

Content type
*/*
Custom Format

Create a delivery from a 1Lieferschein XML format

Accepts deliveries in the 1Lieferschein XML format, processes the XML and creates a delivery record.

Authorizations:
ApiKey
Request Body schema: application/xml
required
string <binary>

XML data in 1Lieferschein format

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Create a delivery from Q-Point system

Receives a JSON delivery note from Q-Point system and creates a delivery record. Implements the Q-Point REST API V8 callback method for HTTP subscriptions.

Authorizations:
ApiKey
Request Body schema: application/json
required
object

Q-Point delivery data in JSON format

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "string"
}

Create a delivery from Q-Point PDF upload

Receives a PDF delivery note from Q-Point system via file upload.

Authorizations:
ApiKey
Request Body schema: multipart/form-data
required
deliveryNote
string <binary>

PDF file containing the delivery note

Responses

Invoices (Supplier)

Supplier-specific invoice endpoints.

Process invoice in custom format

Processes a custom invoice format using GPT/AI parsing. Accepts raw data up to 32MiB and processes them using generative AI for invoice data extraction.

Required Scopes: invoices:write Authentication: API key must be linked to a customer and tenant ID must match.

Authorizations:
ApiKey
Request Body schema: */*
required
string <binary>

Raw invoice data (up to 32MiB)

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Process PDF invoice using AI

Processes PDF invoices using GPT/AI parsing. Accepts raw PDF data and processes them using generative AI for invoice data extraction.

Required Scopes: invoices:write Authentication: API key must be linked to a customer and tenant ID must match.

Authorizations:
ApiKey
Request Body schema: */*
required
string <binary>

Raw PDF invoice data

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Process invoice in OAWD format using AI

Processes a custom invoice format (OAWD) for Hochtief using GPT/AI parsing. Accepts PDF files and processes them using generative AI for invoice data extraction.

Required Scopes: invoices:write Authentication: API key must be linked to a customer.

Authorizations:
ApiKey
header Parameters
id
required
string

External ID for the invoice

Request Body schema: */*
required
string <binary>

Raw PDF invoice data

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": { }
}

Purchase Orders (SAP)

SAP-specific purchase order endpoints.

Create purchase orders from SAP system

Receives and processes purchase orders from SAP system. Accepts an array of SAP purchase orders as raw JSON data.

Required Scopes: purchase_orders:write Authentication: API key must be linked to a customer. Validation: All purchase orders must pass schema validation and reference existing suppliers.

Authorizations:
ApiKey
Request Body schema: */*
required
string

Raw request body that will be parsed as JSON array of SAP purchase orders

Responses

Request samples

Content type
*/*
Example
[{"number":"PO-2024-001","title":"Concrete Materials Order","creditor_number":"SUPPLIER-123456","payment_term":"30T","items":[{"number":"001","title":"Concrete C25/30","quantity":50,"cost_bearer_number":"PROJECT-KTR-789","unit":"m3","account_number":"ACC-4000","tax_code":"VAT19"}]}]

Response samples

Content type
application/json
{
  • "message": "Purchase Order data received successfully"
}

Suppliers (SAP)

SAP-specific supplier endpoints.

Create suppliers from SAP system

Receives and processes suppliers from SAP system. Accepts an array of SAP suppliers as raw data.

Required Scopes: suppliers:write Authentication: API key must be linked to a customer. Validation: All suppliers must have valid payment terms and pass schema validation.

Authorizations:
ApiKey
Request Body schema: application/json
required
Array
number
required
string

Supplier number from SAP

title
required
string

Supplier name/title

legal_uid
string

Optional legal UID

country_code
required
string

ISO 3166-1 alpha-2 country code

payment_term
required
string

SAP payment terms key; must exist in comstruct tenant

wth_tax_code
string

Optional withholding tax code

Array of objects (SapSupplierBankDetailsInput)

Optional bank details

object (SapSupplierAddressInput)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "message": "Supplier data received successfully"
}

Invoices (SAP)

SAP-specific invoice endpoints.

Receive SAP invoice response callback

Receives callback responses from SAP system regarding invoice processing status. Updates the invoice status based on the success/failure response from SAP.

Authorizations:
ApiKey
Request Body schema: application/json
required
external_id
required
string

External ID of the invoice

success
required
boolean

Whether the SAP processing was successful

messages
Array of strings

Messages from SAP processing

Responses

Request samples

Content type
application/json
{
  • "external_id": "string",
  • "success": true,
  • "messages": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Baubit Integration

Endpoints for Baubit system integration.

List deliveries for Baubit integration

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
Example
{
  • "message": "Invalid scope."
}

Update a delivery for Baubit integration

Authorizations:
ApiKey
path Parameters
id
required
string

The delivery ID

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
Example
{
  • "message": "Invalid scope."
}

List delivery places for Baubit integration

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
Example
{
  • "message": "Invalid scope."
}

Create a delivery place for Baubit integration

Authorizations:
ApiKey
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "error": 403,
  • "message": "Invalid scope."
}

Workflows

Endpoints for workflow and process management.

Trigger workflow processing

Triggers invoice processing workflow for JobRouter integration.

Required Scopes: invoices:write Authentication: API key must be linked to a customer.

Authorizations:
ApiKey
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "success": true
}

Get workflow status by external ID

Retrieves the current status of a workflow process by external identifier.

Required Scopes: invoices:write Authentication: API key must be linked to a customer.

Authorizations:
ApiKey
path Parameters
external_id
required
string

The external identifier of the workflow

Responses

Response samples

Content type
application/json
{}

Calendar

Calendar subscription endpoints with separate authentication.

Get calendar subscription

Retrieves an iCalendar (.ics) file containing calendar events for a subscription. Uses calendar authentication middleware instead of standard API key authentication.

Authorizations:
CalendarAuth

Responses

Response samples

Content type
text/calendar
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//comstruct//EN
END:VCALENDAR