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.

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 čas v millisekundách
pole s prefixem id_ jsou odkazy na záznam v jiné tabulce. Např id_shop odkazuje na id obchodu.

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)

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
    },
    {11111,
      "product_item_type"date_voided": 0,null,
      "currency"date_canceled": "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": 7833607305664820,
      "_u_dyn": 1684414622706,
      "reduction_amount_tax_incl": 0,
      "id_category": 7833063174472996,
      "id_order": 8008974168592088,
      "product_name_alternative": ":;en:Bombus bar",
      "product_price_billed_tax_incl": 30000,
      "id_order_details_parent": 1,
      "id_cash_register": 7694791899251000,
      "id": 8008977175973266,
      "id_shop": 7694791899258554,
      "product_quantity": 1,
      "product_bitmask": 0,
      "product_name": "Bombus tyčinka",
      "_d": 0,
      "total_tax_eco": 0,
      "total_tax_pst": 3913,
      "reduction_amount_tax_excl": 0,
      "product_price_billed_tax_excl": 26087,
      "product_unit": 0,
      "product_price_original_tax_excl": 26087,
      "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": 11111null
    }
  ]
}

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"
}