{
"openapi": "3.0.1",
"info": {
"title": "Digital Terrain Logistics Standard - Technical Guide",
"description": "\r\n## Introduction\r\n\r\nThe DTLS API is a REST API for getting documents like invoices, delivery notes scanned or uploaded. \r\n\r\nThe products used on the documents like delivery note are also can listed by the API.\r\n\r\n## Quickstart\r\n\r\nTo access the API, you will need a way to authenticate. The simplest way to do this is with an API key.\r\n\r\nTo get an API key to the sandbox server, contact us at [hello@bauapp.com](mailto:hello@bauapp.com).\r\n\r\nThe sandbox server is a test environment where you can freely experiment with the API. It's available at https://dtlsscan.mobilengine.com/.\r\n__Do not store live data on the sandbox server. The sandbox server is meant to be used while developing an API client. Data on the sandbox server is removed periodically, without notice.__\r\n\r\nAfter acquiring an API key, download the *swagger.json* file containing the API specification with the *Download* button at te top of this document.\r\n\r\nYou can open the *swagger.json* file with a number of REST client tools, like *Postman* or *Insomnia*.\r\n\r\nYou'll need to set up the base URL of the service to https://dtlsscan.mobilengine.com/ and set the authorization header to look like this:\r\n\r\n```\r\nAuthorization: Bearer $ApiKey\r\n```\r\n\r\nReplace *$ApiKey* with your API key.\r\n\r\nYou should be able to make API requests now.\r\n\r\n## Security\r\n\r\nThe API is only accessible through HTTPS.\r\n\r\nAccess to the API is only allowed when the request contains an API key or a client certificate.\r\n\r\nRequests without valid authentication will result in a `HTTP 401: Unauthorized` or a `HTTP 403: Forbbidden` response code.\r\nThese can happen if your API key/client certificate is not known, or you don't have the rights to a resource (it belongs to another company).\r\n\r\nThere are no fine-grained access rights, a valid API key/client certificate allows clients to perform all operations through the API.\r\n\r\nThe IP addresses from where API access is allowed can be restricted, contact us for details.\r\n\r\n### API Key Authentication\r\n\r\nThe API key must be sent in the HTTP Authorization header, with the Bearer authentication scheme:\r\n\r\n```\r\nAuthorization: Bearer MyApiKey123\r\n```\r\n\r\nOn the live instance (https://api.bauapp.com), administering API keys is done through your company's BauApp web interface.\r\n\r\nApi keys for the sandbox server can be requested at [hello@bauapp.com](mailto:hello@bauapp.com).\r\n\r\n### Client Certificate Authentication\r\n\r\nTLS client certificates can be used as an alternative to the API key authentication mechanism.\r\n\r\nThe client certificate must be a valid certificate issued by a certificate authority.\r\nThe certificate must include the *Client Authentication (1.3.6.1.5.5.7.3.2)* OID in the *Extended key usage* field.\r\n\r\nYou'll need to send us the thumbprint (aka. fingerprint) of your certificate, so that we can associate it with your company.\r\n\r\n## Main use case\r\n### AI Scan documents and products retrival\r\n1. Get delivery note or other document data from certain timeframe\r\n2. Get delivery note or other document changes from certain timeframe\r\n3. Get document product data from certain timeframe\r\n4. Get document product changes data from certain timeframe\r\n5. Getting document pdf\r\n\r\n## API Conventions\r\n\r\n### Message format\r\nThe API consumes and produces JSON messages, with the exception of the QR code endpoint, which returns an image.\r\n\r\nThe encoding of the JSON messages must be UTF-8.\r\n\r\nDate fields are formatted like `2020-12-31` according to OpenAPI specs.\r\nDatetime values are formatted like `2020-12-31T23:59:59Z` for UTC datetimes, and `2020-12-31T23:59:59+02:00` for datetimes with an offset.\r\n\r\nSee [http://spec.openapis.org/oas/v3.0.3#data-types](http://spec.openapis.org/oas/v3.0.3#data-types) for the specification details.\r\n\r\n### Paging\r\n\r\nSome endpoints can potentially return a large number of objects, for example the `/products` endpoint.\r\n\r\nThese endpoints only return a _page_ of objects at once. To receive the next page, \r\ncall the same endpoint with a `from` parameter. The from parameter should contain the last\r\nidentifier received in the previous endpoint request. The response for this reques will \r\ncontain objects starting with (but not including) the object identified in the `from` parameter.\r\n\r\nTo read all objects, proceed to do this in a loop until you get an empty response.\r\n\r\nThe `from` field must contain the id of an existing object, otherwise a HTTP 404 error occurs.\r\n\r\n#### Example: Reading all products\r\n\r\n1. Make a GET request to /products, let's say you receive this page (product details are omitted for the example):\r\n> [\r\n> { id: 'p34' },\r\n> { id: 'p67' },\r\n> { id: 'p23' }\r\n> ]\r\n\r\n2. Make a GET request with the last ID to `/products?from=p23`, receive this page:\r\n> [\r\n> { id: 'p11' },\r\n> { id: 'p76' }\r\n> ]\r\n\r\nNote that the product with ID p23 is not included in this page.\r\n\r\n3. Make a GET request with the last ID to `/products?from=p76`, receive this page:\r\n> []\r\n\r\n4. Since the response is an empty list you're done querying all products\r\n\r\n### String length restrictions\r\n\r\nString length restrictions specified on fields are to be interpreted as the \r\nnumber of bytes in the UTF-8 encoded string, not as unicode character count.\r\n\r\nSo the length specified only applies if you don't use any multibyte characters.\r\n\r\n### HTTP version requirements\r\n\r\nThe API requires the use of HTTP/1.1, HTTP/2 and newer protocols are not supported.\r\n\r\nIf a request doesn't use HTTP/1.1, a HTTP 426 error code will be returned.\r\n\r\n## Getting notifications of document creation or status updates\r\n\r\nIt's possible to configure the DTLS API server to send an HTTP request to your servers when a document is received, modified or deleted.\r\n\r\nWhen the document is recevied, these two requests are sent:\r\n\r\n* a `POST` request to `{your-url}?content=document`, with the body containing the delivery note JSON\r\n\r\nThe `{your-url}` placeholder can be configured to anything you like.\r\nDocuments notifications can be filtered by document type, project or supplier.\r\nNotifications can be sent for created, updated and deleted documents, but not necessary all.\r\n\r\nAuthorization can be performed with any HTTP Authorization header or with a TLS client certificate.\r\n\r\nIf you'd like to use this feature, contact us.\r\n\r\n## API Limitations\r\n\r\n### Data retention\r\nThe production server keeps products and delivery notes indefinitely. \r\nThis may change in future implementations of the API.\r\n\r\nThe data on the sandbox server is removed on a regular basis, without prior notice.\r\n\r\n### Rate limiting\r\nRate limiting is based on the provided API key.\r\nIf too many requests are sent in a period of time the server responds with HTTP 429 messages.\r\n\r\nExplicit rate limit values are to be determined later.\r\n\r\nRate limits on the sandbox server may be stricter than on the production server.\r\n\r\nIf you exceed the rate limit, a `HTTP 429: Too many requests` result is returned.\r\n\r\n### Request size\r\nThe request body size of create (POST) operations is limited. Currently all requests sizes are limited to 256KiB.\r\n\r\nIf you send a larger request, you'll receive a `HTTP 413: Payload too large` response.\r\n\r\n## Generating client code\r\n\r\nThe OpenAPI specification (the *swagger.json* file) can be used to generate API client code for many different programming languages.\r\n\r\nTo download the *swagger.json* for the API using the `download` button at the top of this document.\r\n\r\nFor information about how to generate clients from the specification see the [OpenAPI Generator Homepage.](https://openapi-generator.tech/)\r\n",
"contact": {
"name": "BauApp",
"url": "https://dtlsscan.mobilengine.com/api",
"email": "hello@bauapp.com"
},
"version": "v32"
},
"servers": [
{
"url": "https://dtlsscan.mobilengine.com/",
"description": "Testing"
},
{
"url": "https://api.bauapp.com/",
"description": "Production"
}
],
"paths": {
"/api/v29/delivery_notes": {
"post": {
"tags": [
"Delivery Notes"
],
"summary": "Create a new delivery note",
"description": "The delivery note with the specified id must not exist yet.\n\nThe API doesn't allow updating delivery notes after creation, you can just create a new note if a created note contains an error.\n\nThis API call can also create the products used on the delivery note, see the description of `items`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiNewDeliveryNote"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiNewDeliveryNote"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ApiNewDeliveryNote"
}
}
}
},
"responses": {
"201": {
"description": "The delivery note was created. The created delivery note is returned in the response body.The Location header in the response is set to the URL of the created delivery note.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiDeliveryNote"
}
}
}
},
"400": {
"description": "An invalid delivery note was specified in the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "An delivery note with this ID already exists.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"413": {
"description": "The request is too large.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"get": {
"tags": [
"Delivery Notes"
],
"summary": "List delivery notes",
"description": "Returns delivery notes.\nThe delivery notes are ordered so that the first ones are the ones that are most recently made available to be queried through the API.This way when polling for new orders, you should only need to check the first page(s).This ordering is not necessarily the same as a descending ordering by `creationDate`, because delivery notes created through the web UI may take longer to be visible through the API.\n\nThe endpoint uses paging, so it doesn't return all delivery notes at once.\n\nTo get the next page of notes call the endpoint with the `fromUuid` parameter, using the ID of the oldest (last) note that you received.",
"parameters": [
{
"name": "fromUuid",
"in": "query",
"description": "The result will only contain items starting at (but not including) this one.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiDeliveryNote"
}
}
}
}
},
"404": {
"description": "The delivery note specified in the `fromUuid` field cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/delivery_notes/create_and_get_qr_code": {
"post": {
"tags": [
"Delivery Notes"
],
"summary": "Create a new delivery note and return its QR code",
"description": "Creates a new delivery note and immediately returns its QR code as a PNG image.\n\nThis is a hybrid shortcut combining the `POST /delivery_notes` and `GET /delivery_notes/{uuid}/qr_code` calls into one.\n\nThe same validation rules apply as when creating a delivery note normally.",
"parameters": [
{
"name": "useEncryption",
"in": "query",
"description": "Whether to encrypt the QR code payload. Defaults to true. When false, the payload is only compressed but not encrypted, and no encryption key is required.",
"schema": {
"type": "boolean",
"default": true
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiNewDeliveryNote"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiNewDeliveryNote"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ApiNewDeliveryNote"
}
}
}
},
"responses": {
"201": {
"description": "The QR code PNG for the newly created delivery note."
},
"400": {
"description": "An invalid delivery note was specified in the request.",
"content": {
"image/png": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"412": {
"description": "No valid QR code signing key is configured (or encryption key when useEncryption is true).",
"content": {
"image/png": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "A delivery note with this ID already exists.",
"content": {
"image/png": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"413": {
"description": "The request is too large.",
"content": {
"image/png": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/delivery_notes/search": {
"get": {
"tags": [
"Delivery Notes"
],
"summary": "Search delivery notes",
"description": "Currently the search only supports finding delivery notes by the `supplierId`\n\nThe response contains all matches, no paging is used.\n\nIn rare cases there may be more than one delivery notes with the same supplierId.\n\nFor example when you're a haulier company and you have access to many companies delivery notes, and two happen to share the same supplierId.",
"parameters": [
{
"name": "supplierId",
"in": "query",
"description": "The supplier's identifier of the delivery note, as supplied in the `supplierId` field when creating the delivery note.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The delivery notes matching the search criteria, or an empty list if no matching delivery notes were found.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiDeliveryNote"
}
}
}
}
}
}
}
},
"/api/v29/delivery_notes/{uuid}": {
"get": {
"tags": [
"Delivery Notes"
],
"summary": "Get a delivery note by UUID",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The UUID of the delivery note.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The requested delivery note",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiDeliveryNote"
}
}
}
},
"400": {
"description": "The uuid is not in the correct format",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "No delivery note was found with the specified uuid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"patch": {
"tags": [
"Delivery Notes"
],
"summary": "Update delivery note fields",
"description": "Update the QR-code-relevant fields of an existing delivery note.\n\nAll fields are optional — only the supplied fields will be overwritten. Omitted fields keep their current value.\n\nItem updates are identified by the 1-based sequence number of the item on the delivery note. Product-level fields (name, unit, manufacturer, etc.) are updated on the underlying product entity.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The UUID of the delivery note.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiUpdateDeliveryNote"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiUpdateDeliveryNote"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ApiUpdateDeliveryNote"
}
}
}
},
"responses": {
"200": {
"description": "The delivery note was updated. Returns the updated delivery note.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiDeliveryNote"
}
}
}
},
"400": {
"description": "The request is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "The delivery note with the specified UUID was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/delivery_notes/{uuid}/qr_code": {
"get": {
"tags": [
"Delivery Notes"
],
"summary": "Get the QR code for a delivery note",
"description": "Returns an image of a QR code containing a link to the delivery note.\n\nYou can include this image on your own documents, and the QR code can be scanned with the mobile app during delivery.\n\n**Try to print the QR code as large as you can. This will make scanning easier and will also protect against damage and staining.**\n**We recommend at least 4cm by 4cm.**",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The uuid of the delivery note the create the QR code from.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "useEncryption",
"in": "query",
"description": "Whether to encrypt the QR code payload. Defaults to true. When false, the payload is only compressed but not encrypted, and no encryption key is required.",
"schema": {
"type": "boolean",
"default": true
}
}
],
"responses": {
"200": {
"description": "The QR code in PNG format.\n\nThe exact size of the image is undefined.\n\nThe QR code contains the same URI that is in the `qrCodeContent` field of the delivery note."
},
"404": {
"description": "The delivery note with the speified id was not found",
"content": {
"image/png": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"412": {
"description": "No valid QR code signing key is configured (or encryption key when useEncryption is true).",
"content": {
"image/png": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/delivery_notes/{uuid}/receipt": {
"get": {
"tags": [
"Delivery Notes"
],
"summary": "Get the receipt PDF for a delivery note",
"description": "Download the receipt for the delivery note - a .pdf report confirming the delivery, with comments and information supplied by the recipient.\n\nOnly available after the delivery note was received, see the `status` field on the delivery note.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The uuid of the delivery note.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The delivery note PDF"
},
"404": {
"description": "The delivery note with the speified id was not found, or it's not in the `received` state yet.",
"content": {
"application/pdf": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/delivery_notes/{uuid}/encoded_data": {
"get": {
"tags": [
"Delivery Notes"
],
"summary": "Get the full encoded delivery note data",
"description": "Returns the **complete** (never truncated) delivery note payload in compressed and base64url-encoded form, along with the supplier identifier and an optional ECDSA signature.\n\nUnlike the QR code — which may drop items to fit a size limit — this endpoint always includes every item.\n\nThe response contains the same fields that appear on the QR code URL (`is`, `dn`, `sig`).",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The uuid of the delivery note.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "useEncryption",
"in": "query",
"description": "Whether to encrypt the QR code payload. Defaults to true. When false, the payload is only compressed but not encrypted, and no encryption key is required.",
"schema": {
"type": "boolean",
"default": true
}
}
],
"responses": {
"200": {
"description": "The encoded delivery note data.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EncodedDeliveryNoteResponse"
}
}
}
},
"404": {
"description": "The delivery note with the specified id was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"412": {
"description": "No valid QR code signing key is configured (or encryption key when useEncryption is true).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/delivery_notes/receive": {
"post": {
"tags": [
"Delivery Notes"
],
"summary": "Receive a delivery note",
"description": "Administrate the reception (acceptance) of a delivery note by submitting the scanned QR code content together with reception details, optional item quantity modifications, haulier/transport data, supplier, customer, and delivery information.\n\nThe `haulierNumberplate` field is mandatory.\n\nItem quantity modifications are identified by the 1-based sequence number of the item on the delivery note.\n\nUse the optional `forwardTo` field to specify where the reception notification should be sent: `Supplier`, `Builder`, or `Both`. If omitted, no notification is forwarded.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiDeliveryNoteReception"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiDeliveryNoteReception"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ApiDeliveryNoteReception"
}
}
}
},
"responses": {
"200": {
"description": "The reception was successfully recorded. The updated delivery note is returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiDeliveryNote"
}
}
}
},
"400": {
"description": "The request is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "The delivery note referenced by the QR code was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "The delivery note has already been received.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"413": {
"description": "The request is too large.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/delivery_notes/{uuid}/reception_photos": {
"post": {
"tags": [
"Delivery Notes"
],
"summary": "Upload reception photos for a delivery note",
"description": "Upload one or more photos taken during the reception of a delivery note.\n\nTwo categories of photos are supported:\n- **vehicle** – photo of the delivery vehicle and its license plate\n- **cargo** – photo of the cargo / shipment\n\nEach file must be a JPEG or PNG image. Multiple files can be uploaded in a single request.\nThe `type` form field must be provided for each file (`vehicle` or `cargo`).",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The UUID of the delivery note.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"files": {
"type": "array",
"items": {
"type": "string",
"format": "binary"
}
},
"type": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"encoding": {
"files": {
"style": "form"
},
"type": {
"style": "form"
}
}
}
}
},
"responses": {
"201": {
"description": "The photos were saved. Returns the list of saved photo metadata.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReceptionPhotoInfo"
}
}
}
}
},
"400": {
"description": "No files were provided, an unsupported file type was uploaded, or the type is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "The delivery note with the specified UUID was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"413": {
"description": "One of the uploaded files exceeds the size limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"get": {
"tags": [
"Delivery Notes"
],
"summary": "List reception photos for a delivery note",
"description": "Returns metadata for all photos uploaded during the reception of a delivery note.\nUse the photo id with the download endpoint to retrieve the actual image data.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The UUID of the delivery note.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The list of reception photo metadata.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReceptionPhotoInfo"
}
}
}
}
},
"404": {
"description": "The delivery note with the specified UUID was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/delivery_notes/{uuid}/reception_photos/{photoId}": {
"get": {
"tags": [
"Delivery Notes"
],
"summary": "Download a reception photo",
"description": "Returns the image data of a single reception photo by its id.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The UUID of the delivery note.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "photoId",
"in": "path",
"description": "The id of the photo.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The photo image data."
},
"404": {
"description": "The delivery note or the photo was not found.",
"content": {
"image/jpeg": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"image/png": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/documents/{uuid}": {
"get": {
"tags": [
"Documents"
],
"summary": "Get a document by UUID",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The UUID of the document.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The requested document",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiDocument"
}
}
}
},
"400": {
"description": "The uuid is not in the correct format",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "No document was found with the specified uuid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"410": {
"description": "Document with uuid was deleted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"patch": {
"tags": [
"Documents"
],
"summary": "Update document fields",
"description": "Update the QR-code-relevant fields of an existing document.\n\nAll fields are optional — only the supplied fields will be overwritten. Omitted fields keep their current value.\n\nUpdatable header fields: supplier (name, warehouse, tax number, address), customer (name, address), delivery (address, recipient name), issue date, order number, document number, document type, reference number, project (name, code), total price, currency, and comment.\n\nItem updates are identified by the 1-based sequence number of the item on the document.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The UUID of the document.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiUpdateDocument"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiUpdateDocument"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ApiUpdateDocument"
}
}
}
},
"responses": {
"200": {
"description": "The document was updated. Returns the updated document.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiDocument"
}
}
}
},
"400": {
"description": "The request is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "The document with the specified UUID was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/documents": {
"get": {
"tags": [
"Documents"
],
"summary": "List documents for search criteria",
"description": "The documents are in descending order of creation.The endpoint uses paging, so it doesn't return all documents at once.\n\nTo get the next page of notes call the endpoint with the `fromUuid` parameter, using the ID of the oldest (last) note that you uploaded.",
"parameters": [
{
"name": "fromUuid",
"in": "query",
"description": "The result will only contain items starting at (but not including) this one.",
"schema": {
"type": "string"
}
},
{
"name": "project",
"in": "query",
"description": "Documents in project",
"schema": {
"type": "string"
}
},
{
"name": "supplierName",
"in": "query",
"description": "Documents from supplier",
"schema": {
"type": "string"
}
},
{
"name": "documentNumber",
"in": "query",
"description": "Documents with document (e.g. delivery note or invoice) number",
"schema": {
"type": "string"
}
},
{
"name": "orderNumber",
"in": "query",
"description": "Documents with order number",
"schema": {
"type": "string"
}
},
{
"name": "agreementNumber",
"in": "query",
"description": "Documents with agreement number",
"schema": {
"type": "string"
}
},
{
"name": "referenceNumber",
"in": "query",
"description": "Documents with reference number",
"schema": {
"type": "string"
}
},
{
"name": "documentType",
"in": "query",
"description": "Documents with type, \"Delivery Note\" or \"Invoice\"",
"schema": {
"type": "string"
}
},
{
"name": "issuedFrom",
"in": "query",
"description": "Documents issued from this date",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "issuedTo",
"in": "query",
"description": "Documents issued to this date",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "uploadedFrom",
"in": "query",
"description": "Documents uploaded from this date",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "uploadedTo",
"in": "query",
"description": "Documents uploaded to this date",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "updatedFrom",
"in": "query",
"description": "Documents updated from this date",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "updatedTo",
"in": "query",
"description": "Documents updated to this date",
"schema": {
"type": "string",
"format": "date-time"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiDocument"
}
}
}
}
},
"404": {
"description": "The document specified in the `fromUuid` field cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/documents/changes": {
"get": {
"tags": [
"Documents"
],
"summary": "List document changes in a date range",
"description": "Returns changed documents.\nDescending order of document creation.The endpoint uses paging, so it doesn't return all documents at once.\n\nTo get the next page of notes call the endpoint with the `fromUuid` parameter, using the ID of the oldest (last) note that you uploaded.",
"parameters": [
{
"name": "fromUuid",
"in": "query",
"description": "The result will only contain items starting at (but not including) this one.",
"schema": {
"type": "string"
}
},
{
"name": "project",
"in": "query",
"description": "Documents in project",
"schema": {
"type": "string"
}
},
{
"name": "supplierName",
"in": "query",
"description": "Supplier name",
"schema": {
"type": "string"
}
},
{
"name": "documentType",
"in": "query",
"description": "Documents with type like \"Delivery Note\" or \"Invoice\"",
"schema": {
"type": "string"
}
},
{
"name": "updatedFrom",
"in": "query",
"description": "Documents updated from this date",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "updatedTo",
"in": "query",
"description": "Documents updated to this date",
"schema": {
"type": "string",
"format": "date-time"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiDocumentChange"
}
}
}
}
},
"404": {
"description": "The document specified in the `fromUuid` field cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/documents/{uuid}/pdf": {
"get": {
"tags": [
"Documents"
],
"summary": "Get the PDF file for a document",
"description": "Download the pdf for the document.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The uuid of the document.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The document PDF"
},
"404": {
"description": "The document with the speified id was not found.",
"content": {
"application/pdf": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/documents/upload": {
"post": {
"tags": [
"Documents"
],
"summary": "Upload a document file",
"description": "Upload a JPEG or PDF file to create a new document, or replace the file of an existing one.\n\nWhen `replaceDocumentId` is omitted a new document is created and **201 Created** is returned.\n\nWhen `replaceDocumentId` is provided the file of the existing document is replaced, its status is set to **Updated**, and **200 OK** is returned.",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"replaceDocumentId": {
"type": "string"
}
}
},
"encoding": {
"file": {
"style": "form"
},
"replaceDocumentId": {
"style": "form"
}
}
}
}
},
"responses": {
"201": {
"description": "New document created. Basic administration data is returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiDocumentUploadResult"
}
}
}
},
"200": {
"description": "Existing document file replaced. Basic administration data is returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiDocumentUploadResult"
}
}
}
},
"400": {
"description": "No file was provided or the file type is not JPEG or PDF.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "The document specified in replaceDocumentId was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"413": {
"description": "The uploaded file exceeds the size limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/documents/{uuid}/reception": {
"post": {
"tags": [
"Documents"
],
"summary": "Add reception data to a document",
"description": "Record reception (acceptance) details for an existing document.\n\nFields include: which construction diary the receipt was recorded in, when the receipt was administratively and physically processed, which user received the delivery, a free-text comment, and the delivery direction (In/Out).",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The UUID of the document.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiDocumentReception"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiDocumentReception"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ApiDocumentReception"
}
}
}
},
"responses": {
"200": {
"description": "The reception data was saved. The updated document is returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiDocument"
}
}
}
},
"400": {
"description": "The request is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "The document with the specified UUID was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/documents/{uuid}/reception/photos": {
"post": {
"tags": [
"Documents"
],
"summary": "Upload reception photos for a document",
"description": "Upload one or more photos taken during the reception of a document.\n\nTwo categories of photos are supported:\n- **vehicle** – photo of the delivery vehicle and its license plate\n- **cargo** – photo of the cargo / shipment\n\nEach file must be a JPEG or PNG image. Multiple files can be uploaded in a single request.\nThe `type` form field must be provided for each file (`vehicle` or `cargo`).\n\nThe document must already have reception data (created via the `POST {uuid}/reception` endpoint).",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The UUID of the document.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"files": {
"type": "array",
"items": {
"type": "string",
"format": "binary"
}
},
"type": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"encoding": {
"files": {
"style": "form"
},
"type": {
"style": "form"
}
}
}
}
},
"responses": {
"201": {
"description": "The photos were saved. Returns the list of saved photo metadata.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReceptionPhotoInfo"
}
}
}
}
},
"400": {
"description": "No files were provided, an unsupported file type was uploaded, or the type is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "The document or its reception data was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"413": {
"description": "One of the uploaded files exceeds the size limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"get": {
"tags": [
"Documents"
],
"summary": "List reception photos for a document",
"description": "Returns metadata for all photos uploaded during the reception of a document.\nUse the photo id with the download endpoint to retrieve the actual image data.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The UUID of the document.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The list of reception photo metadata.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReceptionPhotoInfo"
}
}
}
}
},
"404": {
"description": "The document or its reception data was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/documents/{uuid}/reception/photos/{photoId}": {
"get": {
"tags": [
"Documents"
],
"summary": "Download a document reception photo",
"description": "Returns the image data of a single reception photo by its id.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "The UUID of the document.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "photoId",
"in": "path",
"description": "The id of the photo.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "The photo image data."
},
"404": {
"description": "The document, reception, or photo was not found.",
"content": {
"image/jpeg": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"image/png": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/keys": {
"get": {
"tags": [
"QR Code Keys"
],
"summary": "List keys",
"description": "List QR code encryption and signing keys.\n\nThe result only contains a fixed number of keys.\nTo get the next batch of keys, use the `idFrom` parameter.\nRepeat these steps until the result is an empty array, that means there are no more keys to retrieve.\nIf the specified idFrom is not found, the keys are returned from the start as if the parameter were missing.",
"parameters": [
{
"name": "idFrom",
"in": "query",
"description": "The id of the key to start the listing from (it will not be included in the response)",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiKey"
}
}
}
}
}
}
}
},
"/api/v29/keys/qr-signing": {
"post": {
"tags": [
"QR Code Keys"
],
"summary": "Upload a signing key",
"description": "Upload a public key of a keypair that will be used to sign QR codes.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiQrSigningKey"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiQrSigningKey"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ApiQrSigningKey"
}
}
}
},
"responses": {
"201": {
"description": "The key was successfully uploaded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiKey"
}
}
}
},
"400": {
"description": "The request body is invalid. Check the error message for details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "The maximum number of valid keys has been reached. Re-upload the key after some time, when the existing keys have expired.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/keys/qr-encryption": {
"post": {
"tags": [
"QR Code Keys"
],
"summary": "Generate an encryption key",
"description": "Generate the secret string used to encrypt delivery note data in QR codes.\n",
"responses": {
"200": {
"description": "The encryption key was successfully generated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiEncryptionKey"
}
}
}
},
"409": {
"description": "The maximum number of valid keys have been reached. Re-upload the key after some time, when the existing keys have expired.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/keys/{id}": {
"delete": {
"tags": [
"QR Code Keys"
],
"summary": "Delete a key",
"description": "Delete a key by its id.\n\nThis can be used to revoke keys before their expiration date.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The id of the key to delete",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The key was successfully deleted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiKey"
}
}
}
},
"404": {
"description": "The key with that id was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/keys/feed": {
"get": {
"tags": [
"QR Code Keys"
],
"summary": "Key synchronization feed",
"description": "Get the keys modified after the specified date.\nThis can be used by clients to synchronize known keys.\n\nClients should use the date parameter to only get the keys modified since the last synchronization.\nThe result will contain all keys which were created or modified after the specified date.\nClients should use the key identifiers to update the modified keys in their local key store.\n\nClients are expected to call this endpoint regularly: about once every hour, to get notified of deleted keys early.\n\nClients should query all keys initially with the `/keys` endpoint, and only use this to update that list.",
"parameters": [
{
"name": "date",
"in": "query",
"description": "Date to get the changed keys from. Must be an UTC date in YYYY-MM-DDTHH:mm:ssZ format.",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
}
}
],
"responses": {
"200": {
"description": "All changed keys returned in the response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiKey"
}
}
}
}
},
"206": {
"description": "Only a part of the changed keys returned in the response. This can happen if there are too many changes since the specified date. Clients should call this endpoint again with a later date to get the next batch of changes."
}
}
}
},
"/api/v29/products": {
"post": {
"tags": [
"Products"
],
"summary": "Create a new product",
"description": "Register a new product, so that it can later be referenced in delivery notes.\n\nModifying the properties of a product after creation is not supported for now.\n\nIt's strongly recommended to provide the `eanCode` or the `manufacturerItemNumber` values in the request. If these fields match an existing product, no new product will be created.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiNewProduct"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiNewProduct"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/ApiNewProduct"
}
}
}
},
"responses": {
"201": {
"description": "The product was created.The created product is returned in the response body.The Location header in the response is set to the URL of the product.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiProduct"
}
}
}
},
"202": {
"description": "The same product already exists.\nThe existing product is returned in the response body.The Location header in the response is set to the URL of the existing product.The server attempts to find an already existing product, by checking the `eanCode` and `mManufacturerItemNumber` fields.If a field matches, the id of that exsiting product is returned instead of creating a new product.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiProduct"
}
}
}
},
"400": {
"description": "Invalid product specified",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"413": {
"description": "The request is too large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
"get": {
"tags": [
"Products"
],
"summary": "List products",
"description": "List products that are registered for your company.\n\nThe products are ordered so that the first ones are the ones that are most recently made available to be queried through the API.This way when polling for new products, you should only need to check the first page(s).This ordering is not necessarily the same as a descending ordering by `creationDate`, because products created through the web UI may take longer to be visible through the API.\n\nThe endpoint uses paging, so it doesn't return all products at once.To get the next page of notes call the endpoint with the `from` parameter, using the ID of the last product that you received.",
"parameters": [
{
"name": "from",
"in": "query",
"description": "A product id. The result will only contain items starting at (but not including) the specified one.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiProduct"
}
}
}
}
},
"400": {
"description": "The specified product ID was invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "The specified product cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/products/{id}": {
"get": {
"tags": [
"Products"
],
"summary": "Get a product by its id",
"description": "Returns a single product with the specified product identifier",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The product's product id or product uuid",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiProduct"
}
}
}
},
"400": {
"description": "Invalid id specified in path",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "The product specified cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/products/withAmount": {
"get": {
"tags": [
"Products"
],
"summary": "List products with summed amount",
"description": "List products that are registered for your company.\n\nThe products are ordered so that the first ones are the ones that are most recently made available to be queried through the API.This way when polling for new products, you should only need to check the first page(s).This ordering is not necessarily the same as a descending ordering by `creationDate`, because products created through the web UImay take longer to be visible through the API.\n\nThe endpoint uses paging, so it doesn't return all products at once.To get the next page of notes call the endpoint with the `from` parameter, using the ID of the last product that you received.",
"parameters": [
{
"name": "from",
"in": "query",
"description": "A product id. The result will only contain items starting at (but not including) the specified one.",
"schema": {
"type": "string"
}
},
{
"name": "project",
"in": "query",
"description": "Documents in project",
"schema": {
"type": "string"
}
},
{
"name": "supplierName",
"in": "query",
"description": "Documents from supplier",
"schema": {
"type": "string"
}
},
{
"name": "documentType",
"in": "query",
"description": "Documents with type, \"Delivery Note\" or \"Invoice\"",
"schema": {
"type": "string"
}
},
{
"name": "uploadedFrom",
"in": "query",
"description": "Documents uploaded from this date",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "uploadedTo",
"in": "query",
"description": "Documents uploaded to this date",
"schema": {
"type": "string",
"format": "date-time"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiProductWithStock"
}
}
}
}
},
"400": {
"description": "The specified product ID was invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "The specified product cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/products/changes": {
"get": {
"tags": [
"Products"
],
"summary": "List product changes in a date range",
"description": "Returns changed products.\nDescendingly ordered by `lastUpdated`.The endpoint uses paging, so it doesn't return all products at once.\n\nTo get the next page of notes call the endpoint with the `fromUuid` parameter, using the ID of the oldest (last) note that you received.",
"parameters": [
{
"name": "from",
"in": "query",
"description": "The result will only contain items starting at (but not including) this one.",
"schema": {
"type": "string"
}
},
{
"name": "updatedFrom",
"in": "query",
"description": "Products updated from this date",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "updatedTo",
"in": "query",
"description": "Products updated to this date",
"schema": {
"type": "string",
"format": "date-time"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiProductChange"
}
}
}
}
},
"404": {
"description": "The product specified in the `fromUuid` field cannot be found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v29/projects": {
"get": {
"tags": [
"Projects"
],
"summary": "List projects",
"description": "Returns all project in company used by at least one document. The projects are in the order of their code.",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiProject"
}
}
}
}
}
}
}
},
"/api/v29/suppliers/register": {
"post": {
"tags": [
"Suppliers"
],
"summary": "Register a new supplier company",
"description": "Registers a supplier company with a name and tax number. Returns a new unique identifier for the supplier.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterSupplierRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RegisterSupplierRequest"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RegisterSupplierRequest"
}
}
}
},
"responses": {
"201": {
"description": "Supplier registered successfully.",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RegisterSupplierResponse"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterSupplierResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RegisterSupplierResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ApiDeliveryNote": {
"required": [
"items"
],
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "A globally unique identifier for the delivery note.\r\nThis field is automatically generated on creation, if not supplied.\r\nThe identifier is in lowercase, and in the short format without hyphen characters.",
"nullable": true,
"example": "c4db0608bac44a739ec752c48ba9b4da"
},
"created": {
"type": "string",
"description": "The date and time when this delivery note was created.",
"format": "date-time"
},
"lastUpdated": {
"type": "string",
"description": "The date and time when this delivery note was last updated, most likely for a status change.",
"format": "date-time"
},
"status": {
"$ref": "#/components/schemas/DeliveryNoteStatus"
},
"reception": {
"$ref": "#/components/schemas/Reception"
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Item"
},
"description": "The products and their quantities which are listed on the delivery note.\r\nAfter reception it can optionally contain fields describing the products actually received, in the `modified...` fields"
},
"supplierId": {
"type": "string",
"description": "The unique identifier for the delivery note, as represented in the supplier's ERP system.\r\nThe format of the note is not fixed, any identifier format can be used.\r\nThe identifier doesn't need to be globally unique, it's enough that it's unique for the current user (the one identified by the API key).",
"nullable": true,
"example": "K20223223SL"
},
"issueDate": {
"type": "string",
"description": "The date and time when the delivery note was issued.\r\n\r\nThe value of this field is not verified, it can be in the far past or in the future.",
"format": "date-time"
},
"orderDate": {
"type": "string",
"description": "The order date of the delivery note.\r\n\r\nThe value of this field is not verified, it can be in the far past or in the future.",
"format": "date",
"nullable": true
},
"estimatedDeliveryDate": {
"type": "string",
"description": "The estimated delivery date of the delivery note.\r\n\r\nThe value of this field is not verified, it can be in the far past or in the future.",
"format": "date",
"nullable": true
},
"supplier": {
"$ref": "#/components/schemas/Supplier"
},
"customer": {
"$ref": "#/components/schemas/Customer"
},
"delivery": {
"$ref": "#/components/schemas/Delivery"
},
"netWeight": {
"type": "string",
"description": "Total net weight of all products. Also includes weight units in the field.",
"nullable": true,
"example": "970 kg"
},
"grossWeight": {
"type": "string",
"description": "Total gross weight of all products. Also includes weight units in the field.",
"nullable": true
},
"hazardousGoodsIndicator": {
"type": "string",
"description": "Indicates whether the delivery contains hazardous goods",
"nullable": true,
"example": "UN 1263"
},
"orderNumber": {
"type": "string",
"description": "Additional identifier from the manufacturer's ERP system",
"nullable": true,
"example": "PO6375327"
},
"assignmentNumber": {
"type": "string",
"description": "Additional identifier from the manufacturer’s ERP system",
"nullable": true,
"example": "R4-20-00179"
},
"referenceNumber": {
"type": "string",
"description": "Additional identifier from the manufacturer’s ERP system",
"nullable": true,
"example": "182230/DTS"
},
"comment": {
"type": "string",
"description": "Additional comment",
"nullable": true
}
},
"additionalProperties": false,
"description": "A delivery note, as returned by the API."
},
"ApiDeliveryNoteReception": {
"required": [
"deliveryDirection",
"haulierNumberplate",
"reception"
],
"type": "object",
"properties": {
"qrCodeContent": {
"type": "string",
"description": "The full URL content of the scanned QR code.\r\nAt least one of `qrCodeContent` or `deliveryNoteUuid` must be provided.\r\nWhen both are supplied, `deliveryNoteUuid` takes precedence.",
"nullable": true,
"example": "https://dtls.hu/qr/v1?d=esu-NoUg81fV8LP..."
},
"deliveryNoteUuid": {
"type": "string",
"description": "The UUID of the delivery note to receive.\r\nCan be used instead of (or in addition to) `qrCodeContent` to identify the delivery note directly.\r\nAt least one of `qrCodeContent` or `deliveryNoteUuid` must be provided.",
"nullable": true,
"example": "c4db0608bac44a739ec752c48ba9b4da"
},
"haulierNumberplate": {
"maxLength": 65535,
"minLength": 1,
"type": "string",
"description": "Number plate of the vehicle delivering the goods. Required.",
"example": "ABC-123"
},
"haulierAxleLoad": {
"maxLength": 65535,
"type": "string",
"description": "Axle load / weight of the delivery vehicle.",
"nullable": true,
"example": "11.5t"
},
"shipmentWeight": {
"maxLength": 65535,
"type": "string",
"description": "Total weight of the shipment.",
"nullable": true,
"example": "2400 kg"
},
"haulierTaxNumber": {
"maxLength": 65535,
"type": "string",
"description": "Tax number of the haulier company/person performing the delivery.",
"nullable": true,
"example": "52725916-2-05"
},
"supplier": {
"$ref": "#/components/schemas/ReceptionSupplierInfo"
},
"deliveryAddress": {
"maxLength": 65535,
"type": "string",
"description": "Delivery address, used for outbound deliveries.",
"nullable": true,
"example": "Budapest, Bartók Béla út 42, II/4"
},
"customer": {
"$ref": "#/components/schemas/ReceptionCustomerInfo"
},
"hazardousGoods": {
"type": "boolean",
"description": "Indicates whether the delivery contains hazardous goods.",
"nullable": true,
"example": false
},
"itemModifications": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReceptionItemModification"
},
"description": "Quantity modifications for individual items on the delivery note.\r\nItems are identified by their sequence number (1-based order) on the delivery note.",
"nullable": true
},
"reception": {
"$ref": "#/components/schemas/ReceptionInfo"
},
"deliveryDirection": {
"$ref": "#/components/schemas/DeliveryDirection"
},
"forwardTo": {
"$ref": "#/components/schemas/ReceptionForwardTarget"
}
},
"additionalProperties": false,
"description": "Request model for administrating the reception of a delivery note.\r\nSubmitted after scanning the QR code on a delivery note."
},
"ApiDocument": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "A globally unique identifier for the delivery note.\r\nThis field is automatically generated on creation, if not supplied.\r\nThe identifier is in lowercase, and in the short format without hyphen characters.",
"nullable": true,
"example": "c4db0608bac44a739ec752c48ba9b4da"
},
"status": {
"$ref": "#/components/schemas/DocumentStatus"
},
"uploaded": {
"type": "string",
"description": "The date and time when this delivery note was uploaded.",
"format": "date-time"
},
"lastUpdated": {
"type": "string",
"description": "The date and time when this delivery note was last updated, most likely for a status change.",
"format": "date"
},
"uploader": {
"type": "string",
"description": "Username of document uploader or scanner user in bauapp.",
"nullable": true,
"example": "john.doe@bauapp.com"
},
"issueDate": {
"type": "string",
"description": "The date and time when the delivery note was issued.",
"format": "date-time"
},
"documentNumber": {
"type": "string",
"description": "The supplier dependent unique identifier for the document.\r\nThe format of the note is not fixed, any identifier format can be used.\r\nNot a real number.",
"nullable": true,
"example": "K20223223SL"
},
"orderNumber": {
"type": "string",
"description": "Order number.\r\nThe format of the note is not fixed, any identifier format can be used.\r\nNot a real number.",
"nullable": true,
"example": "PO6375327"
},
"agreementNumber": {
"type": "string",
"description": "Agreement number\r\nThe format of the note is not fixed, any identifier format can be used.\r\nNot a real number.",
"nullable": true,
"example": "XYZ123"
},
"referenceNumber": {
"type": "string",
"description": "Reference number\r\nThe format of the note is not fixed, any identifier format can be used.\r\nNot a real number.",
"nullable": true,
"example": "PO6375327"
},
"location": {
"type": "string",
"description": "Delivery location written on the document.",
"nullable": true,
"example": "Flat #102"
},
"deliveryAddress": {
"type": "string",
"description": "Delivery address.",
"nullable": true,
"example": "1051 BUDAPEST, KOSSUTH TÉR 1."
},
"contactPerson": {
"type": "string",
"description": "Contact person.",
"nullable": true,
"example": "John Doe"
},
"grossWeight": {
"type": "string",
"description": "Total gross weight of all products. Also includes weight units in the field.",
"nullable": true,
"example": "123 kg"
},
"hazardousGoodsIndicator": {
"type": "string",
"description": "Indicates whether the delivery contains hazardous goods",
"nullable": true,
"example": "UN 1263"
},
"totalPrice": {
"type": "string",
"description": "Total price of all products.",
"nullable": true,
"example": "100 000"
},
"totalPriceCurrency": {
"type": "string",
"description": "Currency of total price.",
"nullable": true,
"example": "Ft"
},
"comment": {
"type": "string",
"description": "Comment on document",
"nullable": true
},
"generalComment": {
"type": "string",
"description": "General document comment given by bauapp users anytime on documents form on web interface.",
"nullable": true
},
"documentComment": {
"type": "string",
"description": "Uploader user's document comment, given when the document is scanned on mobile phone.",
"nullable": true
},
"documentType": {
"type": "string",
"description": "Document type: \"Delivery Note\", \"Invoice\", \"Certificate of performance\", \"Debit Note\", etc",
"nullable": true
},
"duplicate": {
"$ref": "#/components/schemas/DuplicateType"
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiDocumentItem"
},
"description": "The products and their quantities which are listed on the delivery note.",
"nullable": true
},
"project": {
"$ref": "#/components/schemas/ApiProject"
},
"supplier": {
"$ref": "#/components/schemas/Supplier"
},
"customer": {
"$ref": "#/components/schemas/Customer"
},
"concrete": {
"$ref": "#/components/schemas/Concrete"
},
"delivery": {
"$ref": "#/components/schemas/Delivery"
},
"haulierName": {
"type": "string",
"description": "Name of the haulier company.",
"nullable": true
},
"haulierTaxNumber": {
"type": "string",
"description": "Tax number of the haulier company.",
"nullable": true
},
"haulierNumberPlate": {
"type": "string",
"description": "Number plate of the haulier vehicle.",
"nullable": true
},
"haulierAxelLoad": {
"type": "string",
"description": "Axle load of the haulier vehicle.",
"nullable": true
},
"supplierHeadquarters": {
"type": "string",
"description": "Registered headquarters address of the supplier.",
"nullable": true
},
"customerTaxNumber": {
"type": "string",
"description": "Tax number of the customer.",
"nullable": true
},
"dueDate": {
"type": "string",
"description": "Financial document payment date",
"format": "date-time",
"nullable": true
},
"dueDay": {
"type": "string",
"description": "In how many days is the payment due",
"nullable": true
},
"transactionDate": {
"type": "string",
"description": "When the transaction happens",
"format": "date-time",
"nullable": true
},
"deliveryDate": {
"type": "string",
"description": "Date of delivery, mainly used for financial documents",
"format": "date-time",
"nullable": true
},
"bankAccount": {
"type": "string",
"description": "Bank account number for wire transfer, used in financial documents",
"nullable": true
},
"paymentMethod": {
"type": "string",
"description": "Method of payment, example: wire transfer, cash, card",
"nullable": true
},
"totalPriceNet": {
"type": "number",
"description": "Total document net price, number.",
"format": "double",
"nullable": true
},
"refundTotal": {
"type": "number",
"description": "Amount due / to be refunded, number.",
"format": "double",
"nullable": true
},
"totalPriceVatAmount": {
"type": "number",
"description": "Total document vat amount, number.",
"format": "double",
"nullable": true
},
"refundedAmount": {
"type": "number",
"description": "Paid / refunded, number.",
"format": "double",
"nullable": true
},
"refundRemaining": {
"type": "number",
"description": "Remaining to be paid / refunded, number.",
"format": "double",
"nullable": true
}
},
"additionalProperties": false,
"description": "A delivery note, as returned by the API."
},
"ApiDocumentChange": {
"type": "object",
"properties": {
"documentUuid": {
"type": "string",
"description": "A globally unique identifier for the delivery note.\r\nThis field is automatically generated on creation, if not supplied.\r\nThe identifier is in lowercase, and in the short format without hyphen characters.",
"nullable": true,
"example": "c4db0608bac44a739ec752c48ba9b4da"
},
"lastUpdated": {
"type": "string",
"description": "The date and time when this delivery note was last updated, most likely for a status change.",
"format": "date-time"
},
"changeType": {
"$ref": "#/components/schemas/DocumentChangeType"
}
},
"additionalProperties": false,
"description": "A delivery note, as returned by the API."
},
"ApiDocumentItem": {
"type": "object",
"properties": {
"productUuid": {
"type": "string",
"nullable": true
},
"name": {
"type": "string",
"nullable": true
},
"manufacturerItemNumber": {
"type": "string",
"nullable": true
},
"manufacturer": {
"type": "string",
"description": "The name of the manufacturer of the product",
"nullable": true,
"example": "ACME Kft."
},
"utnyItemNumber": {
"type": "string",
"description": "The ÚTNY item number of the product",
"nullable": true,
"example": "e-EM 12345/2024"
},
"taxNumber": {
"type": "string",
"description": "The custom tariffs identifier of the product",
"nullable": true,
"example": "68109100"
},
"unit": {
"type": "string",
"description": "The name of the smallest undividable unit of the product.\r\nThe system will use this unit on all delivery notes for the product.\r\nE.g. a *roll* of electrical tape, or a *can* of paint.\r\n \r\nMandatory when creating a new product.",
"nullable": true,
"example": "roll"
},
"referenceNumber": {
"type": "string",
"description": "Reference number",
"nullable": true,
"example": "ABC987"
},
"amount": {
"type": "number",
"description": "The number of units ordered of this product.",
"format": "double",
"nullable": true
},
"grossWeight": {
"type": "string",
"nullable": true
},
"unitPrice": {
"type": "string",
"nullable": true
},
"unitPriceCurrency": {
"type": "string",
"nullable": true
},
"cprCategory": {
"$ref": "#/components/schemas/CprCategory"
},
"erbFunction": {
"type": "string",
"description": "The building material function: object or material",
"nullable": true,
"example": "material"
},
"erbCategory": {
"type": "string",
"description": "The building material category to which the product belongs",
"nullable": true,
"example": "concrete"
},
"erbSubcategory": {
"type": "string",
"description": "The building material",
"nullable": true,
"example": "C20/25"
},
"steelClass": {
"type": "string",
"nullable": true
},
"reinforcementClass": {
"type": "string",
"nullable": true
},
"reinforcementDiameter": {
"type": "string",
"nullable": true
},
"reinforcementSurfacetype": {
"type": "string",
"nullable": true
},
"reinforcementShape": {
"type": "string",
"nullable": true
},
"sectionProfile": {
"type": "string",
"nullable": true
},
"woodClass": {
"type": "string",
"nullable": true
},
"size": {
"type": "string",
"nullable": true
},
"width": {
"type": "string",
"nullable": true
},
"length": {
"type": "string",
"nullable": true
},
"height": {
"type": "string",
"nullable": true
},
"itemTotalPriceNet": {
"type": "number",
"format": "double",
"nullable": true
},
"itemTotalPriceVatAmount": {
"type": "number",
"format": "double",
"nullable": true
},
"vatRate": {
"type": "number",
"format": "double",
"nullable": true
},
"pricePrincipal": {
"type": "number",
"format": "double",
"nullable": true
},
"priceInterest": {
"type": "number",
"format": "double",
"nullable": true
},
"priceInterestCorrection": {
"type": "number",
"format": "double",
"nullable": true
}
},
"additionalProperties": false
},
"ApiDocumentReception": {
"required": [
"administrationDate",
"deliveryDirection",
"receivedByUser"
],
"type": "object",
"properties": {
"constructionDiaryId": {
"maxLength": 65535,
"type": "string",
"description": "Identifier or name of the construction diary where the reception was recorded.",
"nullable": true,
"example": "ÉN-2024/00123"
},
"administrationDate": {
"minLength": 1,
"type": "string",
"description": "The date and time when the reception was administratively recorded.",
"format": "date-time",
"example": "2026-03-30T14:30:00+02:00"
},
"physicalReceptionDate": {
"type": "string",
"description": "The date and time when the goods were physically received.",
"format": "date-time",
"nullable": true,
"example": "2026-03-30T10:00:00+02:00"
},
"receivedByUser": {
"maxLength": 65535,
"minLength": 1,
"type": "string",
"description": "Username or name of the person who received the delivery.",
"example": "kovacs.imre"
},
"comment": {
"maxLength": 65535,
"type": "string",
"description": "Free-text comment about the reception.",
"nullable": true,
"example": "2 packages damaged, rest OK"
},
"deliveryDirection": {
"$ref": "#/components/schemas/DeliveryDirection"
}
},
"additionalProperties": false,
"description": "Request model for adding reception data to an existing document."
},
"ApiDocumentUploadResult": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "A globally unique identifier for the document.",
"nullable": true,
"example": "c4db0608bac44a739ec752c48ba9b4da"
},
"status": {
"$ref": "#/components/schemas/DocumentStatus"
},
"uploaded": {
"type": "string",
"description": "The date and time when this document was uploaded.",
"format": "date-time"
},
"lastUpdated": {
"type": "string",
"description": "The date and time when this document was last updated.",
"format": "date-time"
},
"uploader": {
"type": "string",
"description": "Username of the document uploader.",
"nullable": true,
"example": "john.doe@bauapp.com"
},
"fileName": {
"type": "string",
"description": "Original filename of the uploaded file.",
"nullable": true,
"example": "invoice_2026.pdf"
}
},
"additionalProperties": false,
"description": "Lightweight response returned after uploading a document.\r\nContains only basic administration data; full document details\r\n(items, supplier, customer, etc.) are gathered later."
},
"ApiEncryptionKey": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "A globally unique identifier for the key.\r\n \r\nUsed for deleting keys and tracking modifications to the key expiration date.",
"nullable": true,
"example": "111546fd078a48a683bb46f0fb32cf64"
},
"supplierId": {
"type": "string",
"description": "A globally unique identifier for the supplier.\r\n \r\nThis key can only be used for signing/encryption of delivery notes created by this supplier.",
"nullable": true,
"example": "4295d8d4b4b341b8ab03ffdf55e4a829"
},
"notBefore": {
"type": "string",
"description": "The date and time when the key becomes valid.\r\nThe key should only be used for signing/encryption starting from this date.",
"format": "date-time",
"example": "2026-08-24T14:15:22Z"
},
"notAfter": {
"type": "string",
"description": "The date and time after which the key expires.\r\nAfter this date the key should not be used for signing/encryption.",
"format": "date-time",
"example": "2026-08-28T10:15:22Z"
},
"createdAt": {
"type": "string",
"description": "The date and time when the key was created in this API.",
"format": "date-time",
"example": "2026-08-26T14:15:22Z"
},
"deletedAt": {
"type": "string",
"description": "The date and time when the key was deleted, or null if the key has not been deleted.",
"format": "date-time",
"nullable": true,
"example": "2026-08-27T10:00:00Z"
},
"type": {
"type": "string",
"description": "Always {\"encryption\"} for generated QR-code encryption keys.",
"nullable": true,
"example": "encryption"
},
"key": {
"type": "string",
"description": "The generated secret string used as input to QR-payload encryption.\r\n \r\nThe UTF-8 bytes from this string are used as the PBKDF2 input for deriving the actual AES-256 key,\r\nwith SHA-256, 100000 iterations, and the salt {\"buildlink-aes-gcm-salt\"}.",
"nullable": true,
"example": "ZfdKzjxyfopt9KTz9MC1gzoMCX4hAZnK"
}
},
"additionalProperties": false,
"description": "The result of generating an encryption key."
},
"ApiKey": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "A globally unique identifier for the key.\r\n \r\nUsed for deleting keys and tracking modifications to the key expiration date.",
"nullable": true,
"example": "111546fd078a48a683bb46f0fb32cf64"
},
"supplierId": {
"type": "string",
"description": "A globally unique identifier for the supplier.\r\n \r\nThis key can only be used for signing/encryption of delivery notes created by this supplier.",
"nullable": true,
"example": "4295d8d4b4b341b8ab03ffdf55e4a829"
},
"type": {
"type": "string",
"description": "The type of the key, either \"signing\" or \"encryption\".",
"nullable": true,
"example": "signing"
},
"key": {
"type": "string",
"description": "The key material for the key.\r\n \r\nFor signing keys, this is the public key exactly as it was uploaded.\r\nFor encryption keys, this is the generated secret string.\r\nThe actual AES-256 key is derived from its UTF-8 bytes using PBKDF2 with SHA-256, 100000 iterations,\r\nand the salt {\"buildlink-aes-gcm-salt\"}.",
"nullable": true,
"example": "-----BEGIN PUBLIC KEY-----..."
},
"notBefore": {
"type": "string",
"description": "The date and time when the key becomes valid.\r\nThe key should only be used for signing/encryption starting from this date.",
"format": "date-time",
"example": "2026-08-24T14:15:22Z"
},
"notAfter": {
"type": "string",
"description": "The date and time after which the key expires.\r\nAfter this date the key should not be used for signing/encryption.",
"format": "date-time",
"example": "2026-08-28T10:15:22Z"
},
"createdAt": {
"type": "string",
"description": "The date and time when the key was created in this API.",
"format": "date-time",
"example": "2026-08-26T14:15:22Z"
},
"deletedAt": {
"type": "string",
"description": "The date and time when the key was deleted, or null if the key has not been deleted.",
"format": "date-time",
"nullable": true,
"example": "2026-08-27T10:00:00Z"
}
},
"additionalProperties": false,
"description": "The result of uploading a signing/encryption key."
},
"ApiNewDeliveryNote": {
"required": [
"customer",
"delivery",
"issueDate",
"items",
"supplier",
"supplierId"
],
"type": "object",
"properties": {
"items": {
"minLength": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/NewItem"
},
"description": "The products and their quantities which are listed on the delivery note.\r\n\r\nAt least one item is required.\r\n \r\nAt least one identifier from `productId or name+unit` must be specified for each item.\r\n\r\nWhen referring to a product by it's productId, the product must already exist.\r\nWhen using the `name+unit` to reference a product, the necessary products are created automatically before the delivery note is created.\r\nFor this automatic creation to work, you must `name` and `unit` in the item.\r\n\r\nIf the product already exists in the DTLS database, the values supplied in the item will not change the existing product.\r\nMultiple items can reference the same product. These references will be merged into one, and the quantity of each item will be summed up."
},
"uuid": {
"pattern": "^[0-9a-f]{32}$",
"type": "string",
"description": "A globally unique identifier for the delivery note.\r\nThis field is automatically generated on creation, if not supplied.\r\nThe identifier is in lowercase, and in the short format without hyphen characters.",
"nullable": true,
"example": "c4db0608bac44a739ec752c48ba9b4da"
},
"supplierId": {
"maxLength": 40,
"minLength": 1,
"type": "string",
"description": "The unique identifier for the delivery note, as represented in the supplier's ERP system.\r\nThe format of the note is not fixed, any identifier format can be used.\r\nThe identifier doesn't need to be globally unique, it's enough that it's unique for the current user (the one identified by the API key).",
"example": "K20223223SL"
},
"issueDate": {
"minLength": 1,
"type": "string",
"description": "The date and time when the delivery note was issued.\r\n\r\nThe value of this field is not verified, it can be in the far past or in the future.",
"format": "date-time"
},
"orderDate": {
"type": "string",
"description": "The order date of the delivery note.\r\n\r\nThe value of this field is not verified, it can be in the far past or in the future.",
"format": "date",
"nullable": true
},
"estimatedDeliveryDate": {
"type": "string",
"description": "The estimated delivery date of the delivery note.\r\n\r\nThe value of this field is not verified, it can be in the far past or in the future.",
"format": "date",
"nullable": true
},
"supplier": {
"$ref": "#/components/schemas/Supplier"
},
"supplierUuid": {
"type": "string",
"description": "The unique identifier of a registered supplier company, as returned by the supplier registration endpoint.\r\nWhen provided, the supplier details are looked up from the registered supplier.",
"nullable": true,
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"customer": {
"$ref": "#/components/schemas/Customer"
},
"delivery": {
"$ref": "#/components/schemas/Delivery"
},
"netWeight": {
"maxLength": 65535,
"type": "string",
"description": "Total net weight of all products. Also includes weight units in the field.",
"nullable": true,
"example": "970 kg"
},
"grossWeight": {
"maxLength": 65535,
"type": "string",
"description": "Total gross weight of all products. Also includes weight units in the field.",
"nullable": true
},
"hazardousGoodsIndicator": {
"type": "string",
"description": "Indicates whether the delivery contains hazardous goods",
"nullable": true,
"example": "UN 1263"
},
"orderNumber": {
"maxLength": 65535,
"type": "string",
"description": "Additional identifier from the manufacturer’s ERP system",
"nullable": true,
"example": "PO6375327"
},
"assignmentNumber": {
"maxLength": 65535,
"type": "string",
"description": "Additional identifier from the manufacturer’s ERP system",
"nullable": true,
"example": "R4-20-00179"
},
"referenceNumber": {
"maxLength": 65535,
"type": "string",
"description": "Additional identifier from the manufacturer’s ERP system",
"nullable": true,
"example": "182230/DTS"
}
},
"additionalProperties": false,
"description": "The model object for creating a delivery note through the API."
},
"ApiNewProduct": {
"required": [
"name",
"unit"
],
"type": "object",
"properties": {
"name": {
"maxLength": 65535,
"minLength": 1,
"type": "string",
"description": "The name of the product.",
"example": "MASTERFOL TAPE-2 20"
},
"unit": {
"maxLength": 65535,
"minLength": 1,
"type": "string",
"description": "The name of the smallest undividable unit of the product.\r\nThis cannot be changed after a product is added to the DTLS database and on\r\nall delivery notes in the system the products can be listed only in this unit.\r\nE.g. a roll of electrical tape, or a can of paint.",
"example": "roll"
},
"manufacturerItemNumber": {
"maxLength": 65535,
"type": "string",
"description": "",
"nullable": true,
"example": "0213-04020025"
},
"utnyItemNumber": {
"maxLength": 65535,
"type": "string",
"description": "The ÚTNY item number of the product",
"nullable": true,
"example": "e-EM 12345/2024"
},
"cprCategory": {
"$ref": "#/components/schemas/CprCategory"
}
},
"additionalProperties": false
},
"ApiProduct": {
"required": [
"created",
"lastUpdated",
"name",
"status",
"unit",
"uuid"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the product.",
"example": "MASTERFOL TAPE-2 20"
},
"unit": {
"type": "string",
"description": "The name of the smallest undividable unit of the product.\r\nThis cannot be changed after a product is added to the DTLS database and on\r\nall delivery notes in the system the products can be listed only in this unit.\r\nE.g. a roll of electrical tape, or a can of paint.",
"example": "roll"
},
"manufacturerItemNumber": {
"type": "string",
"description": "",
"nullable": true,
"example": "0213-04020025"
},
"utnyItemNumber": {
"type": "string",
"description": "The ÚTNY item number of the product",
"nullable": true,
"example": "e-EM 12345/2024"
},
"cprCategory": {
"$ref": "#/components/schemas/CprCategory"
},
"uuid": {
"type": "string",
"description": "The identifier of the product",
"example": "de17f5d23f9146e2a0cc8a2921a86eb4"
},
"created": {
"type": "string",
"description": "The date when this product was first registered with the DTLS system",
"format": "date-time"
},
"lastUpdated": {
"type": "string",
"description": "The date of the last change made to this product",
"format": "date-time"
},
"status": {
"$ref": "#/components/schemas/ProductStatus"
},
"erbFunction": {
"type": "string",
"description": "The building material function: object or material",
"nullable": true,
"example": "material"
},
"erbCategory": {
"type": "string",
"description": "The building material category to which the product belongs",
"nullable": true,
"example": "concrete"
},
"erbSubcategory": {
"type": "string",
"description": "The building material",
"nullable": true,
"example": "C20/25"
}
},
"additionalProperties": false
},
"ApiProductChange": {
"type": "object",
"properties": {
"productUuid": {
"type": "string",
"description": "A globally unique identifier for the delivery note.\r\nThis field is automatically generated on creation, if not supplied.\r\nThe identifier is in lowercase, and in the short format without hyphen characters.",
"nullable": true,
"example": "c4db0608bac44a739ec752c48ba9b4da"
},
"lastUpdated": {
"type": "string",
"description": "The date and time when this delivery note was last updated, most likely for a status change.",
"format": "date-time"
},
"changeType": {
"$ref": "#/components/schemas/DocumentChangeType"
}
},
"additionalProperties": false,
"description": "A delivery note, as returned by the API."
},
"ApiProductWithStock": {
"required": [
"created",
"lastUpdated",
"name",
"status",
"unit",
"uuid"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the product.",
"example": "MASTERFOL TAPE-2 20"
},
"unit": {
"type": "string",
"description": "The name of the smallest undividable unit of the product.\r\nThis cannot be changed after a product is added to the DTLS database and on\r\nall delivery notes in the system the products can be listed only in this unit.\r\nE.g. a roll of electrical tape, or a can of paint.",
"example": "roll"
},
"manufacturerItemNumber": {
"type": "string",
"description": "",
"nullable": true,
"example": "0213-04020025"
},
"utnyItemNumber": {
"type": "string",
"description": "The ÚTNY item number of the product",
"nullable": true,
"example": "e-EM 12345/2024"
},
"cprCategory": {
"$ref": "#/components/schemas/CprCategory"
},
"uuid": {
"type": "string",
"description": "The identifier of the product",
"example": "de17f5d23f9146e2a0cc8a2921a86eb4"
},
"created": {
"type": "string",
"description": "The date when this product was first registered with the DTLS system",
"format": "date-time"
},
"lastUpdated": {
"type": "string",
"description": "The date of the last change made to this product",
"format": "date-time"
},
"status": {
"$ref": "#/components/schemas/ProductStatus"
},
"erbFunction": {
"type": "string",
"description": "The building material function: object or material",
"nullable": true,
"example": "material"
},
"erbCategory": {
"type": "string",
"description": "The building material category to which the product belongs",
"nullable": true,
"example": "concrete"
},
"erbSubcategory": {
"type": "string",
"description": "The building material",
"nullable": true,
"example": "C20/25"
},
"amount": {
"type": "number",
"description": "The number of units ordered of this product.",
"format": "double",
"nullable": true
}
},
"additionalProperties": false
},
"ApiProject": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Project code set in the BauApp project.",
"nullable": true,
"example": "AT1"
},
"name": {
"type": "string",
"description": "Project name set in the BauApp project.",
"nullable": true,
"example": "Albatros Towers Phase 1"
}
},
"additionalProperties": false
},
"ApiQrSigningKey": {
"required": [
"publicKey"
],
"type": "object",
"properties": {
"publicKey": {
"maxLength": 65535,
"minLength": 1,
"type": "string",
"description": "The API accepts public keys encoded using PEM encoding, in the X.509 SubjectPublicKeyInfo structure.\r\n \r\nRequired structure:\r\n```\r\n-----BEGIN PUBLIC KEY-----(newline)\r\n(base64-encoded DER content)(newline)\r\n-----END PUBLIC KEY-----\r\n```\r\n \r\nThe content between the headers must be Base64-encoded DER.\r\n\r\nOnly the ECDSA key algorithm with the P-256 curve is currently supported."
},
"privateKey": {
"maxLength": 65535,
"type": "string",
"description": "Optional private key, for QR code generation.\r\n \r\nIf supplied, it must be the pair of the supplied public key.\r\nIf omitted, QR code generation and signing will not be possible with this key.\r\nThe API does not expose the uploaded private keys.\r\n \r\nThe API accepts private keys encoded using PEM encoding, in the PKCS#8 structure.\r\n \r\nRequired structure:\r\n```\r\n-----BEGIN PRIVATE KEY-----(newline)\r\n(base64-encoded DER content)(newline)\r\n-----END PRIVATE KEY-----\r\n```\r\n \r\nThe content between the headers must be Base64-encoded DER.\r\n\r\nOnly the ECDSA key algorithm with the P-256 curve is currently supported.",
"nullable": true
},
"notBefore": {
"type": "string",
"description": "The date and time when the key becomes valid.\r\nThe key should only be used for signing/encryption starting from this date.",
"format": "date-time",
"example": "2026-08-24T14:15:22Z"
},
"notAfter": {
"type": "string",
"description": "The date and time after which the key expires.\r\nAfter this date the key should not be used for signing/encryption.",
"format": "date-time",
"example": "2026-08-28T10:15:22Z"
}
},
"additionalProperties": false
},
"ApiUpdateDeliveryNote": {
"type": "object",
"properties": {
"supplierId": {
"type": "string",
"description": "The unique identifier for the delivery note in the supplier's ERP system.",
"nullable": true,
"example": "K20223223SL"
},
"issueDate": {
"type": "string",
"description": "The date and time when the delivery note was issued.",
"format": "date-time",
"nullable": true
},
"orderDate": {
"type": "string",
"description": "The order date of the delivery note.",
"format": "date",
"nullable": true
},
"estimatedDeliveryDate": {
"type": "string",
"description": "The estimated delivery date of the delivery note.",
"format": "date",
"nullable": true
},
"supplier": {
"$ref": "#/components/schemas/UpdateSupplier"
},
"customer": {
"$ref": "#/components/schemas/UpdateCustomer"
},
"delivery": {
"$ref": "#/components/schemas/UpdateDelivery"
},
"netWeight": {
"maxLength": 65535,
"type": "string",
"description": "Total net weight of all products.",
"nullable": true,
"example": "970 kg"
},
"grossWeight": {
"maxLength": 65535,
"type": "string",
"description": "Total gross weight of all products.",
"nullable": true,
"example": "1200 kg"
},
"hazardousGoodsIndicator": {
"maxLength": 65535,
"type": "string",
"description": "Hazardous goods indicator.",
"nullable": true,
"example": "UN 1263"
},
"orderNumber": {
"maxLength": 65535,
"type": "string",
"description": "Order number from the manufacturer's ERP system.",
"nullable": true,
"example": "PO6375327"
},
"assignmentNumber": {
"maxLength": 65535,
"type": "string",
"description": "Assignment number from the manufacturer's ERP system.",
"nullable": true,
"example": "R4-20-00179"
},
"referenceNumber": {
"maxLength": 65535,
"type": "string",
"description": "Reference number from the manufacturer's ERP system.",
"nullable": true,
"example": "182230/DTS"
},
"comment": {
"maxLength": 65535,
"type": "string",
"description": "Comment for the delivery note.",
"nullable": true
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UpdateDeliveryNoteItem"
},
"description": "Updated items. Each item is identified by its 1-based sequence number on the delivery note.\r\nOnly supplied fields within each item will be updated.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Request model for updating the QR-code-relevant fields of an existing delivery note.\r\nAll fields are optional — only supplied fields will be updated."
},
"ApiUpdateDocument": {
"type": "object",
"properties": {
"supplierName": {
"maxLength": 65535,
"type": "string",
"description": "Name of the supplier company.",
"nullable": true,
"example": "ACME Kft."
},
"supplierWarehouse": {
"maxLength": 65535,
"type": "string",
"description": "Supplier warehouse / premise name.",
"nullable": true,
"example": "Révay utcai telephely"
},
"supplierTaxNumber": {
"maxLength": 65535,
"type": "string",
"description": "Supplier tax number.",
"nullable": true,
"example": "52725916-2-05"
},
"supplierAddress": {
"maxLength": 65535,
"type": "string",
"description": "Supplier address.",
"nullable": true,
"example": "Révay utca 123"
},
"customerName": {
"maxLength": 65535,
"type": "string",
"description": "Customer company name.",
"nullable": true,
"example": "HufBau Akker"
},
"customerAddress": {
"maxLength": 65535,
"type": "string",
"description": "Customer address.",
"nullable": true,
"example": "Hufbau sétány 123"
},
"deliveryAddress": {
"maxLength": 65535,
"type": "string",
"description": "Delivery address.",
"nullable": true,
"example": "Budapest, Bartók Béla út 42, II/4"
},
"deliveryRecipientName": {
"maxLength": 65535,
"type": "string",
"description": "Delivery recipient name.",
"nullable": true,
"example": "Kovács Imre, +36204791543"
},
"issueDate": {
"type": "string",
"description": "The issue date of the document.",
"format": "date",
"nullable": true
},
"orderNumber": {
"maxLength": 65535,
"type": "string",
"description": "Order number.",
"nullable": true,
"example": "PO6375327"
},
"documentNumber": {
"maxLength": 65535,
"type": "string",
"description": "Document number (delivery note number, invoice number, etc.).",
"nullable": true,
"example": "SZL-2024/00456"
},
"documentType": {
"maxLength": 65535,
"type": "string",
"description": "Document type identifier.",
"nullable": true,
"example": "Delivery Note"
},
"referenceNumber": {
"maxLength": 65535,
"type": "string",
"description": "Reference number.",
"nullable": true,
"example": "182230/DTS"
},
"projectName": {
"maxLength": 65535,
"type": "string",
"description": "Project name.",
"nullable": true,
"example": "Albatros Towers Phase 1"
},
"projectCode": {
"maxLength": 65535,
"type": "string",
"description": "Project code.",
"nullable": true,
"example": "AT1"
},
"totalPrice": {
"maxLength": 65535,
"type": "string",
"description": "Total price.",
"nullable": true,
"example": "125000"
},
"totalPriceCurrency": {
"maxLength": 255,
"type": "string",
"description": "Currency of the total price.",
"nullable": true,
"example": "HUF"
},
"comment": {
"maxLength": 65535,
"type": "string",
"description": "Free-text comment.",
"nullable": true
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UpdateDocumentItem"
},
"description": "Updated items. Each item is identified by its 1-based sequence number on the document.\r\nOnly supplied fields within each item will be updated.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Request model for updating the QR-code-relevant fields of an existing document.\r\nAll fields are optional — only supplied fields will be updated."
},
"Concrete": {
"type": "object",
"properties": {
"arrival": {
"type": "string",
"description": "Mixer arrival to the site in hours and minutes, in format: [hours in 24 hour format]:[minutes].\r\n12:30",
"nullable": true
},
"startPour": {
"type": "string",
"description": "Concrete pouring start time in hours and minutes, in format: [hours in 24 hour format]:[minutes].\r\n12:30",
"nullable": true
},
"endPour": {
"type": "string",
"description": "Concrete pouring end time in hours and minutes, in format: [hours in 24 hour format]:[minutes].\r\n12:30",
"nullable": true
},
"departure": {
"type": "string",
"description": "Mixer departure time from the site in hours and minutes, in format: [hours in 24 hour format]:[minutes].\r\n12:30",
"nullable": true
},
"waitTime": {
"type": "string",
"description": "Mixer wait time in the site in hours and minutes, in format: [hours in 24 hour format]:[minutes].\r\n12:30",
"nullable": true
},
"jobTime": {
"type": "string",
"description": "Concrete pouring time, how long the pouring took in hours and minutes, in format: [hours in 24 hour format]:[minutes].\r\n12:30",
"nullable": true
},
"cement": {
"type": "string",
"description": "Type of cement added to the concrete",
"nullable": true
},
"cementAmount": {
"type": "string",
"description": "Added cement amount to the concrete",
"nullable": true
},
"pumpLength": {
"type": "string",
"description": "Length of the concrete pump",
"nullable": true
},
"pouringLocation": {
"type": "string",
"description": "Pouring location for concrete in the site",
"nullable": true
},
"shippingDistance": {
"type": "string",
"description": "Delivery travel distance from the sender to the receiver",
"nullable": true
},
"class": {
"type": "string",
"description": "Compressive strength class of the concrete",
"nullable": true,
"example": "C20/25; C25/30"
},
"expositionClass": {
"type": "string",
"description": "Exposure class of concrete",
"nullable": true,
"example": "X0; XD; XC1; XC2"
},
"waterproofClass": {
"type": "string",
"description": "Waterproof class of concrete",
"nullable": true,
"example": "WU0; WU1"
},
"consistencyClass": {
"type": "string",
"description": "Consistency class of concrete",
"nullable": true,
"example": "F1; F2; F3"
},
"mixDesign": {
"type": "string",
"description": "Design mix of cement, aggregates, water, and additives for concrete",
"nullable": true
},
"admixtures": {
"type": "string",
"description": "Admixtures added to concrete",
"nullable": true,
"example": "Sika Viscocrete-1020 Xtreme FO 2,62"
},
"reactionToFire": {
"type": "string",
"description": "Concrete reaction to fire",
"nullable": true
}
},
"additionalProperties": false
},
"CprCategory": {
"enum": [
"precast",
"door",
"membrane",
"insulation",
"bearing",
"chimney",
"gypsum",
"geotextile",
"curtwalling",
"firefight",
"sanitary",
"circulation",
"timber",
"woodpanel",
"cement",
"rebar",
"masonry",
"sewer",
"flooring",
"structmetal",
"wallfinish",
"roof",
"road",
"aggregate",
"adhesives",
"mortar",
"heating",
"tank",
"drinkwater",
"glass",
"cable",
"sealant",
"fixing",
"prefab",
"firestop",
"concrete",
"lighting",
"services",
"electrical",
"pallet",
"tools",
"none",
"other"
],
"type": "string"
},
"Customer": {
"required": [
"name"
],
"type": "object",
"properties": {
"name": {
"maxLength": 65535,
"minLength": 1,
"type": "string",
"description": "Name of the company who is the customer of the delivery.",
"example": "HufBau Akker"
},
"address": {
"maxLength": 65535,
"type": "string",
"description": "Optional customer address.",
"nullable": true,
"example": "Hufbau sétány 123"
},
"taxNumber": {
"type": "string",
"description": "Tax number of the company.",
"nullable": true,
"example": "52725916-2-05"
},
"code": {
"type": "string",
"description": "Optional customer code.",
"nullable": true
},
"comment": {
"type": "string",
"description": "Optional customer comment.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Fields related to the customer."
},
"Delivery": {
"required": [
"address"
],
"type": "object",
"properties": {
"recipientName": {
"maxLength": 65535,
"type": "string",
"description": "The name - and possibly additional info - of the person who will receive the delivery \r\nnote at the delivery address.",
"nullable": true,
"example": "Kovács Imre, +36204791543"
},
"address": {
"maxLength": 65535,
"minLength": 1,
"type": "string",
"description": "The delivery address. \r\n_Must contain a DTLS company identifier_.",
"example": "Budapest, Bartók Béla út 42, II/4, DTLS134532"
},
"ekaerNumber": {
"maxLength": 65535,
"type": "string",
"description": "Identification number of the delivery from the Hungarian tax bureau (NAV).",
"nullable": true
},
"haulierName": {
"maxLength": 65535,
"type": "string",
"description": "Name of the haulier company, who delivers the goods listed on the delivery note.",
"nullable": true,
"example": "OptiSped Kft"
},
"haulierComment": {
"maxLength": 65535,
"type": "string",
"nullable": true
},
"haulierDetails": {
"type": "string",
"nullable": true
},
"haulierTaxNumber": {
"maxLength": 65535,
"type": "string",
"description": "Tax number of the haulier company.",
"nullable": true,
"example": "52725916-2-05"
},
"haulierNumberplate": {
"maxLength": 65535,
"type": "string",
"description": "Number plate of the vehicle delivering the goods.",
"nullable": true,
"example": "ABC-123"
},
"haulierAxleLoad": {
"maxLength": 65535,
"type": "string",
"description": "Axle load of the delivery vehicle.",
"nullable": true,
"example": "11.5t"
}
},
"additionalProperties": false,
"description": "Delivery address and transport information."
},
"DeliveryDirection": {
"enum": [
"in",
"out"
],
"type": "string",
"description": "Direction of the delivery."
},
"DeliveryNoteStatus": {
"enum": [
"created",
"markedForDelete",
"received"
],
"type": "string",
"description": "The current delivery status of the delivery note.\r\n \r\nAll delivery notes start with a `created` status, and change to the `received` status shortly after \r\nthe delivery note QR code is scanned by the recipient."
},
"DocumentChangeType": {
"enum": [
"create",
"update",
"delete"
],
"type": "string"
},
"DocumentStatus": {
"enum": [
"created",
"updated",
"deleted",
"preview"
],
"type": "string"
},
"DuplicateType": {
"enum": [
"original",
"duplicate"
],
"type": "string"
},
"EncodedDeliveryNoteResponse": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "The UUID of the delivery note.",
"nullable": true,
"example": "c4db0608bac44a739ec752c48ba9b4da"
},
"issuer": {
"type": "string",
"description": "The short id of the registered supplier company that issued the delivery note.",
"nullable": true,
"example": "a1b2c3d4"
},
"encodedPayload": {
"type": "string",
"description": "The delivery note payload, compressed with gzip and encoded as a base64url string.\r\nContains all items — this payload is never truncated.",
"nullable": true
},
"signature": {
"type": "string",
"description": "ECDSA signature of the encoded payload, if signing is enabled for this supplier.",
"nullable": true
},
"itemCount": {
"type": "integer",
"description": "The number of items included in the encoded payload.",
"format": "int32",
"example": 5
}
},
"additionalProperties": false,
"description": "The encoded delivery note payload with supplier and signature information.\r\nAll items are always included (never truncated)."
},
"Item": {
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "DTLS Product identifier.",
"nullable": true,
"example": "de17f5d23f9146e2a0cc8a2921a86eb4"
},
"product": {
"$ref": "#/components/schemas/ApiProduct"
},
"amount": {
"type": "number",
"description": "The number of units ordered of this product.",
"format": "double"
},
"comment": {
"type": "string",
"nullable": true
},
"modifiedAmount": {
"type": "number",
"description": "The amount of this product actually received. Only available after reception.",
"format": "double",
"nullable": true
},
"modifierComment": {
"type": "string",
"description": "Comment about the reception of this item. Only available after reception.",
"nullable": true
}
},
"additionalProperties": false
},
"NewItem": {
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "DTLS Product identifier. The product must already exist in DTLS.",
"nullable": true,
"example": "de17f5d23f9146e2a0cc8a2921a86eb4"
},
"amount": {
"maximum": 100000000000,
"minimum": -100000000000,
"type": "number",
"description": "The number of units ordered of this product.",
"format": "double"
},
"comment": {
"maxLength": 65535,
"type": "string",
"nullable": true
},
"name": {
"maxLength": 65535,
"type": "string",
"description": "The name of the product.\r\n \r\nMandatory when creating a new product.",
"nullable": true,
"example": "MASTERFOL TAPE-2 20"
},
"unit": {
"maxLength": 65535,
"type": "string",
"description": "The name of the smallest undividable unit of the product.\r\nThe system will use this unit on all delivery notes for the product.\r\nE.g. a *roll* of electrical tape, or a *can* of paint.\r\n \r\nMandatory when creating a new product.",
"nullable": true,
"example": "roll"
},
"manufacturer": {
"maxLength": 65535,
"type": "string",
"description": "The name of the manufacturer.",
"nullable": true,
"example": "Masterplast"
},
"manufacturerItemNumber": {
"maxLength": 65535,
"type": "string",
"description": "",
"nullable": true,
"example": "0213-04020025"
},
"utnyItemNumber": {
"maxLength": 65535,
"type": "string",
"description": "The ÚTNY item number of the product",
"nullable": true,
"example": "e-EM 12345/2024"
},
"eanCode": {
"type": "string",
"description": "The standard 13 digits GTIN id of the product",
"nullable": true,
"example": "5996507000009"
},
"taxNumber": {
"maxLength": 65535,
"type": "string",
"description": "The custom tariffs identifier of the product",
"nullable": true,
"example": "68109100"
},
"size": {
"maxLength": 65535,
"type": "string",
"description": "The size of the product",
"nullable": true,
"example": "25m"
},
"netWeight": {
"maxLength": 65535,
"type": "string",
"description": "The net weight of the product.",
"nullable": true,
"example": "0.1kg"
},
"grossWeight": {
"maxLength": 255,
"type": "string",
"description": "The gross weight of the product.",
"nullable": true,
"example": "0.2kg"
},
"otherLink": {
"type": "string",
"description": "Any other URL associated with the product",
"format": "uri",
"nullable": true,
"example": "http://example.net/myProduct/otherInfo"
},
"cprCategory": {
"$ref": "#/components/schemas/CprCategory"
}
},
"additionalProperties": false,
"description": "An item in the delivery note at creation."
},
"ProblemDetails": {
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"type": "integer",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"additionalProperties": { }
},
"ProductStatus": {
"enum": [
"active",
"inactive"
],
"type": "string",
"description": "The status of the product. Only active products can be used while creating delivery notes."
},
"Reception": {
"required": [
"Date"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The username of the person who received the delivery note in the mobile application.",
"nullable": true,
"example": "kovacs.imre"
},
"company": {
"type": "string",
"description": "The company who actually received the materials on the construction site.",
"nullable": true,
"example": "Generál Kivitelező Kft."
},
"date": {
"type": "string",
"description": "The date when the delivery note was received.",
"format": "date-time",
"nullable": true
},
"comment": {
"type": "string",
"description": "Contains qualitative and quantitative notes that were recorded upon receiving the delivery note.",
"nullable": true
},
"project": {
"$ref": "#/components/schemas/ApiProject"
}
},
"additionalProperties": false,
"description": "Contains information about the reception of the delivery.\r\nOnly present after the status of the deliver note has been changed to `received`."
},
"ReceptionCustomerInfo": {
"type": "object",
"properties": {
"name": {
"maxLength": 65535,
"type": "string",
"description": "Name of the buyer company.",
"nullable": true,
"example": "HufBau Akker"
},
"taxNumber": {
"maxLength": 65535,
"type": "string",
"description": "Tax number of the buyer company.",
"nullable": true,
"example": "52725916-2-05"
},
"headquarters": {
"maxLength": 127,
"type": "string",
"description": "Registered headquarters address of the buyer company.",
"nullable": true,
"example": "5678 Debrecen, Kossuth tér 1."
}
},
"additionalProperties": false,
"description": "Customer (buyer) information submitted during reception."
},
"ReceptionForwardTarget": {
"enum": [
"supplier",
"mainContractor",
"both"
],
"type": "string",
"description": "Specifies where the reception notification should be forwarded."
},
"ReceptionInfo": {
"required": [
"administrationDate",
"receivedByUser"
],
"type": "object",
"properties": {
"constructionDiaryId": {
"maxLength": 65535,
"type": "string",
"description": "Identifier or name of the construction diary where the reception was recorded.",
"nullable": true,
"example": "ÉN-2024/00123"
},
"administrationDate": {
"minLength": 1,
"type": "string",
"description": "The date and time when the reception was administratively recorded.",
"format": "date-time",
"example": "2026-03-30T14:30:00+02:00"
},
"receptionDate": {
"type": "string",
"description": "The date and time when the goods were physically received.",
"format": "date-time",
"nullable": true,
"example": "2026-03-30T10:00:00+02:00"
},
"receivedByUser": {
"maxLength": 65535,
"minLength": 1,
"type": "string",
"description": "Username or name of the person who physically received the delivery.",
"example": "kovacs.imre"
},
"comment": {
"maxLength": 65535,
"type": "string",
"description": "Free-text comment about the reception.",
"nullable": true,
"example": "2 packages damaged, rest OK"
}
},
"additionalProperties": false,
"description": "Information about the reception event itself."
},
"ReceptionItemModification": {
"required": [
"itemSequence",
"modifiedAmount"
],
"type": "object",
"properties": {
"itemSequence": {
"minimum": 1,
"type": "integer",
"description": "The 1-based sequence number of the item on the delivery note.",
"format": "int32",
"example": 1
},
"modifiedAmount": {
"maximum": 100000000,
"minimum": -100000000,
"type": "number",
"description": "The actually received quantity for this item.",
"format": "double",
"example": 8
},
"comment": {
"maxLength": 65535,
"type": "string",
"description": "Optional comment about the modification.",
"nullable": true,
"example": "2 packages were damaged"
}
},
"additionalProperties": false,
"description": "A quantity modification for a single item on the delivery note."
},
"ReceptionPhotoInfo": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier of the photo.",
"format": "int32",
"example": 42
},
"type": {
"$ref": "#/components/schemas/ReceptionPhotoType"
},
"fileName": {
"type": "string",
"description": "Original file name as uploaded.",
"nullable": true,
"example": "truck_front.jpg"
},
"contentType": {
"type": "string",
"description": "MIME content type of the photo.",
"nullable": true,
"example": "image/jpeg"
},
"size": {
"type": "integer",
"description": "Size of the photo in bytes.",
"format": "int32",
"example": 245760
},
"created": {
"type": "string",
"description": "When the photo was uploaded.",
"format": "date-time"
}
},
"additionalProperties": false,
"description": "Metadata for a reception photo, as returned by the API (without binary image data)."
},
"ReceptionPhotoType": {
"enum": [
"vehicle",
"cargo"
],
"type": "string",
"description": "Type of photo taken during delivery note reception."
},
"ReceptionSupplierInfo": {
"type": "object",
"properties": {
"name": {
"maxLength": 65535,
"type": "string",
"description": "Name of the sender company.",
"nullable": true,
"example": "ACME Kft."
},
"headquarters": {
"maxLength": 127,
"type": "string",
"description": "Registered headquarters address of the sender company.",
"nullable": true,
"example": "1234 Budapest, Futrinka utca 42."
},
"address": {
"maxLength": 65535,
"type": "string",
"description": "Address of the sender (warehouse / premise).",
"nullable": true,
"example": "Révay utca 123"
}
},
"additionalProperties": false,
"description": "Sender (supplier) information submitted during reception."
},
"RegisterSupplierRequest": {
"required": [
"name",
"taxNumber"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the supplier company.",
"example": "ACME Kft."
},
"taxNumber": {
"type": "string",
"description": "Tax number of the supplier company.",
"example": "52725916-2-05"
}
},
"additionalProperties": false
},
"RegisterSupplierResponse": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "The newly generated unique identifier for the registered supplier.",
"nullable": true,
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
},
"additionalProperties": false
},
"Supplier": {
"required": [
"name",
"warehouse"
],
"type": "object",
"properties": {
"name": {
"maxLength": 65535,
"minLength": 1,
"type": "string",
"description": "Name of the company who issued the delivery note.",
"example": "ACME Kft."
},
"warehouse": {
"maxLength": 65535,
"minLength": 1,
"type": "string",
"description": "The premise where the delivery note was issued.\r\n \r\nIf the issuer doesn’t have a warehouse or a premise it can be the same as the supplier name.",
"example": "Révay utcai telephely"
},
"taxNumber": {
"maxLength": 65535,
"type": "string",
"description": "Tax number of the company who issued the delivery note.",
"nullable": true,
"example": "52725916-2-05"
},
"address": {
"maxLength": 65535,
"type": "string",
"description": "Optional address of the supplier.",
"nullable": true,
"example": "Révay utca 123"
},
"headquarters": {
"maxLength": 127,
"type": "string",
"description": "The registered address of the company who issued the delivery note.",
"nullable": true,
"example": "1234 Budapest, Futrinka utca 42."
},
"comment": {
"type": "string",
"description": "Optional supplier comment.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Fields related to the issuer of the delivery note."
},
"UpdateCustomer": {
"type": "object",
"properties": {
"name": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "HufBau Akker"
},
"address": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "Hufbau sétány 123"
},
"taxNumber": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "52725916-2-05"
}
},
"additionalProperties": false,
"description": "Customer fields for update. All fields optional — only supplied values are applied."
},
"UpdateDelivery": {
"type": "object",
"properties": {
"address": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "Budapest, Bartók Béla út 42, II/4, DTLS134532"
},
"recipientName": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "Kovács Imre, +36204791543"
},
"ekaerNumber": {
"maxLength": 65535,
"type": "string",
"nullable": true
},
"haulierName": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "OptiSped Kft"
},
"haulierTaxNumber": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "52725916-2-05"
},
"haulierNumberplate": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "ABC-123"
},
"haulierAxleLoad": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "11.5t"
}
},
"additionalProperties": false,
"description": "Delivery/haulier fields for update. All fields optional — only supplied values are applied."
},
"UpdateDeliveryNoteItem": {
"type": "object",
"properties": {
"itemSequence": {
"minimum": 1,
"type": "integer",
"description": "The 1-based sequence number of the item on the delivery note.",
"format": "int32",
"example": 1
},
"amount": {
"type": "number",
"description": "Updated quantity.",
"format": "double",
"nullable": true
},
"name": {
"maxLength": 65535,
"type": "string",
"description": "Updated product name.",
"nullable": true,
"example": "MASTERFOL TAPE-2 20"
},
"unit": {
"maxLength": 65535,
"type": "string",
"description": "Updated product unit.",
"nullable": true,
"example": "roll"
},
"manufacturer": {
"maxLength": 65535,
"type": "string",
"description": "Updated manufacturer name.",
"nullable": true,
"example": "Masterplast"
},
"manufacturerItemNumber": {
"maxLength": 65535,
"type": "string",
"description": "Updated manufacturer item number.",
"nullable": true,
"example": "0213-04020025"
},
"utnyItemNumber": {
"maxLength": 65535,
"type": "string",
"description": "Updated ÚTNY item number.",
"nullable": true,
"example": "e-EM 12345/2024"
},
"comment": {
"maxLength": 65535,
"type": "string",
"description": "Updated item comment.",
"nullable": true
}
},
"additionalProperties": false,
"description": "An item update within the delivery note. Identified by its 1-based sequence number.\r\nOnly supplied fields are updated."
},
"UpdateDocumentItem": {
"type": "object",
"properties": {
"itemSequence": {
"minimum": 1,
"type": "integer",
"description": "The 1-based sequence number of the item on the document.",
"format": "int32",
"example": 1
},
"name": {
"maxLength": 65535,
"type": "string",
"description": "Updated item name.",
"nullable": true,
"example": "MASTERFOL TAPE-2 20"
},
"amount": {
"type": "number",
"description": "Updated quantity.",
"format": "double",
"nullable": true
},
"unit": {
"maxLength": 65535,
"type": "string",
"description": "Updated unit.",
"nullable": true,
"example": "roll"
},
"manufacturerItemNumber": {
"maxLength": 65535,
"type": "string",
"description": "Updated manufacturer item number.",
"nullable": true,
"example": "0213-04020025"
},
"referenceNumber": {
"maxLength": 65535,
"type": "string",
"description": "Updated item reference number.",
"nullable": true,
"example": "ABC987"
},
"unitPrice": {
"maxLength": 65535,
"type": "string",
"description": "Updated unit price.",
"nullable": true,
"example": "2500"
},
"unitPriceCurrency": {
"maxLength": 255,
"type": "string",
"description": "Updated unit price currency.",
"nullable": true,
"example": "HUF"
}
},
"additionalProperties": false,
"description": "An item update within the document. Identified by its 1-based sequence number.\r\nOnly supplied fields are updated."
},
"UpdateSupplier": {
"type": "object",
"properties": {
"name": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "ACME Kft."
},
"warehouse": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "Révay utcai telephely"
},
"taxNumber": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "52725916-2-05"
},
"address": {
"maxLength": 65535,
"type": "string",
"nullable": true,
"example": "Révay utca 123"
},
"headquarters": {
"maxLength": 127,
"type": "string",
"nullable": true,
"example": "1234 Budapest, Futrinka utca 42."
}
},
"additionalProperties": false,
"description": "Supplier fields for update. All fields optional — only supplied values are applied."
}
},
"securitySchemes": {
"ApiKey": {
"type": "http",
"description": "The API key for the deliveryNoteManager must be sent in the HTTP Authorization header as such:\n```\nAuthorization: Bearer MyApiKey123\n```\nRequests without an API key or with an invalid API key will result in a HTTP 401 response code.",
"scheme": "Bearer"
}
}
},
"security": [
{
"ApiKey": [ ]
}
]
}