API propojení a integrace

Načtení objednávky z externího API souboru


Aplikace KASA FIK nabízí možnost importu již přednastavených objednávek/faktur ze stávajícího informačního systému pomocí stáhnutí JSON dokumentu. Prodejce tak může načíst předpřipravenou objednávku s položkami, číslem účtenky i poznámkami. Používá se v mobilním a sanitárním prodeji, prodeji z eshopu a jiných situacích, kdy dochází jen k dokončení tržby na zařízení a objednávka byla připravena předem.

Funkce je dostupná pouze v edici PREMIUM

Nastavení

  1. V Nastavení – Expert nastavení – Importní URL pro objednávky zadejte URL adresu k Vašemu rozhraní na serveru
  2. Daná URL adresa musí vrátit platný dokument JSON ve formátu popsaném níže
  3. Adresa je například: https://www.mujserver.cz/hledat.php
  4. Aplikace připojí parametr „search“ s volbou, kterou zadá uživatel. to znamená že bude voláno např. https://www.mujserver.cz/hledat.php?search=220001

Používání

  1. V aplikaci, v rozhraní KLASIK
  2. Vlevo nahoře klepněte na šipku menu
  3. Zvolte „Vyhledat položky z objednávky“
  4. Zadejte číslo objednávky, které se použije k vyhledání dané objednáky na serveru
  5. Pokud se objednávka nelezne, dojde k vyplnění položek

Popis formátu 

Formát JSON platné odpovědi

{
  "invoice_number": 20130001, // optional, will be generated if not provided
  "note": "strestt", // optional
  "items": [
    {
      "plu": "203", // optional
      "note": "Item optional note" // optional
      "name": "Item number 203",
      "price_without_vat": 112.0,
      "quantity": 1.0,
      "vat_rate": 1.21
    }
  ]
}

Formát JSON prázdné odpovědi pokud server nic nenalezl

Pokud uživatel zadá neplatný kód faktury, měl by server vrátit chybu 404 - Not found v hlavičce a odpověd v těle by měla obsahovat null

null

Propojení na informačním systémem (web integrace)

Aplikace KASA FIK umožňuje dynamicky integrovat webové aplikace zákazníka pomocí integrovaného tlačítka nebo funkční klávesy. Propojení je ideální pro přenos objednávek z eshopu nebo účetních systémů přímo do aplikace.

Funkce je dostupná pouze s licencí PREMIUM

custom-button.gif

Princip funkce - workflow

Ukázková stránka

Vytvořili jsme ukázkovou stránku, ve které můžete vidět funkce, které lze využít při práci v aplikaci a návrtatu hodnot.

Příklad poskytnutých parametrů v URL:

partner_code=XXXXX&utm_source=app-com.eetterminal.pos&utm_medium=app&utm_campaign=fik-integration&app_flavor=fik&app_version=1.181-beta12-debug&app_version_code=181&app_lang=cs&shop_id=848428671200000&cash_register_id=2044577243700000&shift_id=5132358187320000
Query String poskytnutý při volání URL

Specifikace integrace

Aplikace načte uživatetem přednastavené URL, které obohatí o Query String s dalšími parametry. Rozšíří Javascript funkce o interface window.FikApiInterface který obsahuje metody použitelné k propojení nativní Android aplikace s webovou.

if (window.FikApiInterface){
    window.FikApiInterface.logError('heyho'); // log error message to android console
    window.FikApiInterface.logInfo('heyho'); // log info message to android console
    window.FikApiInterface.setTitle(document.title); // sets title of the window
    window.FikApiInterface.showToast('heyho'); // shows small toast notification
    // window.FikApiInterface.finish(); // Will close the window without any result
    // window.FikApiInterface.finishWithReceipt(JSON.stringify(obj)); // return back to the app with receipt data
} else {
  // Not loaded within Fik Webapp container
}

Návrat účtenky do aplikace

Zavolejte metodu window.FikApiInterface.finishWithReceipt(JSON.stringify(obj)) s následujícim JSON objektem:

{
  "invoice_number": 20130001, // optional, will be generated if not provided
  "note": "strestt", // optional
  "items": [
    {
      "plu": "203", // optional
      "note": "Item optional note" // optional
      "name": "Item number 203",
      "price_without_vat": 112.0,
      "quantity": 1.0,
      "vat_rate": 1.21
    }
  ]
}

Poznámky k poskytovanému objektu:

Nastavení expirace a vliv na cache (expire)

Webová integrace respektuje správné nastavení cache hlavičky pro ukládání do paměti prohlížeče. Nastavíte-li správné Expire v HTTP hlavičce, bude se respektovat.

Aplikace má také podporu pro ukládání databází a Webstorage.

Webhook Integrace API

Webhooky umožňují zasílání dat z pokladny/backoffice pomocí HTTP volání informovat o každé události (např. vystavení účtenky, založení zákazníka). Zpracováním webhooků si můžete měnit chování stránky nebo aplikace a rozšiřovat je o nové funkce.

Webhooky lze nastavit v Backoffice v Nastavení - Systém - Webhooky. Zadejte https:// adresu kam systém má zasílat data. Nastavení uložte tlačítkem Uložit. Pak následně může trvat nějaký čas, než systém začne automaticky data zasílat. Nové nastavení může trvat až 1-2 hodiny, než se projeví nastavení skrz  systémy.

Screenshot-from-2020-10-19-12-50-48.png

Formát zasílaných dat

Příklad zaslaného objektu `orders`

