Skip to main content

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.

Autorizační klíč je v HTTP hlavičce Authorization: A|xxxxx

curl -XGET 'https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/products/list' \
 -H 'Authorization: A|kLgT.........' \
 -H 'Content-Type: application/json'

POST přííklad:

curl -XPOST 'https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/reports/generic/order_history' \
 -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

  • Časy jsou reprezentovány v unix timestamp v millisekundách. Např. 1639436400000
  • Monetární hodnoty (tržba, cena, atd) jsou vždy celé číslo, vynásobené 1000. Např. cena 23.50 je v JSON dokumentu jako 23500.
  • Autorizační token nemá expiraci, ale do budoucna plánujeme že token bude muset být vyměněn za nový
  • Do User Agent prosím vložte svoji identifikaci případně kontakt, abychom měli kontakt na vývojáře
  • Pokud navrácený objekt obsahuje položku, která začíná na __ tak se jedná o tzv. hydrataci - objekt je automaticky obohacen o child objekty, aby vývojář nemusel provádět další dotazy na API.
  • Převod id na čas lze provést pomocí funkce: new Date((id / 32768) + 1440000000000);

Společné pole

  • id_c - globální ID zákazníka
  • _v - verze objektu
  • _d - indikuje jestli byl záznam označen jako smazaný
  • _t - název tabulky
  • pgx - složený interní primární klíč - ignorujte
  • pole s prefixem date_ jsou Unix UTC čas v millisekundách
  • pole s prefixem id_ jsou odkazy na záznam v jiné tabulce. Např id_shop odkazuje na id obchodu.

Funkce pro práci s id

Id je číslo složené z času, id tabulky a náhodného suffixu. Příklad výpočtu:

const EPOCH = 1440000000000;

// Vrati objekt s datem a id tabulky
function getDateFromId(id) {
  return {
    dt: new Date((id / 32768) + EPOCH),
    tableId: (id / 512) & 0x3f
  }
}

// Generuje id pro konkretni tabulku - pouzijte 0 pro referenci
function getRandomRowId(tableId) {
  let ts = new Date().getTime() - EPOCH;
  let randid = Math.floor(Math.random() * 512);
  ts = (ts * 64);
  ts = ts + tableId;
  return (ts * 512) + (randid % 512);
}

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": 111111,
    "_t": "products",
    "_v": 1641499263746
  }
]

GET product/{id}

Vrací jednotlivý produkt podle ID objektu. Pro ceny volejte get-price-by-product-id/

https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/products/{id}
Odpověď
{
  "unit": 0,
  "pgx": "111:products",
  "description_short": "Vydařená kombinace rumu a griotky",
  "date_updated": 1647012279153,
  "attributes_bitmask": 8240,
  "sale_group_type": 0,
  "condition_type": 1,
  "name": "Čert",
  "id_tax_rules_group": 0,
  "id_category": 6783340285035904,
  "node_sort": 3752073357922477000,
  "accounting_group": 600000,
  "warranty_length": 0,
  "inventory_management": true,
  "inventory_type": 0,
  "id": 6783372795320333,
  "id_shop": 0,
  "tax_eco": 1,
  "color": 0,
  "visible": true,
  "_d": 0,
  "tax_luxury": 1,
  "tax_pst_rate": 1.21,
  "item_type": 0,
  "additional_shipping_cost": 0,
  "icon_code": 0,
  "warranty_type": 0,
  "_t": "products",
  "quantity_minimal": 1,
  "_v": 1681918519463,
  "quantity_multiple": 1,
  "id_c": 111111,
  "id_exec_rule": 0
}

GET get-price-by-product-id/{id_product}

Vrací ceny pro konkrétní produkt v ceníku podle id produktu.

https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/products/get-price-by-product-id/{id_product}


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
Odpověď
[
  {
    "currency": "CZK",
    "unit_price_base_tax_excl": 30,
    "id_warehouse": 4438373662962620,
    "_d": 1,
    "dow_bitmask": 0,
    "credits_deduct": 0,
    "hour_bitmask": 0,
    "unit_price_base_tax_incl": 30,
    "id_product": 4438453021022482,
    "unit_price_regular_tax_excl": 30000,
    "points_deduct": 0,
    "date_starts": 1575450836824,
    "price_bitmask": 0,
    "_t": "product_price_matrix",
    "unit_price_a_tax_excl": 30000,
    "_v": 1633950008092,
    "id": 4438454091814580,
    "reduction_amount_a_tax_excl": 0,
    "id_shop": 0,
    "id_c": 1141932
   }
  ]

GET categories

Seznam kategorií v hiearchické struktuře

