Documentation Powered by ReDoc

Digital Terrain Logistics Standard - Technical Guide (v32)

Download OpenAPI specification:Download

BauApp: hello@bauapp.com URL: https://dtlsscan.mobilengine.com/api



Introduction

The DTLS API is a REST API for getting documents like invoices, delivery notes scanned or uploaded.

The products used on the documents like delivery note are also can listed by the API.

Quickstart

To access the API, you will need a way to authenticate. The simplest way to do this is with an API key.

To get an API key to the sandbox server, contact us at hello@bauapp.com.

The sandbox server is a test environment where you can freely experiment with the API. It's available at https://dtlsscan.mobilengine.com/. 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.

After acquiring an API key, download the swagger.json file containing the API specification with the Download button at te top of this document.

You can open the swagger.json file with a number of REST client tools, like Postman or Insomnia.

You'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:

Authorization: Bearer $ApiKey

Replace $ApiKey with your API key.

You should be able to make API requests now.

Security

The API is only accessible through HTTPS.

Access to the API is only allowed when the request contains an API key or a client certificate.

Requests without valid authentication will result in a HTTP 401: Unauthorized or a HTTP 403: Forbbidden response code. These 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).

There are no fine-grained access rights, a valid API key/client certificate allows clients to perform all operations through the API.

The IP addresses from where API access is allowed can be restricted, contact us for details.

API Key Authentication

The API key must be sent in the HTTP Authorization header, with the Bearer authentication scheme:

Authorization: Bearer MyApiKey123

