{ "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 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.\r\n\r\nThe products used on the delivery note are also managed through 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://apiteszt.dtls.hu.\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://apiteszt.dtls.hu 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.dtls.hu), 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\nThe main usage scenario when creating delivery notes is the following.\r\n\r\n1. Create products with the [products endpoints](#tag/Products). \r\nThis is optional if you already have products defined in DTLS, or if you send the product details with the *create delivery note* API call.\r\n\r\n2. Create a [delivery note](#tag/Delivery-Notes).\r\n\r\n3. Get the QR code for the created delivery note.\r\n\r\n4. Print the QR code with your physical delivery note document.\r\n\r\n5. Poll the delivery note for status changes. \r\nThe status field of the delivery note is updated shortly after the QR code is scanned by the recipient of the delivery.\r\n\r\n6. Download the delivery receipt 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## 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\r\n## Getting notifications of delivery note status updates\r\n\r\nIt's possible to configure the DTLS API server to send an HTTP request to your servers when a delivery note is received.\r\n\r\nWhen the delivery note is recevied, these two requests are sent:\r\n\r\n* a `POST` request to `{your-url}?content=deliveryNote`, with the body containing the delivery note JSON\r\n* a `POST` request to `{your-url}?content=deliveryReceipt&filename=...&deliveryNoteUuid=...`, with the body containing the delivery receipt PDF\r\n\r\nThe `{your-url}` placeholder can be configured to anything you like. \r\nAuthorization can be performed with any HTTP Authorization header or with a TLS client certificate.\r\n\r\nThe order of the two requests is undefined.\r\n\r\nIf you'd like to use this feature, contact us.\r\n", "contact": { "name": "BauApp", "url": "https://bauapp.hu/api", "email": "hello@bauapp.com" }, "version": "v24" }, "servers": [ { "url": "https://apiteszt.dtls.hu", "description": "Sandbox" }, { "url": "https://api.dtls.hu", "description": "Production" } ], "paths": { "/api/v15/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/v15/delivery_notes/{uuid}": { "delete": { "tags": [ "Delivery Notes" ], "summary": "Delete an existing delivery note", "description": "After creating a Delivery Note in th BauApp system it is possible to delete the data from BauApp servers if the Delivery Note hasn't been scanned yet. After deletion the Delivery Note won't appear on the BauApp web forms.\n\nDeleted delivery notes will not be visible for the API calls anymore.\n\nThe identifiers (`uuid`, `supplierId`) of deleted delivery notes cannot be reused when creating new ones.", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the delivery note to delete, as 32 lowercase hexadecimal digits, no hyphens.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The delivery note was deleted." }, "400": { "description": "The provided uuid is not in the correct format, or the delivery note is in the `Received` state.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The delivery note with the specified uuid was not found.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "description": "The request is too large.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "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" } } } } } } }, "/api/v15/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/v15/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 3cm by 3cm.**", "parameters": [ { "name": "uuid", "in": "path", "description": "The uuid of the delivery note the create the QR code from.", "required": true, "schema": { "type": "string" } } ], "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" } } } } } } }, "/api/v15/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/v15/dtls_id_pattern": { "get": { "tags": [ "Precondition Checks" ], "summary": "Get the pattern for DTLS company Ids", "description": "> Before sending delivery notes through the API, suppliers have two options to check if they should get a QR code for their delivery note: \r\n> 1. only send the delivery address so the DTLS system can check if it contains the DTLS Company ID or\r\n> 2. get the format of the DTLS Company ID so the supplier's ERP system can check if it contains the DTLS Company ID\r\n\r\nThe DLTS API requires a DTLS company identifier in the recipient's address when creating a delivery note.\r\n\r\nYou can use the regular expression pattern returned by this API call to check whether the delivery note in your system contains a company identifier.\r\nOnly send the delivery note creation request to the DTLS API if your delivery note contains a DTLS company ID.\r\nThis way you avoid disclosing potentially sensitive information, and the request would be rejected anyway.\r\n\r\nYou should check all the delivery note fields in your system that are eventually included in the `address` field of the delivery note creation request.\r\nThese may include fields like:\r\n* address\r\n* shipTo\r\n* comment\r\n* recipient\r\n* receiving_party\r\n\r\nThe pattern is meant to be case sensitive.", "responses": { "200": { "description": "The regular expression that you can match agains text fields to determine whether they contain a DTLS company ID.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/api/v15/check_dtls_id": { "post": { "tags": [ "Precondition Checks" ], "summary": "Check if a text field contains a DTLS company Id", "description": "> Before sending delivery notes through the API, suppliers have two options to check if they should get a QR code for their delivery note: \r\n> 1. only send the delivery address so the DTLS system can check if it contains the DTLS Company ID or\r\n> 2. get the format of the DTLS Company ID so the supplier's ERP system can check if it contains the DTLS Company ID\r\n\r\nChecks whether the posted data field contains a DTLS company identifier.\r\n\r\nYou would typically use this to send us a field in your delivery note that might contain a DTLS company identifier, such as the address/shipTo field.\r\nThis endpoint returns whether the field contains a company identifier or not.\r\n\r\nIf your address field doesn't contain a company identifier, you probably don't want to send the delivery note to DTLS.\r\n\r\nThe endpoint doesn't validate whether the company identifier belongs to an existing company or not, it only checks for the correct company id format.", "requestBody": { "description": "The text to search for DTLS company Ids.", "content": { "application/json": { "schema": { "type": "string" }, "example": "1034 Budapest, Nyírfa utca 33, DTLS123456" }, "text/json": { "schema": { "type": "string" }, "example": "1034 Budapest, Nyírfa utca 33, DTLS123456" }, "application/*+json": { "schema": { "type": "string" }, "example": "1034 Budapest, Nyírfa utca 33, DTLS123456" } } }, "responses": { "200": { "description": "true if the supplied text contains a DTLS company Id, false otherwise", "content": { "application/json": { "schema": { "type": "boolean" } } } } } } }, "/api/v15/products": { "post": { "tags": [ "Products" ], "summary": "Create a new product", "description": "Register a new product with DTLS, 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 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 DTLS 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/v15/products/{id}": { "get": { "tags": [ "Products" ], "summary": "Get a product by DTLS ID", "description": "Returns a single product with the specified DTLS product identifier", "parameters": [ { "name": "id", "in": "path", "description": "The product's DTLS product id", "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" } } } } } } } }, "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" }, "qrCodeContent": { "type": "string", "description": "This is the URI that's encoded in the delivery note's QR code.\r\nThe URI is used to identify the delivery note during the reception process.", "format": "uri", "nullable": true }, "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" }, "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 }, "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" } }, "additionalProperties": false, "description": "A delivery note, as returned by the API." }, "ApiNewDeliveryNote": { "type": "object", "properties": { "items": { "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/manufacturerItemNumber/eanCode` must be specified for each item.\r\n \r\n> The usage of `manufacturerItemNumber/eanCode` is only allowed for **manufacturers**! Need to provide a written proof. Only the `productId` is allowed for suppliers, dealers!\r\n\r\nWhen referring to a product by it's DTLS ID in `productId`, the product must already exist.\r\n\r\nWhen using the `manufacturerItemNumber/eanCode` 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 also specify at least a `name` and a `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\n \r\nThere must not be multiple items referring to the same product.", "nullable": true }, "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" }, "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" }, "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 }, "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" } }, "additionalProperties": false, "description": "The model object for creating a delivery note through the API." }, "ApiNewProduct": { "required": [ "name", "unit" ], "type": "object", "properties": { "name": { "minLength": 1, "type": "string", "description": "The name of the product.", "example": "MASTERFOL TAPE-2 20" }, "unit": { "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" }, "manufacturer": { "type": "string", "description": "The name of the manufacturer", "nullable": true, "example": "Masterplast" }, "manufacturerId": { "type": "string", "description": "The manufacturer's company ID in the DTLS system", "nullable": true, "example": "DTLS123456" }, "manufacturerItemNumber": { "type": "string", "description": "", "nullable": true, "example": "0213-04020025" }, "eanCode": { "type": "string", "description": "The standard 13 digits GTIN id of the product", "nullable": true, "example": "5996507000009" }, "taxNumber": { "type": "string", "description": "The custom tariffs identifier of the product", "nullable": true, "example": "68109100" }, "category": { "type": "string", "description": "The building material category to which the product belongs", "nullable": true, "example": "masonry" }, "packageName": { "type": "string", "description": "If multiple units of a product may be packaged together, then the name of the package containing the units.\r\nE.g. a case (package_name) of beer contains _cans_ of beers (unit).", "nullable": true, "example": "pack" }, "packageUnit": { "type": "string", "description": "Specifies how many _units_ does this package contain", "nullable": true, "example": "24" }, "palletName": { "type": "string", "description": "If multiple units of a product may be packaged together, then the name of a group of unit larger than a package.\r\nUsually just 'pallet'.", "nullable": true, "example": "pallet" }, "palletUnit": { "type": "string", "description": "Specifies how many _unit_s a pallet of this product contains.", "nullable": true, "example": "144" }, "size": { "type": "string", "description": "The size of the product", "nullable": true, "example": "25m" }, "netWeight": { "type": "string", "description": "The net weight of the product.", "nullable": true, "example": "0.1kg" }, "grossWeight": { "type": "string", "description": "The gross weight of the product.", "nullable": true, "example": "0.2kg" }, "productPage": { "type": "string", "description": "URL of the product's datasheet", "format": "uri", "nullable": true, "example": "http://example.net/myProduct" }, "performanceStatement": { "type": "string", "description": "URL of the product's performance statement", "format": "uri", "nullable": true, "example": "http://example.net/myProduct/perfStatement" }, "bimObject": { "type": "string", "description": "URL of the BIM object of the product", "format": "uri", "nullable": true, "example": "http://example.net/myProduct/bimObject" }, "otherLink": { "type": "string", "description": "Any other URL associated with the product", "format": "uri", "nullable": true, "example": "http://example.net/myProduct/otherInfo" } }, "additionalProperties": false }, "ApiProduct": { "required": [ "created", "id", "lastUpdated", "name", "status", "unit" ], "type": "object", "properties": { "name": { "minLength": 1, "type": "string", "description": "The name of the product.", "example": "MASTERFOL TAPE-2 20" }, "unit": { "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" }, "manufacturer": { "type": "string", "description": "The name of the manufacturer", "nullable": true, "example": "Masterplast" }, "manufacturerId": { "type": "string", "description": "The manufacturer's company ID in the DTLS system", "nullable": true, "example": "DTLS123456" }, "manufacturerItemNumber": { "type": "string", "description": "", "nullable": true, "example": "0213-04020025" }, "eanCode": { "type": "string", "description": "The standard 13 digits GTIN id of the product", "nullable": true, "example": "5996507000009" }, "taxNumber": { "type": "string", "description": "The custom tariffs identifier of the product", "nullable": true, "example": "68109100" }, "category": { "type": "string", "description": "The building material category to which the product belongs", "nullable": true, "example": "masonry" }, "packageName": { "type": "string", "description": "If multiple units of a product may be packaged together, then the name of the package containing the units.\r\nE.g. a case (package_name) of beer contains _cans_ of beers (unit).", "nullable": true, "example": "pack" }, "packageUnit": { "type": "string", "description": "Specifies how many _units_ does this package contain", "nullable": true, "example": "24" }, "palletName": { "type": "string", "description": "If multiple units of a product may be packaged together, then the name of a group of unit larger than a package.\r\nUsually just 'pallet'.", "nullable": true, "example": "pallet" }, "palletUnit": { "type": "string", "description": "Specifies how many _unit_s a pallet of this product contains.", "nullable": true, "example": "144" }, "size": { "type": "string", "description": "The size of the product", "nullable": true, "example": "25m" }, "netWeight": { "type": "string", "description": "The net weight of the product.", "nullable": true, "example": "0.1kg" }, "grossWeight": { "type": "string", "description": "The gross weight of the product.", "nullable": true, "example": "0.2kg" }, "productPage": { "type": "string", "description": "URL of the product's datasheet", "format": "uri", "nullable": true, "example": "http://example.net/myProduct" }, "performanceStatement": { "type": "string", "description": "URL of the product's performance statement", "format": "uri", "nullable": true, "example": "http://example.net/myProduct/perfStatement" }, "bimObject": { "type": "string", "description": "URL of the BIM object of the product", "format": "uri", "nullable": true, "example": "http://example.net/myProduct/bimObject" }, "otherLink": { "type": "string", "description": "Any other URL associated with the product", "format": "uri", "nullable": true, "example": "http://example.net/myProduct/otherInfo" }, "id": { "minLength": 1, "type": "string", "description": "The DTLS product identifier of the product", "example": "DTLS123456123456712" }, "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" } }, "additionalProperties": false }, "Customer": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the company who is the customer of the delivery.", "nullable": true, "example": "HufBau Akker" }, "companyId": { "type": "string", "description": "The DTLS company ID of the customer.", "nullable": true, "example": "DTLS999888" }, "address": { "type": "string", "description": "Optional customer address.", "nullable": true, "example": "Hufbau sétány 123" } }, "additionalProperties": false, "description": "Fields related to the customer." }, "Delivery": { "type": "object", "properties": { "recipientName": { "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": { "type": "string", "description": "The delivery address. \r\n_Must contain a DTLS company identifier_.", "nullable": true, "example": "Budapest, Bartók Béla út 42, II/4, DTLS134532" }, "ekaerNumber": { "type": "string", "description": "Identification number of the delivery from the Hungarian tax bureau (NAV).", "nullable": true }, "haulierName": { "type": "string", "description": "Name of the haulier company, who delivers the goods listed on the delivery note.", "nullable": true, "example": "OptiSped Kft" }, "haulierCompanyId": { "type": "string", "description": "The haulier’s DTLS Company ID which the issuer might provide so that the\r\nhaulier can receive the received delivery note file digitally.", "nullable": true, "example": "DTLS555667" }, "haulierComment": { "type": "string", "nullable": true }, "deliveryCompanyId": { "type": "string", "description": "The DTLS company ID of the receiving company,\r\nif you want to send a delivery note directly to the project you must fill out this field.", "nullable": true, "example": "DTLS122646" }, "projectCode": { "type": "string", "description": "The BauApp project code of the receiving project,\r\nif you want to send a delivery note directly to the project you must fill out this field", "nullable": true, "example": "PRJ-441234" } }, "additionalProperties": false, "description": "Delivery address and transport information." }, "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." }, "Item": { "type": "object", "properties": { "productId": { "type": "string", "description": "DTLS Product identifier.", "nullable": true, "example": "DTLS123456123456712" }, "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 }, "modifierUser": { "type": "string", "description": "The author of the received amount and the comment about the reception. Only available after reception.", "nullable": true }, "updateDate": { "type": "string", "description": "The time when the information about the reception was created. Only available after reception.", "format": "date-time", "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": "DTLS123456123456712" }, "amount": { "type": "number", "description": "The number of units ordered of this product.", "format": "double" }, "comment": { "type": "string", "nullable": true }, "name": { "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": { "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": { "type": "string", "description": "The name of the manufacturer.", "nullable": true, "example": "Masterplast" }, "manufacturerId": { "type": "string", "description": "The manufacturer's company ID in the DTLS system.", "nullable": true, "example": "DTLS123456" }, "manufacturerItemNumber": { "type": "string", "description": "", "nullable": true, "example": "0213-04020025" }, "eanCode": { "type": "string", "description": "The standard 13 digits GTIN id of the product", "nullable": true, "example": "5996507000009" }, "taxNumber": { "type": "string", "description": "The custom tariffs identifier of the product", "nullable": true, "example": "68109100" }, "category": { "type": "string", "description": "The building material category to which the product belongs", "nullable": true, "example": "masonry" }, "packageName": { "type": "string", "description": "If multiple units of a product may be packaged together, then the name of the package containing the units.\r\nE.g. a case (package_name) of beer contains _cans_ of beers (unit).", "nullable": true, "example": "pack" }, "packageUnit": { "type": "string", "description": "Specifies how many _units_ does this package contain", "nullable": true, "example": "24" }, "palletName": { "type": "string", "description": "If multiple units of a product may be packaged together, then the name of a group of unit larger than a package.\r\nUsually just 'pallet'.", "nullable": true, "example": "pallet" }, "palletUnit": { "type": "string", "description": "Specifies how many _unit_s a pallet of this product contains.", "nullable": true, "example": "144" }, "size": { "type": "string", "description": "The size of the product", "nullable": true, "example": "25m" }, "netWeight": { "type": "string", "description": "The net weight of the product.", "nullable": true, "example": "0.1kg" }, "grossWeight": { "type": "string", "description": "The gross weight of the product.", "nullable": true, "example": "0.2kg" }, "productPage": { "type": "string", "description": "URL of the product's datasheet", "format": "uri", "nullable": true, "example": "http://example.net/myProduct" }, "performanceStatement": { "type": "string", "description": "URL of the product's performance statement", "format": "uri", "nullable": true, "example": "http://example.net/myProduct/perfStatement" }, "bimObject": { "type": "string", "description": "URL of the BIM object of the product", "format": "uri", "nullable": true, "example": "http://example.net/myProduct/bimObject" }, "otherLink": { "type": "string", "description": "Any other URL associated with the product", "format": "uri", "nullable": true, "example": "http://example.net/myProduct/otherInfo" } }, "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 } }, "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`." }, "Supplier": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the company who issued the delivery note.", "nullable": true, "example": "ACME Kft." }, "warehouse": { "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.", "nullable": true, "example": "Révay utcai telephely" }, "taxNumber": { "type": "string", "description": "Tax number of the company who issued the delivery note.", "nullable": true, "example": "52725916-2-05" }, "address": { "type": "string", "description": "Optional address of the supplier.", "nullable": true, "example": "Révay utca 123" }, "headquarters": { "type": "string", "description": "The registered address of the company who issued the delivery note.", "nullable": true, "example": "1234 Budapest, Futrinka utca 42." } }, "additionalProperties": false, "description": "Fields related to the issuer of the delivery note." } }, "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": [ ] } ] }