Development Quickstart Guide

API documentation
Introduction

Get up and running with our client libraries and start developing your Keemova integration.

Integrating Keemova into your ERP/TMS/WMS can begin as soon as you create a Keemova account, requiring only two steps:

- Obtain your API keys so Keemova can authenticate your integration’s API requests
- Make a test API request to confirm everything is up and running

Step 1: Obtain your API key
Keemova authenticates your API requests using your account’s API key. If you do not include your key when making an API request, or use one that is incorrect or outdated, Keemova returns an error.

Your API key is available in the settings area of your Keemova account.

If you cannot see your secret API key in the settings section of your Keemova account, this means you do not have access to them. Contact your Keemova account’s owner and ask to be added to their team as a developer.

Step 2: Make a test API request
To check that your integration is working correctly, make a test API request using your test secret key to create a transportation order.

We include randomly generated API keys in our code examples. Replace these with your own to see code examples populated with your own API key.

Once you have successfully made an API request, you’re ready to begin integrating Keemova into your business workflow.

Next steps
Works fine? Perfect! Read on to begin integrating Keemova:

API Reference

The Keemova API uses „Hypermedia as the Engine of Application State“ (HATEOAS). This is a component of the REST application architecture. With HATEOAS, you interact with our network application whose application servers provide information dynamically through hypermedia.

Authentication
You will need your company’s API key to authenticate your requests. It should look like the following example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiI2Iiwicm9sZSI6Ik1hbmFnZXJVc2VyIiwiZW1haWwiOiJibGcudGVzdEBrZWVtb3ZhLmFzc2Vjb3IuZGUiLCJ1bmlxdWVfbmFtZSI6ImJsZy50ZXN0QGtlZW1vdmEuYXNzZWNvci5kZSIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvdmVyc2lvbiI6Iklnbm9yZSIsIktlZW1vdmEuQ29tcGFueUlkIjoiMSIsIktlZW1vdmEuVG9rZW5UeXBlIjoiRW1haWwiLCJLZWVtb3ZhLkZpcnN0TmFtZSI6IkJMRyIsIktlZW1vdmEuTGFzdE5hbWUiOiJUZXN0IiwibmJmIjoxNTcyMDAwMzExLCJleHAiOjE4ODc2MTk1MTEsImlhdCI6MTU3MjAwMDMxMX0.12MNzjepqQ8U7eQThWkC-0IUd8XqY3GABjSAOqRC4Nc

Authorization
Keemova uses JWT bearer tokens as API keys. Each request should have the “Authorization” header set to “Bearer <token-in-base64-format>”. For API interaction, simply get the “Authorization” request header to the value of your API key. With the API key example provided in the Authentication section above, a proper request would be like so:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiI2Iiwicm9sZSI6Ik1hbmFnZXJVc2VyIiwiZW1haWwiOiJibGcudGVzdEBrZWVtb3ZhLmFzc2Vjb3IuZGUiLCJ1bmlxdWVfbmFtZSI6ImJsZy50ZXN0QGtlZW1vdmEuYXNzZWNvci5kZSIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvdmVyc2lvbiI6Iklnbm9yZSIsIktlZW1vdmEuQ29tcGFueUlkIjoiMSIsIktlZW1vdmEuVG9rZW5UeXBlIjoiRW1haWwiLCJLZWVtb3ZhLkZpcnN0TmFtZSI6IkJMRyIsIktlZW1vdmEuTGFzdE5hbWUiOiJUZXN0IiwibmJmIjoxNTcyMDAwMzExLCJleHAiOjE4ODc2MTk1MTEsImlhdCI6MTU3MjAwMDMxMX0.12MNzjepqQ8U7eQThWkC-0IUd8XqY3GABjSAOqRC4Nc

How to Use This API

API Routes
Our API endpoints are in different services, each with their own host. The routes for these services and endpoints are in this format:

https://app.keemova-logistics.de/api/<service>/<endpoint>

The <service> is in kebab-case format, like so:

https://app.keemova-logistics.de/api/order/<endpoint>

Request Format
GET request parameters are in the URL query string. All other requests should send their data in the request body as a JSON object. The object contents are dependent on the API method.

Response Body
All responses to valid requests should be a JSON object with links for HATEOAS architecture. If the request has business logic errors, the "errors" property should be set. The response code for errors will still be 200 (OK).

Authentication or authorization errors will return codes 401 (Unauthorized) and 403 (Forbidden) respectively. The response body will be empty.

This is the format for the response body:

{

 data: {

   <API method-specific data in JSON format>

 },

 links: {

   ‘<name of link1>’: {

     method: '<HTTP method>',

     url: '<url>'

   },

   ‘<name of link2’> {

      ...

   },

   ...

 },

 errors: [

   'Error #1',

   'Error #2',

   ...

 ]

}

If the response data is a list of entities, the “data” property will contain similar nested objects with “data” and “links”. Here is an example:

{

 data: {

   orderList: [

     {

       data: {

         id: 1234,

         ...

       },

       links: {

         viewDocuments: {

           method: 'GET',

           url: 'api/v1/documents?orderId=1234'

         },

         ‘<name of link2>’: {

           ...

         }

       }

     }

   ]

 }

}

Company API Usage

Company Registration
Companies can sign up via https://www.keemova-logistics.de/signup and get their Keemova API key, to access the Keemova API.

Company Login
Companies can login via https://www.keemova-logistics.de/login. After login, companies have multiple options to access the Keemova freight handling services.

Service URLs
Order service:

https://app.keemova-logistics.de/api/order/

Document service:

https://app.keemova-logistics.de/api/document/

Create an Order
To create an order, POST to