https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/categories/list
Odpověď
[
  {
    "visible": true,
    "_d": 0,
    "name": "Cakes >",
    "category_bitmask": 0,
    "icon_code": 5,
    "node_sort": 5000000,
    "id_category_sort_after": 0,
    "_t": "categories",
    "_v": 1672597351272,
    "id_category_parent": 0,
    "id": 1,
    "id_shop": 0,
    "color": 17,
    "id_c": 111111,
    "children": [
      {
        "visible": false,
        "name": "test",
        "category_bitmask": 0,
        "margin_minimal_rate": null,
        "icon_code": 4,
        "node_sort": 5000000,
        "id_category_sort_after": 0,
        "_t": "categories",
        "_v": 1640029337604,
        "id_category_parent": 1,
        "id": 1067887041152062,
        "id_shop": 0,
        "margin": null,
        "color": 5,
        "tags": null,
        "id_c": 111111,
        "children": []
      }
    ]
  }
]

GET shops

Seznam poboček (shops)

https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/shops/list
Odpověď
[
  {
    "visible": true,
    "currency": "CZK",
    "_d": 0,
    "name": "Shop 83",
    "location_name": "City 44",
    "_t": "shops",
    "_v": 1677240349376,
    "id": 492696696391111,
    "bitmask": 0,
    "id_c": 111111
  }
]

GET cash_registers

Seznam poboček. Více o struktuře a závislosti na obchodech v manuálu zde.

https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/cash_registers/list
Odpověď
[
  {
    "visible": true,
    "name": "Point of Sale 233",
    "location_name": "Brno",
    "_t": "cash_registers",
    "_v": 1640802641284,
    "cash_register_type": 11,
    "id": 49269669639111,
    "id_shop": 492696696397774,
    "bitmask": 0,
    "id_c": 11111
  }
]

GET customers

Seznam zákazníků

curl 'https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/customers/list' \
 -H 'Authorization: A|ADq
Odpověď
[
  {
    "customer_type": 0,
    "credit_account": null,
    "internal_extra": null,
    "price_group": "A",
    "zip_code": "40801",
    "date_updated": null,
    "email": null,
    "city": "RUMBURK",
    "bank_account": null,
    "date_birthday": null,
    "company": "Test s.r.o.",
    "geohash": null,
    "firstname": null,
    "company_ico": "3332650",
    "id": 3665795354036044,
    "color": 0,
    "bitmask": 0,
    "tags": "csv-import-91",
    "barcode": null,
    "visible": true,
    "id_discount_group": null,
    "lastname": null,
    "company_dic": "CZ33333",
    "internal_json": null,
    "_t": "customers",
    "_v": 1551875000154,
    "date_expires": null,
    "phone_number": null,
    "note_internal": null,
    "country_code": "CZ",
    "note_external": null,
    "id_c": "11111",
    "street": "17.8"
  }
]

GET customer/{id}

Jednotlivý záznam pro zákazníka podle ID.

https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/customers/{id}
curl 'https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/customers/12344566' \
 -H 'Authorization: A|ADqsEX...

GET orders

Vrací seznam účtenek (JSON Array), seřazené od nejnovějších po nejstarší.

Poznámky:

  • Pokud je doklad zrušený nebo stornovaný, pole date_canceled obsahuje čas zrušení (not-null)
  • reduction_percent indikuje slevu v procentech poskytnutou zakaznikovi vynasobene 1000, uvedené jako celé číslo (integer). Tzn. hodnota 500 znamená, že byla poskytnuta sleva 0.5%

Parametry

  • id_start - id záznamu od kterého se má stránkovat. výchozí hodnota 0 stránkuje od nejnovejší účtenky
  • version_start - unix epoch timestamp (ms) filtr. Hodnota 0 znamená že se hodnoty nebudou filtrovat.
  • limit - omezit počet záznamů, výchozí 250, maximum 2000. Velková velikost navráceného JSON nemůže přesáhnout 6MB
https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/orders/list?version_start=0&id_start={id_order}

GET orders/latest/{id_cash_register}

Posledních 40 orders z konkrétní pokladny podle id_cash_register. Metoda nepodporuje stránkování. Doporučujeme na získávání aktuálních objednávek v pravidelných intervalech pro systémy, které chtějí získávat online přehled o uskutečnených pohybech.

Query string parametry:

  • id_payment (optional) - ID forma platby. Např 221: hotovost, 222: kreditní parta, 238: sumup 
