The DTLS API is a REST API for registering delivery notes. The registered delivery notes get a printable QR code. This QR code can be scanned in the BauApp application when receiving the shipment. API clients then see the delivery note as received, can see the receiver's comments about the shipment, and can download a PDF receipt of the received shipment.

The products used on the delivery note are also managed through the API.

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://apiteszt.dtls.hu. 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://apiteszt.dtls.hu 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.

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.dtls.hu), 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.

The main usage scenario when creating delivery notes is the following.

1. Create products with the products endpoints. This is optional if you already have products defined in DTLS, or if you send the product details with the create delivery note API call.

2. Create a delivery note.

3. Get the QR code for the created delivery note.

4. Print the QR code with your physical delivery note document.

5. Poll the delivery note for status changes. The status field of the delivery note is updated shortly after the QR code is scanned by the recipient of the delivery.

6. Download the delivery receipt PDF.

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.

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

   []

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

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.

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.

It's possible to configure the DTLS API server to send an HTTP request to your servers when a delivery note is received.

When the delivery note is recevied, these two requests are sent:

• a POST request to {your-url}?content=deliveryNote, with the body containing the delivery note JSON
• a POST request to {your-url}?content=deliveryReceipt&filename=...&deliveryNoteUuid=..., with the body containing the delivery receipt PDF

The {your-url} placeholder can be configured to anything you like. Authorization can be performed with any HTTP Authorization header or with a TLS client certificate.

The order of the two requests is undefined.

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