https://app.keemova-logistics.de/api/order/orders

with the following body:

{

 "name": "string",

 "companyId": {your company id},

 "truckLicensePlate": "string",

 "earliestPickupDate": "YYYY-MM-DDTHH:MM:SS.SSSZ",

 "latestDeliveryDate": "YYYY-MM-DDTHH:MM:SS.SSSZ",

 "pickupAddress": {

   "address1": "string",

   "address2": "string",

   "address3": "string",

   "street": "string",

   "city": "string",

   "cityCode": "string",

   "countryCode": "string"

 },

 "deliveryAddress": {

   "address1": "string",

   "address2": "string",

   "address3": "string",

   "street": "string",

   "city": "string",

   "cityCode": "string",

   "countryCode": "string"

 },

 "emailContacts": [

   {

     "contactType": "string",

     "emailAddress": "string",

     "name": "string"

   }

 ]

}

The name parameter is used for the company’s internal order ID. It can be any identifier one uses for the order, such as, “1234-ABCD-00”. It must be unique.

The date parameters earliestPickupDate and latestDeliveryDate should be strings in ISO date format. A time difference can be specified, but it will always be stored as UTC. Any dates retrieved will be returned in UTC format as well.

Email receiver from concerned order parties should be added in the email parameter. They will receive order update information (handovers, added signatures, order closing) automatically.

The response body’s data property will look like this – take note of the id parameter, you will need it later to create documents and upload their content.

"data": {

 "id": {your company id},

 "name": "string",

 "truckLicensePlate": "string",

 "earliestPickupDate": "YYYY-MM-DDTHH:MM:SS.SSSZ",

 "latestDeliveryDate": "YYYY-MM-DDTHH:MM:SS.SSSZ",

 "pickupAddress": {

   "address1": "string",

   "address2": "string",

   "address3": "string",

   "street": "string",

   "city": "string",

   "cityCode": "string",

   "countryCode": "string"

 },

 "deliveryAddress": {

   "address1": "string",

   "address2": "string",

   "address3": "string",

   "street": "string",

   "city": "string",

   "cityCode": "string",

   "countryCode": "string"

 },

 "emailContacts": [

   {

     "contactType": "string",

     "emailAddress": "string",

     "name": "string"

   }

 ]

}

Create a Document
Once an order is created, you can upload a freight document. First you will need to create the document entry. You can upload its content afterwards.

POST
to

https://app.keemova-logistics.de/api/document/documents?getIfExists=false

with the following body:

{

 "orderId": <id of order>,

 "name": "<unique name of document>",

 "type": "Document",

 "label": "<type of document>",

 "properties": {}

}

orderId is what we received as “id” when creating our order.

The name property is a unique name used for display.
The type property must be “document”.
The label property can be one of the following:

- “CMR” This is the CMR. There should only be one of these per order.
- “DeliveryNote” This is the Lieferschein. There should only be one of these per order.
- null The label is null or missing for any other type of freight document.

The properties can be ignored for now – this isn’t relevant if type is “Document”.

The response body’s data property will look like this – take note of the id parameter, you will need it later to upload the document content.

{

   "id": 21,

   "name": "My New Document",

   "type": "Document",

   "category": "FreightPaper",

   "label": "CMR",

   "properties": {}

}

Upload Document Content
Now that the document exists, you can upload its content. For this API routine, the request body is not a JSON object, but rather a multipart/form-data request. Set “Content-Type” accordingly. To upload content:

PUT to:

https://app.keemova-logistics.de/api/document/documents/{id}/content?closeOrder=false

Where {id} is the document id we received when uploading the document.

This method currently returns no data.

Other Useful Methods
For more details, please see the API reference later in this documentation.

Get all orders:

https://app.keemova-logistics.de/api/order/orders

View a specific order:

https://app.keemova-logistics.de/api/order/orders/{id}

View documents for an order:

https://app.keemova-logistics.de/api/document/documents?orderId={id}

View a specific document:

https://app.keemova-logistics.de/api/document/documents/{id}

Download a document’s content:

https://app.keemova-logistics.de/api/document/{id}/content?zip=[false/true]

Company WebUI Usage
Company Registration

Companies can sign up via https://www.keemova-logistics.de/signup and get their Keemova API key, to access the Keemova API or use the Keemova WebUI to organize their Keemova freight document services.

Company Login

Companies can login via https://www.keemova-logistics.de/login. After login, companies have multiple options to access the Keemova freight handling services:

- Assign trucks and roles
- Edit account details
- Subscripe to a service plan
- Use the Keemova WebUI to handle orders

Assign trucks

Transportation orders are related to company trucks. Handling orders with Keemova thus requires assigning trucks to the company first. The company account provides a form to do this fast and efficiently.

Assign roles

Keemova provides three basic roles: company administrators, drivers and supervisors.

Roles

Company Administrators
The company administrator holds the company’s account credentials. After company registration, the company administrator can assign company members to roles to work with Keemova. The company members will get an email invitation from Keemova after assignment (please check your junk mail folder if you can’t findthe invitation note). The company administrator can edit the company’s account and payment details as well as select the subscription plans to the Keemova services.

Drivers
Drivers handle freight documents related to a transportation order during their tour. They get a Keemova invitation note from their company to access Keemova. After successfully signing up, the drivers can log in to the Keemova App. Logged-indrivers can scan the QR code of their trucks (QR codes need to be distributed before the start of the tour) to get access to all orders assigned to the truck.

Supervisors
Supervisors can create new transportation orders and add (freight) documents to the orders using the Keemova WebUI form. To have it more automized, simply connect your ERP/ TMS/ WMS to the Keemova API and transfer your order information.