{
  "_t": "orders",
  "_v": 1541274974010,
  "conversion_rate": 1,
  "currency": "CZK",
  "dine_in": false,
  "id": 3317888960569993,
  "id_c": 100000,
  "id_cash_register": 3173505578999348,
  "id_employee": 1,
  "id_employee_served": 1,
  "id_park_location": 3227505427363220,
  "id_shift": 3317259000928416,
  "id_shop": 3173505578310000,
  "order_serial_number": 103,
  "total_credits": 0,
  "total_discounts_tax_excl": 0,
  "total_discounts_tax_incl": 0,
  "total_paid_real": 3331000,
  "total_paid_tax_excl": 3331000,
  "total_paid_tax_incl": 3331000,
  "total_points": 0,
  "total_products": 32,
  "total_profit_tax_excl": 0,
  "total_profit_tax_incl": 0,
  "total_shipping_tax_excl": 0,
  "total_shipping_tax_incl": 0,
  "total_tax_eco": 0,
  "total_tax_gst": 0,
  "total_tax_luxury": 0,
  "total_tax_pst": 0,
  "total_tax_service": 0,
  "total_tip": 0,
  "total_wrapping_tax_excl": 0,
  "total_wrapping_tax_incl": 0
}

 

REST API

Data z pokladen jsou pravidelně synchronizována do cloudu a zpřístupněna přes REST API.

API je v současné době poskytováno v omezeném režimu. Do budoucna plánujeme expiraci autorizačního tokenu. Pokud chcete získávat kontinuáně data a synchronizovat systémy doporučujeme používat Webhooky. Jedná se o efektivnější způsob.

Autorizace požadavku

Autorizace probíhá pomocí API Tokenu, který naleznete v Backoffice - Nastavení - Systém.

curl 'https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/reports/generic/order_history' \
 -H 'Accept: application/json' \
 -H 'Authorization: A|kLgT.........' \
 -H 'Content-Type: application/json' \
 --data-raw '{"date_start":1639436400000,"date_end":1642028399999,"timezone":"Europe/Prague","id_cash_register":953221254382092,"id_shop":492696696397774}' \

Konvence

GET products

Vrací JSON Array se seznamem produktů. Položky které jsou smazané, mají nastaveno _visible = false

https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/products/list

CURL příklad

curl 'https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/products/list' \
-H 'Authorization: A|......'
Odpověď
[
  {
    "unit": 0,
    "date_updated": 1641499263724,
    "attributes_bitmask": 8208,
    "__price_matrix_model": {
      "date_starts": 1640070857424,
      "unit_price_base_tax_incl": 550,
      "unit_price_regular_tax_excl": 454546,
      "unit_price_c_tax_excl": 0,
      "credits_deduct": 0,
      "hour_bitmask": 0,
      "points_deduct": 0,
      "reduction_amount_a_tax_excl": 0,
      "id_exec_rule": 0,
      "id_product": 6555921856010421,
      "unit_price_b_tax_excl": 0,
      "dow_bitmask": 0,
      "price_bitmask": 0,
      "unit_price_base_tax_excl": 454.5455,
      "id_shop": 0,
      "currency": "CZK",
      "unit_price_a_tax_excl": 454546,
      "id": 6555922259744395,
      "id_warehouse": 953221254427235,
      "_t": "product_price_matrix",
      "_v": 1641499263728
    },
    "condition_type": 0,
    "name": "Cesta",
    "id_category": 5723345161520367,
    "node_sort": -6680027574804497000,
    "inventory_management": false,
    "id": 6555921856010421,
    "id_shop": 0,
    "color": 0,
    "visible": true,
    "tax_pst_rate": 1.21,
    "item_type": 0,
    "icon_code": 0,
    "quantity_minimal": 1,
    "quantity_multiple": 1,
    "id_c": 100084,
    "_t": "products",
    "_v": 1641499263746
  }
]

GET product_price_matrix

Ceny k produktům. Je nutné napárovat pomocí id_product

https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/product_price_matrix/list

GET categories

Vrací JSON Array se seznamem kategorií

https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/categories/list

GET orders

Vrací seznam účtenek, seřazené od nejnovějších po nejstarší. Je nutné poskytnout ID objektu orders, od kterého se vrací záznamy.

https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/orders/list?version_start=0&id_start=6619280915435403

GET order_details

Vrací položky účtenek

https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/order_details/list?version_start=0&id_start=6619280915435403

POST warehouse_status

Aktuální stav skladu. Je nutné zaslat JSON request s id_warehouse který určuje ID skladu, pro který chcete report.

curl 'https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/reports/generic/warehouse_status' \
  -H 'Accept: application/json' \
  -H 'Authorization: A|....' \
  -H 'Content-Type: application/json' \
  --data-raw '{"id_warehouse":953221250000000}'
Odpověď
{
  "data": [
    {
      "id_c": 100084,
      "id_warehouse": 953221254427235,
      "wname": "WAREHOUSE MAIN 21",
      "id_product": 5128991459121170,
      "pname": "Aperol",
      "cname": null,
      "id_category": 4933809643652539,
      "barcode": null,
      "ean13": null,
      "unit": 0,
      "qty_cnt": 1,
      "qty_sum": 3,
      "qty_avg": 3,
      "date_updated": 1641489385000,
      "pp_avg": 10000,
      "pp_unit": 10000
    },
    {
      "id_c": 100084,
      "id_warehouse": 953221254427235,
      "wname": "WAREHOUSE MAIN 21",
      "id_product": 4305305643161675,
      "pname": "01.Vstup 8225",
      "cname": "ACesty",
      "id_category": 5723345161520367,
      "barcode": null,
      "ean13": null,
      "unit": 0,
      "qty_cnt": 1,
      "qty_sum": 6,
      "qty_avg": 6,
      "date_updated": 1642004221000,
      "pp_avg": 100000,
      "pp_unit": 100000
    }
  ],
  "source": "query"
}