API pro čtení analytických dat

HTTP API api.jonot.io/v1/* poskytuje přístup pouze pro čtení k datům o lístcích a frontách vaší organizace — bez nutnosti přihlášení do administrace, stačí bearer token. Použijte jej ke stažení dat do datového skladu, BI nástroje nebo vlastního přehledu.

Upozornění

API je dostupné od tarifu Pro a výše. Karta API tokenů na stránce Integrace zobrazuje na tarifu Starter výzvu k upgradu.

Získání tokenu

1. Otevřete admin.jonot.io/settings/integrations.
2. Klikněte na kartu API tokeny.
3. Klikněte na Vytvořit token, zadejte název (např. „Power BI“) a potvrďte.
4. Zkopírujte token ihned — zobrazí se pouze jednou a nelze jej znovu získat. Pokud jej ztratíte, zrušte jej a vytvořte nový.

Tokeny mají prefix jot_ a samy o sobě nikdy nevyprší; zrušte je na stejné kartě, jakmile je již nepotřebujete.

Autentizace

Nebezpečí

Token posílejte pouze v hlavičce Authorization. Nikdy jej neuvádějte v query stringu — query stringy končí v access logách, proxy logách a historii prohlížeče. Token předaný přes ?token=... bude odmítnut s 401.

Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Stav	Význam
401	Chybějící, chybně formátovaný, neznámý nebo zrušený token.
402	Platný token, ale organizace nemá povolenou funkci API.
429	Překročen limit počtu požadavků — viz Limity požadavků níže.
400	Neplatné parametry dotazu, nebo časové rozmezí delší než 90 dní.

Endpointy

GET /v1/queues

Vrátí pobočky a fronty vaší organizace, nefiltrované a nestránkované:

curl https://api.jonot.io/v1/queues \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "locations": [
    {
      "id": "loc_…",
      "name": "Downtown",
      "slug": "downtown",
      "queues": [
        {
          "id": "q_…",
          "name": "Main Queue",
          "slug": "main-queue",
          "status": "ACTIVE"
        }
      ]
    }
  ]
}

Vrácené hodnoty id použijte k filtrování /v1/tickets a exportu CSV podle queueId / locationId.

GET /v1/tickets

Stránkované čtení lístků, omezené na vaši organizaci.

Parametr	Povinný	Opakovatelný	Poznámky
from	ano	ne	ISO-8601, včetně dolní hranice na createdAt.
to	ano	ne	ISO-8601, vyjma horní hranice. Max. rozmezí 90 dní.
queueId	ne	ano	Parametr opakujte pro filtrování více front.
locationId	ne	ano	Parametr opakujte pro filtrování více poboček.
status	ne	ano	Jedna z hodnot WAITING, CALLED, COMPLETED, CANCELED, SKIPPED, NO_SHOW.
cursor	ne	ne	Neprůhledná hodnota z nextCursor předchozí stránky.
limit	ne	ne	Výchozí 100, max. 500.

curl "https://api.jonot.io/v1/tickets?from=2026-06-01T00:00:00Z&to=2026-06-08T00:00:00Z&status=COMPLETED" \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "items": [
    {
      "id": "tkt_…",
      "number": 42,
      "queueId": "q_…",
      "locationId": "loc_…",
      "status": "COMPLETED",
      "createdAt": "2026-06-01T09:14:02.000Z",
      "calledAt": "2026-06-01T09:20:11.000Z",
      "completedAt": "2026-06-01T09:24:47.000Z",
      "cancelledAt": null,
      "skippedAt": null,
      "noShowAt": null,
      "calledByDeviceSessionId": "dev_…"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQi…"
}

Řádky nikdy neobsahují bearer hash lístku ani žádné osobní údaje zadané zákazníkem (jméno, poznámky, počet osob) — pouze id, stav a časová razítka životního cyklu.

Stránkování: pokud je nextCursor odlišné od null, předejte jej jako cursor v dalším požadavku a pokračujte tam, kde jste skončili (stejné from/to/filtry). Hodnota nextCursor rovna null znamená, že jste dosáhli konce rozmezí.

GET /v1/exports/tickets.csv

Stejné filtry jako /v1/tickets (from/to povinné, queueId/locationId/status opakovatelné) mínus cursor/limit — celé odpovídající rozmezí se streamuje jako jedna odpověď CSV, takže při hromadném stažení není potřeba obcházet limit 500 řádků na stránku.

Pořadí sloupců je stabilní, ale sloupce parsujte podle názvu hlavičky, ne podle pevné pozice. Řádek s hlavičkou je vždy přítomen a přesně odpovídá tomuto seznamu:

id,number,queueId,locationId,status,createdAt,calledAt,completedAt,cancelledAt,skippedAt,noShowAt,calledByDeviceSessionId

curl "https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -o tickets.csv

Odpověď se streamuje (Transfer-Encoding: chunked), takže export za 90 dní / 100 tisíc řádků nemusí být bufferován v paměti na žádné straně — pošlete jej rovnou do souboru nebo parseru.

Limit rozmezí 90 dní

Každý endpoint, který přijímá from/to, odmítne rozmezí delší než 90 dní chybou 400. Pokud potřebujete delší historii, stahujte data postupně (např. jedno volání týdně) — časová razítka životního cyklu lístku (calledAt, completedAt, …) vám umožní zpětně rekonstruovat dobu čekání a obsluhy bez opakovaného stahování stejných řádků.

Limity požadavků

60 požadavků za minutu na token (ne na IP adresu — limit se váže k tokenu). Každá odpověď obsahuje:

X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1751328000000

Odpověď 429 navíc obsahuje Retry-After (v sekundách). Počkejte a zkuste to znovu po tomto intervalu; naplánovaná synchronizace každých pár minut se pohodlně vejde pod limit.

Python + pandas

import requests
import pandas as pd

TOKEN = "jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE = "https://api.jonot.io/v1"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

def fetch_tickets(frm: str, to: str) -> pd.DataFrame:
    rows = []
    cursor = None
    while True:
        params = {"from": frm, "to": to, "limit": 500}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(f"{BASE}/tickets", headers=HEADERS, params=params, timeout=30)
        res.raise_for_status()
        body = res.json()
        rows.extend(body["items"])
        cursor = body["nextCursor"]
        if not cursor:
            break
    return pd.DataFrame(rows)

df = fetch_tickets("2026-06-01T00:00:00Z", "2026-07-01T00:00:00Z")
df["waitSeconds"] = (
    pd.to_datetime(df["calledAt"]) - pd.to_datetime(df["createdAt"])
).dt.total_seconds()
print(df.groupby("queueId")["waitSeconds"].mean())

Nebo přečtěte export CSV přímo — pandas zvládá streamovanou odpověď transparentně:

df = pd.read_csv(
    f"{BASE}/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z",
    storage_options={"Authorization": f"Bearer {TOKEN}"},
)

Power BI (webový konektor)

1. V aplikaci Power BI Desktop: Získat data → Web.
2. Zvolte Pokročilé a sestavte URL s vaším časovým rozmezím, např. https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z.
3. V sekci Parametry hlavičky HTTP požadavku přidejte hlavičku s názvem Authorization a hodnotou Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
4. Klikněte na OK — Power BI rozpozná CSV a otevře náhled tabulky.
5. Klikněte na Načíst (nebo nejprve na Transformovat data, pokud chcete nastavit typy sloupců — createdAt/calledAt/atd. se importují jako text; převeďte je na Date/Time v Power Query).
6. Pokud data stahujete pravidelně, nastavte v Power BI service naplánovanou obnovu; udržujte rozmezí pohodlně pod 90 dny na jednu obnovu.

Tip

Úložiště přihlašovacích údajů Power BI udržuje hlavičku Authorization mimo query string a mimo viditelný M kód uloženého souboru .pbix, takže toto je doporučený způsob autentizace z Power BI — token nikdy nevkládejte přímo do URL.