Vain luku -analytiikka-API

api.jonot.io/v1/* HTTP-API tarjoaa vain luku -pääsyn organisaatiosi vuoro- ja jonotietoihin. Admin-kirjautumisen sijaan käytät bearer-tokenia. Hae API:sta tietoja tietovarastoon, BI-työkaluun tai omaan hallintapaneeliin.

Varoitus

API on käytettävissä Pro-paketista ylöspäin. Integraatiot-sivun API-tokenit-välilehti näyttää päivityskehotteen Starter-paketilla.

Tokenin hankkiminen

1. Avaa admin.jonot.io/settings/integrations.
2. Napsauta API-tokenit-välilehteä.
3. Napsauta Luo token, anna sille nimi (esim. “Power BI”) ja vahvista.
4. Kopioi token heti — se näytetään vain kerran, eikä sitä voi palauttaa. Jos hukkaat sen, poista se käytöstä ja luo uusi.

Tokenin alussa on jot_, eikä se vanhene automaattisesti. Poista token käytöstä samalta välilehdeltä, kun et enää tarvitse sitä.

Todennus

Vaara

Lähetä token vain Authorization-otsakkeessa. Älä koskaan laita sitä kyselymerkkijonoon — kyselymerkkijonot päätyvät pääsylokeihin, proxy-lokeihin ja selaimen historiaan. Osoitteessa ?token=... toimitettu token hylätään koodilla 401.

Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tila	Merkitys
401	Token puuttuu, on virheellinen, tuntematon tai poistettu käytöstä.
402	Kelvollinen token, mutta organisaatiolla ei ole API-ominaisuutta käytössä.
429	Pyyntörajoitus ylitetty — katso alta Pyyntörajoitukset.
400	Virheelliset kyselyparametrit tai yli 90 päivän aikaväli.

Päätepisteet

GET /v1/queues

Palauttaa organisaatiosi kaikki toimipisteet ja jonot ilman suodatusta tai sivutusta:

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

Käytä palautettuja id-arvoja /v1/tickets-pyynnön ja CSV-viennin suodattamiseen kentillä queueId / locationId.

GET /v1/tickets

Sivutettu vuoronumeroiden haku, rajattu organisaatioosi.

Parametri	Pakollinen	Toistettava	Huomiot
from	kyllä	ei	ISO-8601, createdAt-kentän alaraja mukaan lukien.
to	kyllä	ei	ISO-8601, yläraja pois lukien. Enintään 90 päivän aikaväli.
queueId	ei	kyllä	Toista parametri suodattaaksesi useita jonoja.
locationId	ei	kyllä	Toista parametri suodattaaksesi useita toimipisteitä.
status	ei	kyllä	Yksi arvoista WAITING, CALLED, COMPLETED, CANCELED, SKIPPED, NO_SHOW.
cursor	ei	ei	Läpinäkymätön arvo edellisen sivun nextCursor-kentästä.
limit	ei	ei	Oletus 100, enintään 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…"
}

Rivit sisältävät vain tunnisteet, tilan ja elinkaaren aikaleimat. Ne eivät sisällä vuoronumeron bearer-hashia tai asiakkaan antamia henkilötietoja, kuten nimeä, muistiinpanoja tai seurueen kokoa.

Sivutus: jos nextCursor ei ole null, anna se seuraavan pyynnön cursor-parametrina ja käytä samoja from-, to- ja suodatinarvoja. nextCursor-arvo null tarkoittaa, että aikavälin kaikki tulokset on haettu.

GET /v1/exports/tickets.csv

Käyttää samoja suodattimia kuin /v1/tickets: from ja to ovat pakollisia, ja queueId, locationId sekä status voi toistaa. cursor- ja limit-parametreja ei käytetä. API lähettää koko vastaavan aikavälin yhtenä CSV-virtana, joten suurta hakua ei tarvitse jakaa 500 rivin sivuihin.

Sarakejärjestys on pysyvä, mutta jäsennä sarakkeet otsikkonimen mukaan kiinteän sijainnin sijaan. Otsikkorivi on aina mukana ja vastaa tarkalleen tätä listaa:

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

Vastaus lähetetään virtana (Transfer-Encoding: chunked). Siksi 90 päivän vienti, jossa on 100 000 riviä, ei vaadi koko aineiston tallentamista muistiin palvelimella tai asiakkaalla. Ohjaa vastaus suoraan tiedostoon tai jäsentimeen.

90 päivän aikavälin yläraja

Jokainen from- ja to-parametreja käyttävä päätepiste hylkää yli 90 päivän aikavälin koodilla 400. Jos tarvitset pidemmän historian, hae tiedot osissa, esimerkiksi viikko kerrallaan. Vuoronumeron elinkaaren aikaleimoista, kuten calledAt ja completedAt, voit laskea odotus- ja palveluajat hakematta samoja rivejä uudelleen.

Pyyntörajoitukset

Raja on 60 pyyntöä minuutissa tokenia kohden. Raja ei ole IP-osoitekohtainen, joten se koskee tokenia kaikista osoitteista käytettäessä. Jokainen vastaus sisältää:

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

429-vastaus sisältää myös sekunteina annetun Retry-After-otsakkeen. Odota ilmoitettu aika ennen uutta yritystä. Muutaman minuutin välein ajettava synkronointi pysyy rajan alla.

Demo-organisaatiot

Demo-organisaatio käyttää samaa API:a, mutta minuuttikohtaisen rajan lisäksi sillä on 50 pyynnön päiväkohtainen kiintiö. Määrä riittää integraation testaamiseen: jonojen luettelointiin, muutaman vuoronumeron hakemiseen ja yhteen CSV-vientiin. Se ei riitä tuotantokäyttöön. Kiintiön ylitys palauttaa 429-vastauksen, jonka runko kertoo syyn:

{
  "error": "demo_quota_exceeded",
  "limit": 50,
  "resetAt": "2026-01-02T09:00:00.000Z"
}

Demo-CSV-viennit merkitään, jotta niitä ei sekoiteta tuotantodataan. Tiedostonimen alussa on demo-, vastaus sisältää otsakkeen X-Jonot-Demo: 1 ja CSV:n loppuun lisätään demo-sarake. Maksullisissa vienneissä ei ole ylimääräistä saraketta tai otsaketta. Maksulliseen pakettiin siirtyminen poistaa päiväkohtaisen kiintiön ja merkinnät.

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())

Voit myös lukea CSV-viennin suoraan. Pandas käsittelee virtana lähetetyn vastauksen automaattisesti:

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 (Web-liitin)

1. Power BI Desktopissa: Get Data → Web.
2. Valitse Advanced ja rakenna osoite haluamallasi aikavälillä, esim. https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z.
3. Kohdassa HTTP request header parameters lisää otsake nimeltä Authorization arvolla Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
4. Napsauta OK — Power BI tunnistaa CSV:n ja avaa taulukon esikatselun.
5. Napsauta Load (tai ensin Transform Data, jos haluat asettaa sarakkeiden tyypit — createdAt/calledAt/jne. tuodaan tekstinä; muunna ne tyyppiin Date/Time Power Queryssä).
6. Aseta ajastettu päivitys Power BI -palvelussa, jos haet tietoja säännöllisesti; pidä aikaväli mukavasti alle 90 päivän per päivitys.

Vinkki

Power BI:n tunnistetietovarasto pitää Authorization-otsakkeen erillään kyselymerkkijonosta ja tallennetun .pbix-tiedoston näkyvästä M-koodista, joten käytä tätä tapaa Power BI:n tunnistautumiseen. Älä koskaan upota tokenia osoitteeseen itseensä.