On the live instance (https://api.bauapp.com), administering API keys is done through your company's BauApp web interface.

Api keys for the sandbox server can be requested at hello@bauapp.com.

Client Certificate Authentication

TLS client certificates can be used as an alternative to the API key authentication mechanism.

The client certificate must be a valid certificate issued by a certificate authority. The certificate must include the Client Authentication (1.3.6.1.5.5.7.3.2) OID in the Extended key usage field.

You'll need to send us the thumbprint (aka. fingerprint) of your certificate, so that we can associate it with your company.

Main use case

AI Scan documents and products retrival

  1. Get delivery note or other document data from certain timeframe
  2. Get delivery note or other document changes from certain timeframe
  3. Get document product data from certain timeframe
  4. Get document product changes data from certain timeframe
  5. Getting document pdf

API Conventions

Message format

The API consumes and produces JSON messages, with the exception of the QR code endpoint, which returns an image.

The encoding of the JSON messages must be UTF-8.

Date fields are formatted like 2020-12-31 according to OpenAPI specs. Datetime 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.

See http://spec.openapis.org/oas/v3.0.3#data-types for the specification details.

Paging

Some endpoints can potentially return a large number of objects, for example the /products endpoint.

These endpoints only return a page of objects at once. To receive the next page, call the same endpoint with a from parameter. The from parameter should contain the last identifier received in the previous endpoint request. The response for this reques will contain objects starting with (but not including) the object identified in the from parameter.

To read all objects, proceed to do this in a loop until you get an empty response.

The from field must contain the id of an existing object, otherwise a HTTP 404 error occurs.

Example: Reading all products

  1. Make a GET request to /products, let's say you receive this page (product details are omitted for the example):

    [ { id: 'p34' }, { id: 'p67' }, { id: 'p23' } ]

  2. Make a GET request with the last ID to /products?from=p23, receive this page:

    [ { id: 'p11' }, { id: 'p76' } ]

Note that the product with ID p23 is not included in this page.

  1. Make a GET request with the last ID to /products?from=p76, receive this page:

    []

  2. Since the response is an empty list you're done querying all products

String length restrictions

String length restrictions specified on fields are to be interpreted as the number of bytes in the UTF-8 encoded string, not as unicode character count.

So the length specified only applies if you don't use any multibyte characters.

HTTP version requirements

The API requires the use of HTTP/1.1, HTTP/2 and newer protocols are not supported.

If a request doesn't use HTTP/1.1, a HTTP 426 error code will be returned.

Getting notifications of document creation or status updates

It's possible to configure the DTLS API server to send an HTTP request to your servers when a document is received, modified or deleted.

When the document is recevied, these two requests are sent:

  • a POST request to {your-url}?content=document, with the body containing the delivery note JSON

The {your-url} placeholder can be configured to anything you like. Documents notifications can be filtered by document type, project or supplier. Notifications can be sent for created, updated and deleted documents, but not necessary all.

Authorization can be performed with any HTTP Authorization header or with a TLS client certificate.

If you'd like to use this feature, contact us.

API Limitations

Data retention

The production server keeps products and delivery notes indefinitely. This may change in future implementations of the API.

The data on the sandbox server is removed on a regular basis, without prior notice.

Rate limiting

Rate limiting is based on the provided API key. If too many requests are sent in a period of time the server responds with HTTP 429 messages.

Explicit rate limit values are to be determined later.

Rate limits on the sandbox server may be stricter than on the production server.

If you exceed the rate limit, a HTTP 429: Too many requests result is returned.

Request size

The request body size of create (POST) operations is limited. Currently all requests sizes are limited to 256KiB.

If you send a larger request, you'll receive a HTTP 413: Payload too large response.

Generating client code

The OpenAPI specification (the swagger.json file) can be used to generate API client code for many different programming languages.

To download the swagger.json for the API using the download button at the top of this document.

For information about how to generate clients from the specification see the OpenAPI Generator Homepage.

Authentication

ApiKey

The API key for the deliveryNoteManager must be sent in the HTTP Authorization header as such:

Authorization: Bearer MyApiKey123

Requests without an API key or with an invalid API key will result in a HTTP 401 response code.

Security Scheme Type HTTP
HTTP Authorization Scheme Bearer

Delivery Notes

Create a new delivery note

The delivery note with the specified id must not exist yet.

The API doesn't allow updating delivery notes after creation, you can just create a new note if a created note contains an error.

This API call can also create the products used on the delivery note, see the description of items.

Authorizations:
ApiKey
Request Body schema:
application/json
application/json
text/json
application/*+json
required
Array of objects (NewItem) non-empty

The products and their quantities which are listed on the delivery note.

At least one item is required.

At least one identifier from productId or name+unit must be specified for each item.

When referring to a product by it's productId, the product must already exist. When using the name+unit to reference a product, the necessary products are created automatically before the delivery note is created. For this automatic creation to work, you must name and unit in the item.

If the product already exists in the DTLS database, the values supplied in the item will not change the existing product. Multiple items can reference the same product. These references will be merged into one, and the quantity of each item will be summed up.

uuid
string or null^[0-9a-f]{32}$

A globally unique identifier for the delivery note. This field is automatically generated on creation, if not supplied. The identifier is in lowercase, and in the short format without hyphen characters.

supplierId
required
string [ 1 .. 40 ] characters

The unique identifier for the delivery note, as represented in the supplier's ERP system. The format of the note is not fixed, any identifier format can be used. The 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).

issueDate
required
string <date-time> non-empty

The date and time when the delivery note was issued.

The value of this field is not verified, it can be in the far past or in the future.

orderDate
string or null <date>

The order date of the delivery note.

The value of this field is not verified, it can be in the far past or in the future.

estimatedDeliveryDate
string or null <date>

The estimated delivery date of the delivery note.

The value of this field is not verified, it can be in the far past or in the future.

required
object (Supplier)

Fields related to the issuer of the delivery note.

supplierUuid
string or null

The unique identifier of a registered supplier company, as returned by the supplier registration endpoint. When provided, the supplier details are looked up from the registered supplier.

required
object (Customer)

Fields related to the customer.

required
object (Delivery)

Delivery address and transport information.

netWeight
string or null <= 65535 characters

Total net weight of all products. Also includes weight units in the field.

grossWeight
string or null <= 65535 characters

Total gross weight of all products. Also includes weight units in the field.

hazardousGoodsIndicator
string or null

Indicates whether the delivery contains hazardous goods

orderNumber
string or null <= 65535 characters

Additional identifier from the manufacturer’s ERP system

assignmentNumber
string or null <= 65535 characters

Additional identifier from the manufacturer’s ERP system

referenceNumber
string or null <= 65535 characters

Additional identifier from the manufacturer’s ERP system

Responses

Request samples

Content type
application/json
application/json
text/json
application/*+json
{
}

Response samples

Content type
application/json
{
}

List delivery notes

Returns delivery notes. The 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.

The endpoint uses paging, so it doesn't return all delivery notes at once.

To get the next page of notes call the endpoint with the fromUuid parameter, using the ID of the oldest (last) note that you received.

Authorizations:
ApiKey
query Parameters
fromUuid
string

The result will only contain items starting at (but not including) this one.

Responses

Response samples

Content type
application/json
[
]

Create a new delivery note and return its QR code

Creates a new delivery note and immediately returns its QR code as a PNG image.

This is a hybrid shortcut combining the POST /delivery_notes and GET /delivery_notes/{uuid}/qr_code calls into one.

The same validation rules apply as when creating a delivery note normally.

Authorizations:
ApiKey
query Parameters
useEncryption
boolean
Default: true

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.

Request Body schema:
application/json
application/json
text/json
application/*+json
required
Array of objects (NewItem) non-empty

The products and their quantities which are listed on the delivery note.

At least one item is required.

At least one identifier from productId or name+unit must be specified for each item.

When referring to a product by it's productId, the product must already exist. When using the name+unit to reference a product, the necessary products are created automatically before the delivery note is created. For this automatic creation to work, you must name and unit in the item.

If the product already exists in the DTLS database, the values supplied in the item will not change the existing product. Multiple items can reference the same product. These references will be merged into one, and the quantity of each item will be summed up.

uuid
string or null^[0-9a-f]{32}$

A globally unique identifier for the delivery note. This field is automatically generated on creation, if not supplied. The identifier is in lowercase, and in the short format without hyphen characters.

supplierId
required
string [ 1 .. 40 ] characters

The unique identifier for the delivery note, as represented in the supplier's ERP system. The format of the note is not fixed, any identifier format can be used. The 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).

issueDate
required
string <date-time> non-empty

The date and time when the delivery note was issued.

The value of this field is not verified, it can be in the far past or in the future.

orderDate
string or null <date>

The order date of the delivery note.

The value of this field is not verified, it can be in the far past or in the future.

estimatedDeliveryDate
string or null <date>

The estimated delivery date of the delivery note.

The value of this field is not verified, it can be in the far past or in the future.

required
object (Supplier)

Fields related to the issuer of the delivery note.

supplierUuid
string or null

The unique identifier of a registered supplier company, as returned by the supplier registration endpoint. When provided, the supplier details are looked up from the registered supplier.

required
object (Customer)

Fields related to the customer.

required
object (Delivery)

Delivery address and transport information.

netWeight
string or null <= 65535 characters

Total net weight of all products. Also includes weight units in the field.

grossWeight
string or null <= 65535 characters

Total gross weight of all products. Also includes weight units in the field.

hazardousGoodsIndicator
string or null

Indicates whether the delivery contains hazardous goods

orderNumber
string or null <= 65535 characters

Additional identifier from the manufacturer’s ERP system

assignmentNumber
string or null <= 65535 characters

Additional identifier from the manufacturer’s ERP system

referenceNumber
string or null <= 65535 characters

Additional identifier from the manufacturer’s ERP system

Responses

Request samples

Content type
application/json
application/json
text/json
application/*+json
{
}

Response samples

Content type
image/png
image/png
application/json
No sample

Search delivery notes

Currently the search only supports finding delivery notes by the supplierId

The response contains all matches, no paging is used.

In rare cases there may be more than one delivery notes with the same supplierId.

For example when you're a haulier company and you have access to many companies delivery notes, and two happen to share the same supplierId.

Authorizations:
ApiKey
query Parameters
supplierId
required
string

The supplier's identifier of the delivery note, as supplied in the supplierId field when creating the delivery note.

Responses

Response samples

Content type
application/json
[
]

Get a delivery note by UUID

Authorizations:
ApiKey
path Parameters
uuid
required
string

The UUID of the delivery note.

Responses

Response samples

Content type
application/json
{
}

Update delivery note fields

Update the QR-code-relevant fields of an existing delivery note.

All fields are optional — only the supplied fields will be overwritten. Omitted fields keep their current value.

Item 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.

Authorizations:
ApiKey
path Parameters
uuid
required
string

The UUID of the delivery note.

Request Body schema:
application/json
application/json
text/json
application/*+json
supplierId
string or null

The unique identifier for the delivery note in the supplier's ERP system.

issueDate
string or null <date-time>

The date and time when the delivery note was issued.

orderDate
string or null <date>

The order date of the delivery note.

estimatedDeliveryDate
string or null <date>

The estimated delivery date of the delivery note.

object (UpdateSupplier)

Supplier fields for update. All fields optional — only supplied values are applied.

object (UpdateCustomer)

Customer fields for update. All fields optional — only supplied values are applied.

object (UpdateDelivery)

Delivery/haulier fields for update. All fields optional — only supplied values are applied.

netWeight
string or null <= 65535 characters

Total net weight of all products.

grossWeight
string or null <= 65535 characters

Total gross weight of all products.

hazardousGoodsIndicator
string or null <= 65535 characters

Hazardous goods indicator.

orderNumber
string or null <= 65535 characters

Order number from the manufacturer's ERP system.

assignmentNumber
string or null <= 65535 characters

Assignment number from the manufacturer's ERP system.

referenceNumber
string or null <= 65535 characters

Reference number from the manufacturer's ERP system.

comment
string or null <= 65535 characters

Comment for the delivery note.

Array of objects or null (UpdateDeliveryNoteItem)

Updated items. Each item is identified by its 1-based sequence number on the delivery note. Only supplied fields within each item will be updated.

Responses

Request samples

Content type
application/json
application/json
text/json
application/*+json
{
}

Response samples

Content type
application/json
{
}

Get the QR code for a delivery note

Returns an image of a QR code containing a link to the delivery note.

You can include this image on your own documents, and the QR code can be scanned with the mobile app during delivery.

Try to print the QR code as large as you can. This will make scanning easier and will also protect against damage and staining. We recommend at least 4cm by 4cm.

Authorizations:
ApiKey
path Parameters
uuid
required
string

The uuid of the delivery note the create the QR code from.

query Parameters
useEncryption
boolean
Default: true

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.

Responses

Response samples

Content type
image/png
image/png
application/json
No sample

Get the receipt PDF for a delivery note

Download the receipt for the delivery note - a .pdf report confirming the delivery, with comments and information supplied by the recipient.

Only available after the delivery note was received, see the status field on the delivery note.

Authorizations:
ApiKey
path Parameters
uuid
required
string

The uuid of the delivery note.

Responses

Response samples

Content type
application/pdf
application/pdf
application/octet-stream
application/json
No sample

Get the full encoded delivery note data

Returns the complete (never truncated) delivery note payload in compressed and base64url-encoded form, along with the supplier identifier and an optional ECDSA signature.

Unlike the QR code — which may drop items to fit a size limit — this endpoint always includes every item.

The response contains the same fields that appear on the QR code URL (is, dn, sig).

Authorizations:
ApiKey
path Parameters
uuid
required
string

The uuid of the delivery note.

query Parameters
useEncryption
boolean
Default: true

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.

Responses

Response samples

Content type
application/json
{
}

Receive a delivery note

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.

The haulierNumberplate field is mandatory.

Item quantity modifications are identified by the 1-based sequence number of the item on the delivery note.

Use the optional forwardTo field to specify where the reception notification should be sent: Supplier, Builder, or Both. If omitted, no notification is forwarded.

Authorizations:
ApiKey
Request Body schema:
application/json
application/json
text/json
application/*+json
qrCodeContent
string or null

The full URL content of the scanned QR code. At least one of qrCodeContent or deliveryNoteUuid must be provided. When both are supplied, deliveryNoteUuid takes precedence.

deliveryNoteUuid
string or null

The UUID of the delivery note to receive. Can be used instead of (or in addition to) qrCodeContent to identify the delivery note directly. At least one of qrCodeContent or deliveryNoteUuid must be provided.

haulierNumberplate
required
string [ 1 .. 65535 ] characters

Number plate of the vehicle delivering the goods. Required.

haulierAxleLoad
string or null <= 65535 characters

Axle load / weight of the delivery vehicle.

shipmentWeight
string or null <= 65535 characters

Total weight of the shipment.

haulierTaxNumber
string or null <= 65535 characters

Tax number of the haulier company/person performing the delivery.

object (ReceptionSupplierInfo)

Sender (supplier) information submitted during reception.

deliveryAddress
string or null <= 65535 characters

Delivery address, used for outbound deliveries.

object (ReceptionCustomerInfo)

Customer (buyer) information submitted during reception.

hazardousGoods
boolean or null

Indicates whether the delivery contains hazardous goods.

Array of objects or null (ReceptionItemModification)

Quantity modifications for individual items on the delivery note. Items are identified by their sequence number (1-based order) on the delivery note.

required
object (ReceptionInfo)

Information about the reception event itself.

deliveryDirection
required
string (DeliveryDirection)
Enum: "in" "out"

Direction of the delivery.

forwardTo
string (ReceptionForwardTarget)
Enum: "supplier" "mainContractor" "both"

Specifies where the reception notification should be forwarded.

Responses

Request samples

Content type
application/json
application/json
text/json
application/*+json
{
}

Response samples

Content type
application/json
{
}

Upload reception photos for a delivery note

Upload one or more photos taken during the reception of a delivery note.

Two categories of photos are supported:

  • vehicle – photo of the delivery vehicle and its license plate
  • cargo – photo of the cargo / shipment

Each file must be a JPEG or PNG image. Multiple files can be uploaded in a single request. The type form field must be provided for each file (vehicle or cargo).

Authorizations:
ApiKey
path Parameters
uuid
required
string

The UUID of the delivery note.

Request Body schema: multipart/form-data
files
Array of strings <binary>
type
Array of strings

Responses

Response samples

Content type
application/json
[
]

List reception photos for a delivery note

Returns metadata for all photos uploaded during the reception of a delivery note. Use the photo id with the download endpoint to retrieve the actual image data.

Authorizations:
ApiKey
path Parameters
uuid
required
string

The UUID of the delivery note.

Responses

Response samples

Content type
application/json
[
]

Download a reception photo

Returns the image data of a single reception photo by its id.

Authorizations:
ApiKey
path Parameters
uuid
required
string

The UUID of the delivery note.

photoId
required
integer <int32>

The id of the photo.

Responses

Response samples

Content type
image/jpeg
image/jpeg
image/png
application/json
No sample

Documents

Get a document by UUID

Authorizations:
ApiKey
path Parameters
uuid
required
string

The UUID of the document.

Responses

Response samples

Content type
application/json
{
}

Update document fields

Update the QR-code-relevant fields of an existing document.

All fields are optional — only the supplied fields will be overwritten. Omitted fields keep their current value.

Updatable 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.

Item updates are identified by the 1-based sequence number of the item on the document.

Authorizations:
ApiKey
path Parameters
uuid
required
string

The UUID of the document.

Request Body schema:
application/json
application/json
text/json
application/*+json
supplierName
string or null <= 65535 characters

Name of the supplier company.

supplierWarehouse
string or null <= 65535 characters

Supplier warehouse / premise name.

supplierTaxNumber
string or null <= 65535 characters

Supplier tax number.

supplierAddress
string or null <= 65535 characters

Supplier address.

customerName
string or null <= 65535 characters

Customer company name.

customerAddress
string or null <= 65535 characters

Customer address.

deliveryAddress
string or null <= 65535 characters

Delivery address.

deliveryRecipientName
string or null <= 65535 characters

Delivery recipient name.

issueDate
string or null <date>

The issue date of the document.

orderNumber
string or null <= 65535 characters

Order number.

documentNumber
string or null <= 65535 characters

Document number (delivery note number, invoice number, etc.).

documentType
string or null <= 65535 characters

Document type identifier.

referenceNumber
string or null <= 65535 characters

Reference number.

projectName
string or null <= 65535 characters

Project name.

projectCode
string or null <= 65535 characters

Project code.

totalPrice
string or null <= 65535 characters

Total price.

totalPriceCurrency
string or null <= 255 characters

Currency of the total price.

comment
string or null <= 65535 characters

Free-text comment.

Array of objects or null (UpdateDocumentItem)

Updated items. Each item is identified by its 1-based sequence number on the document. Only supplied fields within each item will be updated.

Responses

Request samples

Content type
application/json
application/json
text/json
application/*+json
{
}

Response samples

Content type
application/json
{
}

List documents for search criteria

The documents are in descending order of creation.The endpoint uses paging, so it doesn't return all documents at once.

To get the next page of notes call the endpoint with the fromUuid parameter, using the ID of the oldest (last) note that you uploaded.

Authorizations:
ApiKey
query Parameters
fromUuid
string

The result will only contain items starting at (but not including) this one.

project
string

Documents in project

supplierName
string

Documents from supplier

documentNumber
string

Documents with document (e.g. delivery note or invoice) number

orderNumber
string

Documents with order number

agreementNumber
string

Documents with agreement number

referenceNumber
string

Documents with reference number

documentType
string

Documents with type, "Delivery Note" or "Invoice"

issuedFrom
string <date-time>

Documents issued from this date

issuedTo
string <date-time>

Documents issued to this date

uploadedFrom
string <date-time>

Documents uploaded from this date

uploadedTo
string <date-time>

Documents uploaded to this date

updatedFrom
string <date-time>

Documents updated from this date

updatedTo
string <date-time>

Documents updated to this date

Responses

Response samples

Content type
application/json
[
]

List document changes in a date range

Returns changed documents. Descending order of document creation.The endpoint uses paging, so it doesn't return all documents at once.

To get the next page of notes call the endpoint with the fromUuid parameter, using the ID of the oldest (last) note that you uploaded.

Authorizations:
ApiKey
query Parameters
fromUuid
string

The result will only contain items starting at (but not including) this one.

project
string

Documents in project

supplierName
string

Supplier name

documentType
string

Documents with type like "Delivery Note" or "Invoice"

updatedFrom
string <date-time>

Documents updated from this date

updatedTo
string <date-time>

Documents updated to this date

Responses

Response samples

Content type
application/json
[
]

Get the PDF file for a document

Download the pdf for the document.

Authorizations:
ApiKey
path Parameters
uuid
required
string

The uuid of the document.

Responses

Response samples

Content type
application/pdf
application/pdf
application/octet-stream
application/json
No sample

Upload a document file

Upload a JPEG or PDF file to create a new document, or replace the file of an existing one.

When replaceDocumentId is omitted a new document is created and 201 Created is returned.

When replaceDocumentId is provided the file of the existing document is replaced, its status is set to Updated, and 200 OK is returned.

Authorizations:
ApiKey
Request Body schema: multipart/form-data
file
string <binary>
replaceDocumentId
string

Responses

Response samples

Content type
application/json
{
}

Add reception data to a document

Record reception (acceptance) details for an existing document.

Fields 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).

Authorizations:
ApiKey
path Parameters
uuid
required
string

The UUID of the document.

Request Body schema:
application/json
application/json
text/json
application/*+json
constructionDiaryId
string or null <= 65535 characters

Identifier or name of the construction diary where the reception was recorded.

administrationDate
required
string <date-time> non-empty

The date and time when the reception was administratively recorded.

physicalReceptionDate
string or null <date-time>

The date and time when the goods were physically received.

receivedByUser
required
string [ 1 .. 65535 ] characters

Username or name of the person who received the delivery.

comment
string or null <= 65535 characters

Free-text comment about the reception.

deliveryDirection
required
string (DeliveryDirection)
Enum: "in" "out"

Direction of the delivery.

Responses

Request samples

Content type
application/json
application/json
text/json
application/*+json
{
}

Response samples

Content type
application/json
{
}

Upload reception photos for a document

Upload one or more photos taken during the reception of a document.

Two categories of photos are supported:

  • vehicle – photo of the delivery vehicle and its license plate
  • cargo – photo of the cargo / shipment

Each file must be a JPEG or PNG image. Multiple files can be uploaded in a single request. The type form field must be provided for each file (vehicle or cargo).

The document must already have reception data (created via the POST {uuid}/reception endpoint).

Authorizations:
ApiKey
path Parameters
uuid
required
string

The UUID of the document.

Request Body schema: multipart/form-data
files
Array of strings <binary>
type
Array of strings

Responses

Response samples

Content type
application/json
[
]

List reception photos for a document

Returns metadata for all photos uploaded during the reception of a document. Use the photo id with the download endpoint to retrieve the actual image data.

Authorizations:
ApiKey
path Parameters
uuid
required
string

The UUID of the document.

Responses

Response samples

Content type
application/json
[
]

Download a document reception photo

Returns the image data of a single reception photo by its id.

Authorizations:
ApiKey
path Parameters
uuid
required
string

The UUID of the document.

photoId
required
integer <int32>

The id of the photo.

Responses

Response samples

Content type
image/jpeg
image/jpeg
image/png
application/json
No sample

QR Code Keys

List keys

List QR code encryption and signing keys.

The result only contains a fixed number of keys. To get the next batch of keys, use the idFrom parameter. Repeat these steps until the result is an empty array, that means there are no more keys to retrieve. If the specified idFrom is not found, the keys are returned from the start as if the parameter were missing.

Authorizations:
ApiKey
query Parameters
idFrom
string

The id of the key to start the listing from (it will not be included in the response)

Responses

Response samples

Content type
application/json
[
]

Upload a signing key

Upload a public key of a keypair that will be used to sign QR codes.

Authorizations:
ApiKey
Request Body schema:
application/json
application/json
text/json
application/*+json
publicKey
required
string [ 1 .. 65535 ] characters

The API accepts public keys encoded using PEM encoding, in the X.509 SubjectPublicKeyInfo structure.

Required structure:

-----BEGIN PUBLIC KEY-----(newline)
(base64-encoded DER content)(newline)
-----END PUBLIC KEY-----

The content between the headers must be Base64-encoded DER.

Only the ECDSA key algorithm with the P-256 curve is currently supported.

privateKey
string or null <= 65535 characters

Optional private key, for QR code generation.

If supplied, it must be the pair of the supplied public key. If omitted, QR code generation and signing will not be possible with this key. The API does not expose the uploaded private keys.

The API accepts private keys encoded using PEM encoding, in the PKCS#8 structure.

Required structure:

-----BEGIN PRIVATE KEY-----(newline)
(base64-encoded DER content)(newline)
-----END PRIVATE KEY-----

The content between the headers must be Base64-encoded DER.

Only the ECDSA key algorithm with the P-256 curve is currently supported.

notBefore
string <date-time>

The date and time when the key becomes valid. The key should only be used for signing/encryption starting from this date.

notAfter
string <date-time>

The date and time after which the key expires. After this date the key should not be used for signing/encryption.

Responses

Request samples

Content type
application/json
application/json
text/json
application/*+json
{
}

Response samples

Content type
application/json
{
}

Generate an encryption key

Generate the secret string used to encrypt delivery note data in QR codes.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
}

Delete a key

Delete a key by its id.

This can be used to revoke keys before their expiration date.

Authorizations:
ApiKey
path Parameters
id
required
string

The id of the key to delete

Responses

Response samples

Content type
application/json
{
}

Key synchronization feed

Get the keys modified after the specified date. This can be used by clients to synchronize known keys.

Clients should use the date parameter to only get the keys modified since the last synchronization. The result will contain all keys which were created or modified after the specified date. Clients should use the key identifiers to update the modified keys in their local key store.

Clients are expected to call this endpoint regularly: about once every hour, to get notified of deleted keys early.

Clients should query all keys initially with the /keys endpoint, and only use this to update that list.

Authorizations:
ApiKey
query Parameters
date
required
string <date-time>

Date to get the changed keys from. Must be an UTC date in YYYY-MM-DDTHH:mm:ssZ format.

Responses

Response samples

Content type
application/json
[
]

Products

Create a new product

Register a new product, so that it can later be referenced in delivery notes.

Modifying the properties of a product after creation is not supported for now.

It'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.

Authorizations:
ApiKey
Request Body schema:
application/json
application/json
text/json
application/*+json
name
required
string [ 1 .. 65535 ] characters

The name of the product.

unit
required
string [ 1 .. 65535 ] characters

The name of the smallest undividable unit of the product. This cannot be changed after a product is added to the DTLS database and on all delivery notes in the system the products can be listed only in this unit. E.g. a roll of electrical tape, or a can of paint.

manufacturerItemNumber
string or null <= 65535 characters
utnyItemNumber
string or null <= 65535 characters

The ÚTNY item number of the product

cprCategory
string (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"

Responses

Request samples

Content type
application/json
application/json
text/json
application/*+json
{
}

Response samples

Content type
application/json
{
}

List products

List products that are registered for your company.

The 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.

The 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.

Authorizations:
ApiKey
query Parameters
from
string

A product id. The result will only contain items starting at (but not including) the specified one.

Responses

Response samples

Content type
application/json
[
]

Get a product by its id

Returns a single product with the specified product identifier

Authorizations:
ApiKey
path Parameters
id
required
string

The product's product id or product uuid

Responses

Response samples

Content type
application/json
{
}

List products with summed amount

List products that are registered for your company.

The 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.

The 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.

Authorizations:
ApiKey
query Parameters
from
string

A product id. The result will only contain items starting at (but not including) the specified one.

project
string

Documents in project

supplierName
string

Documents from supplier

documentType
string

Documents with type, "Delivery Note" or "Invoice"

uploadedFrom
string <date-time>

Documents uploaded from this date

uploadedTo
string <date-time>

Documents uploaded to this date

Responses

Response samples

Content type
application/json
[
]

List product changes in a date range

Returns changed products. Descendingly ordered by lastUpdated.The endpoint uses paging, so it doesn't return all products at once.

To get the next page of notes call the endpoint with the fromUuid parameter, using the ID of the oldest (last) note that you received.

Authorizations:
ApiKey
query Parameters
from
string

The result will only contain items starting at (but not including) this one.

updatedFrom
string <date-time>

Products updated from this date

updatedTo
string <date-time>

Products updated to this date

Responses

Response samples

Content type
application/json
[
]

Projects

List projects

Returns all project in company used by at least one document. The projects are in the order of their code.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
[
]

Suppliers

Register a new supplier company

Registers a supplier company with a name and tax number. Returns a new unique identifier for the supplier.

Authorizations:
ApiKey
Request Body schema:
application/json
application/json
text/json
application/*+json
name
required
string

Name of the supplier company.

taxNumber
required
string

Tax number of the supplier company.

Responses

Request samples

Content type
application/json
application/json
text/json
application/*+json
{
}

Response samples

Content type
text/plain
text/plain
application/json
text/json
No sample