Delivery Notes Integrations

Electronic delivery notes and Remittances are primarily for suppliers to provide their customers with electronic delivery notes and remittances, and easy stock in.

Purpose of this guide is to ease the integration of a supplier's system with the Dotykacka platform. The customers can then benefit from a smooth cooperation between the two systems which will save their time otherwise consumed by updating products and stock quantities in a delivery note manually item-by-item.

Should you have any questions or issues with the integration do not hesitate to ask us via e-mail [e-mail]

Flow description

1. The supplier prepares the delivery note XML and uploads it via the API2 (steps to setup and invoke the API2 are described in this guide).

2. When the XML document is uploaded, it will show up in the customer's Warehouse application.

3. From there, optionally, the customer can alter selling prices and quantities before confirming to stock in the items.

4. When confirmed, the application will automatically update product prices and quantities of stock items in the customer's warehouse and it will also set the delivery note status to Stacked.

Register your application

• Fill in the Client Application registration form.

• We will provide you a Client ID and Client Secret, and a testing license key.

Setup for testing

The steps in this section are very simplified to help you to experiment with the API as quickly as possible but should not be used in production.

• For testing, create a new Dotypos Account with the provided testing license key.

  (install Dotykacka Application and Activate your license - more info in the Manual)

• Prepare the connector URL (replace variables {} with client ID and secret):

  https://admin.dotykacka.cz/client/connect?client_id={client_id}&client_secret={client_secret}&scope=*&redirect_uri=https://dotykacka.cz

• Open the URL in a browser and grant access to your testing cloud.

• Note down the Refresh Token returned in the URL after you get redirected to dotykacka.cz

  (redirect URL: https://dotykacka.cz?token={RefreshToken}&cloudid={cloudId})

Setup for production

Here are some hints to make your application better prepared for the production.

• Your application should generate the connector URL query parameters and use the full URL to redirect users automatically.

• The redirect_uri in the connector URL should be an URL of your webhook that will process the response.

• Use the state parameter in the connector URL to avoid CSRF (more reading here).
• The Refresh Token should be stored safely in your application (never expires).

Obtain the Access Token

• send API request POST https://test.api.dotykacka.cz/v2/signin/token

  • with header: Authorization: User {RefreshToken}

  • and header: Content-Type: application/json

  • and JSON body: { "_cloudId": {cloudId} }

• parse the response body (JSON) so as to get the value for the key "accessToken"

The Access Token...

• is valid for a limited time only and when it expires, it must be renewed via this endpoint again.

• allows access only to the Cloud ID specified in the body of the request that returned it.

• must be specified when calling any other API v2 endpoint in the headers:

  Authorization: Bearer {AccessToken}

Check the access

During the development stage of your integration code you can call the following endpoint to check you have the right access token with access to the given cloud:

GET https://api.dotykacka.cz/v2/clouds/{cloudId}

Do not forget to add the request header Authorization: Bearer {AccessToken}

If it responds with http status 200 and a cloud info in the body, then you are prepared and ready to call other endpoints.

It is not needed to check the access in production code so we recommend skipping this step for a better performance of your integration code.

We recommend reading the General section in this documentation for more details that apply to most of the entity endpoints.

Uploading Delivery notes

You can upload a delivery note in a XML format by using the API call.

The XML document (structure described here) must be a valid XSD file and according to the mentioned validations. Put it as a value for the key named file in a form-data request body.

Call: POST /v2/clouds/{cloudId}/branches/{branchId}/delivery-note-uploads

In case the XML file is not accepted, please make sure it is valid according to the XSD.

Document id attribute must be a valid UUID in the form "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".

More details about the endpoint and a sample XML document can be found here.

All info about Delivery notes is here.

Managing Products

You can manage, filter and sort products by using the API calls.

Product schema describes the fields and their data types.

The GET endpoints return a single product by its ID or a list of filtered products.

You can read more about filters, sorting and paging in the General section.

The POST endpoint allows to create many products.

The PATCH endpoint is to edit a single product.

The PUT endpoint can create (like POST) or edit (like PATCH) one or more products.

Please do not round any price values (explained here)

Please see the Breaking changes page for more info on the planned changes in validation.

We recommend to read more about ETags since they are mandatory when editing entities.

When updating multiple entities, keep the same order in the PUT request as it was in the GET response that returned the ETag.

For endpoints working with a list of entities (POST/PUT), the order of entities in the response is the same as it was sent in the request .

The POST method does not expect an ID so it always creates new products.

The PUT method requires an ID so you need to generate one when you want to create a product using the PUT method.

The JSON samples labeled "Body request minimum" under the POST and PUT requests show the minimum set of fields that are required to create a new product.

When changing an entity via the PATCH endpoint, you can send only the fields that you want to update, f.e. to change the product name send body {"name": "New name"}.