https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/orders/latest/{id_cash_register}?id_payment={id_payment}
Odpověď
[
  {
    "total_discounts_tax_excl": 0,
    "currency": "CZK",
    "pgx": "1141932:orders:4438373662917304",
    "total_points": 0,
    "id_employee": 0,
    "date_closed": 1642005467495,
    "total_credits": 0,
    "id_payment": 222,
    "total_paid_tax_excl": 50000,
    "total_shipping_tax_excl": 0,
    "total_tax_service": 0,
    "total_paid_real": 50000,
    "conversion_rate": 1,
    "_u_dyn": 1642005490213,
    "total_discounts_tax_incl": 0,
    "geohash": "u2ugrgc",
    "date_collected": 1642005467495,
    "total_tip": 0,
    "id_cash_register": 4438373662917304,
    "id": 6619285123010267,
    "dine_in": true,
    "id_shop": 4438373662924485,
    "total_products": 1,
    "total_tax_gst": 0,
    "total_profit_tax_excl": 0,
    "order_serial_number": 130,
    "summary": "1x Pure bar",
    "id_park_location": 0,
    "total_wrapping_tax_incl": 0,
    "_d": 0,
    "total_tax_eco": 0,
    "total_tax_pst": 0,
    "total_shipping_tax_incl": 0,
    "id_employee_served": 0,
    "date_paid": 1642005467185,
    "id_shift": 6618245790277082,
    "total_profit_tax_incl": 0,
    "date_tax_reported": 1642005467495,
    "_t": "orders",
    "total_paid_tax_incl": 50000,
    "_v": 1642005467521,
    "total_wrapping_tax_excl": 0,
    "total_tax_luxury": 0,
    "invoice_number": 202012274,
    "id_c": 1141932
   }
  ]

GET order/{id_cash_register}/{id_order}

Umožní získat účtenku/doklad včetně položek v poli __order_details

https://m6vadtaz1h.execute-api.eu-west-1.amazonaws.com/prod/data/orders_details/{id_cash_register}/{id_order}
{
  "total_discounts_tax_excl": 0,
  "currency": "CZK",
  "pgx": "1173665:orders:7694791899251239",
  "total_points": 0,
  "id_employee": 1,
  "date_closed": 1684414596504,
  "total_credits": 0,
  "id_payment": 222,
  "total_paid_tax_excl": 56522,
  "total_shipping_tax_excl": 0,
  "total_tax_service": 0,
  "date_fiscalized": 0,
  "total_paid_real": 65000,
  "conversion_rate": 1,
  "total_discounts_tax_incl": 0,
  "date_collected": 1684414596504,
  "total_tip": 0,
  "id_cash_register": 7694791899251000,
  "id": 8008974168592088,
  "dine_in": true,
  "id_shop": 7694791899258554,
  "total_products": 2,
  "total_tax_gst": 0,
  "total_profit_tax_excl": 0,
  "order_serial_number": 320,
  "id_park_location": 0,
  "total_wrapping_tax_incl": 0,
  "_d": 0,
  "total_tax_eco": 0,
  "total_tax_pst": 8478,
  "total_shipping_tax_incl": 0,
  "id_employee_served": 1,
  "date_paid": 1684414596504,
  "id_shift": 7962837799869694,
  "total_profit_tax_incl": 0,
  "date_tax_reported": 1684414596504,
  "_t": "orders",
  "total_paid_tax_incl": 65000,
  "_v": 1684414596517,
  "total_wrapping_tax_excl": 0,
  "total_tax_luxury": 0,
  "invoice_number": 202305288,
  "id_c": 11111,
  "date_canceled": null,
  "__order_details": [
    {
      "product_item_type": 0,
      "currency": "CZK",
      "pgx": "1173665:order_details:7694791899251239",
      "total_points": 0,
      "id_warehouse": 0,
      "id_employee": 1,
      "date_updated": 1684414596517,
      "total_credits": 0,
      "id_payment": 222,
      "id_product": 7833117185743150,
      "_u_dyn": 1684414622686,
      "reduction_amount_tax_incl": 0,
      "id_category": 7694792007615808,
      "id_order": 8008974168592088,
      "product_name_alternative": ":;en:Cappuccino",
      "product_price_billed_tax_incl": 35000,
      "id_order_details_parent": 1,
      "id_cash_register": 7694791899251000,
      "id": 8008976796814560,
      "id_shop": 7694791899258554,
      "product_quantity": 1,
      "product_bitmask": 0,
      "product_name": "Cappuccino",
      "_d": 0,
      "total_tax_eco": 0,
      "total_tax_pst": 4565,
      "reduction_amount_tax_excl": 0,
      "product_price_billed_tax_excl": 30435,
      "product_unit": 0,
      "product_price_original_tax_excl": 30435,
      "tax_pst_rate": 1.15,
      "date_paid": 1684414596517,
      "id_shift": 7962837799869694,
      "_t": "order_details",
      "_v": 1684414596517,
      "order_number": 320,
      "total_tax_luxury": 0,
      "reduction_percent": 0,
      "id_c": 11111,
      "date_voided": null,
      "date_canceled": null
    }
  ]
}

GET order_details

Vrací položky účtenek. Jedná se  o child kolekci objektu orders.

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

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": 111111,
      "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": 111111,
      "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"
}
Back to top