.. meta::
  :description: Zak API introduction
  :keywords: api, pms, zak, introduction, error, authentication, response

Introduction
************

Commercial Guidelines 
=====================

| The Zak approach toward connectivity respects the principle of the company.
|
| We do consider a **right of the user** the possibility to programmatically manage his contents
| (data ownership and provider duties).
|
| At the same time, supporting relevant volumes of traffic is a very expensive goal. So, we did 
| decide to provide the Zak API only for customers activating the Essentials Module.
|
| The **activation of the Essentials Module** allows the usage of a Property Key. Nothing more 
| is required. Notice also that **we do not provide support for providers**. At least genericallly. 
| If you need support, please, reach our commercial team to discuss about this possibility.
|
| From another perspective, should you be an IT company with commercial plans, needing a PMS 
| technical partner, we can work with a **tailored approach**. Studying together solutions and 
| commercial opportunities, with the goal of a Win-Win context. 
|
| **IMPORTANT NOTICE**: it often happens that bad implementations generate too much volume, 
| stressing our servers and damaging the zak network. Under such circumstances, we 
| could block abusing clients. 


WILL BE REPLACED FUNCTIONS
==========================

| The WILL BE REPLACED functions will be improved by publishing better calls in the 
| future. When? We don't know with precision. However, when improvements will be
| available, such WILL BE REPLACED functions will stay for several months before
| desappearing, with the goal to sustain the connectivity processes. 

| Such changes will be communicated in two ways. 

| Each API KEY can be associated to an email. We will for sure send information to 
| such email addresses.

| Tailored partners (having their own and unique API service) will be informed
| personally.


Basic URL
=========

|  To use the api is enough to make a simple POST call to the addresses of our resources.

.. code-block:: html

  Starting url: https://kapi.wubook.net/kapi/


Field types
===========

|  Each *date field* has the European format *dd/mm/yyyy*.
|  The data that fills the *country field* must be 2 characters `ISO country code`_.
|  The *currency fields* should contain `ISO currency code`_.

.. _ISO country code: https://en.wikipedia.org/wiki/ISO_3166-1

.. _ISO currency code: https://en.wikipedia.org/wiki/ISO_4217

Authentication
==============


|  To use our API it is necessary to provide the **customer api-key** as header in each request.
|  The Key is generated by enabling the Essentials Module and entering its Settings.
|
|  Each of the following examples will be provided with a fake customer api-key *123456*.
|
|  The customer of the ZaK pms could specify a whitelist of  **list of IP**,
|  in this case only calls from one of those IPs are authorized.

Response
========

|  The response is always an object with one field: **data** or **error**.
|  The **error** field contains a text that describes the error.
|  The **data** field contains the results.
|
|  To interpret the symbols that an api returns or to know the symbol
|  to be sent as input you can get the zak symbols from the `api-symbols`_.

.. _api-symbols: ./symbols.html#zak-api-to-read-symbols

Examples
--------

|  The endpoint **test** could be used to check your *api-key*,
|  it does not require other input parameters.
|  On the examples *123456* is used as **api-key**
|  which is sent as *user*.

python code:
............
.. code-block:: python

  import requests
  uspw=(123456, None)
  response= requests.post('https://kapi.wubook.net/kapi/test', {}, auth= uspw)
  print(response.text)
  {"data": "Authentication done!"}

In case of error the response key is **error** and provides an error-description.

.. code-block:: python

  import requests

  uspw=(654321, None)
  response= requests.post('https://kapi.wubook.net/kapi/test', data={}, auth= uspw)
  print(response.text)
  {"error": "Authentication error"}

  uspw=(123456, None)
  response= requests.post('https://kapi.wubook.net/kapi/tset', data={}, auth= uspw)
  print(response.text)
  {"error": "Wrong api name: tset"}

curl:
.....
.. code-block:: shell

  $ curl https://kapi.wubook.net/kapi/test -u 123456: -X POST
  {"data": "Authentication done!"}