API ya Takwimu ya Kusoma Tu

API ya HTTP ya api.jonot.io/v1/* inatoa ufikiaji wa kusoma tu wa data ya tiketi na foleni ya shirika lako — hakuna kuingia kwa usimamizi kunahitajika, tokeni-mbeba tu. Itumie kuvuta data katika ghala la data, zana ya BI, au dashibodi maalum.

Caution

API inapatikana kwenye mpango wa Pro na juu zaidi. Kichupo cha tokeni za API katika ukurasa wa Uunganisho kinaonyesha ombi la kuboresha mpango kwenye Mwanzo.

Kupata tokeni

1. Fungua admin.jonot.io/settings/integrations.
2. Bofya kichupo cha API tokens.
3. Bofya Create token, ipe jina (mfano, “Power BI”), kisha thibitisha.
4. Nakili tokeni mara moja — inaonyeshwa mara moja tu na haiwezi kurejeshwa. Ukiipoteza, ibatilishe kisha uunde nyingine.

Tokeni zina kiambishi cha jot_ na hazina muda wa kuisha zenyewe; zibatilishe kutoka kichupo kilekile zisipohitajika tena.

Uthibitishaji

Danger

Tuma tokeni pekee katika kichwa cha Authorization. Kamwe usiiweke katika mfuatano wa hoja (query string) — mifuatano ya hoja huishia kwenye kumbukumbu za ufikiaji, kumbukumbu za wakala, na historia ya kivinjari. Tokeni iliyotolewa kupitia ?token=... inakataliwa kwa 401.

Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Hali	Maana
401	Tokeni haipo, ina umbo batili, haijulikani, au imebatilishwa.
402	Tokeni ni sahihi, lakini shirika halina kipengele cha API kimewashwa.
429	Kiwango cha ukomo kimezidiwa — angalia Vikomo vya Kiwango hapo chini.
400	Vigezo vya hoja si sahihi, au kipindi cha tarehe kinazidi siku 90.

Sehemu za Mwisho

GET /v1/queues

Inarudisha maeneo na foleni za shirika lako, bila kuchujwa na bila kurasa:

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

Tumia thamani za id zilizorudishwa kuchuja /v1/tickets na uhamishaji wa CSV kwa queueId / locationId.

GET /v1/tickets

Usomaji wa tiketi wenye kurasa, umewekwa mipaka kwa shirika lako.

Kigezo	Lazima	Rudufu	Maelezo
from	ndiyo	hapana	ISO-8601, mpaka wa chini unaojumuisha kwenye createdAt.
to	ndiyo	hapana	ISO-8601, mpaka wa juu usiojumuisha. Kiwango cha juu ni siku 90.
queueId	hapana	ndiyo	Rudia kigezo hiki kuchuja foleni nyingi.
locationId	hapana	ndiyo	Rudia kigezo hiki kuchuja maeneo mengi.
status	hapana	ndiyo	Moja ya WAITING, CALLED, COMPLETED, CANCELED, SKIPPED, NO_SHOW.
cursor	hapana	hapana	Thamani isiyofahamika kutoka nextCursor ya ukurasa uliopita.
limit	hapana	hapana	Kawaida 100, kiwango cha juu 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…"
}

Safu hazijumuishi kamwe hashi ya kubeba ya tiketi au taarifa yoyote binafsi iliyoingizwa na mteja (jina, dokezo, idadi ya watu) — ni vitambulisho, hali, na muhuri za muda za mzunguko wa maisha pekee.

Kurasa: wakati nextCursor sio null, itume kama cursor katika ombi lifuatalo ili kuendelea kutoka mahali ulipoishia (from/to/vichujio vilevile). nextCursor yenye thamani null inamaanisha umefikia mwisho wa kipindi hicho.

GET /v1/exports/tickets.csv

Vichujio vilevile kama /v1/tickets (from/to lazima, queueId/locationId/status vinaweza kurudufiwa) ukiondoa cursor/limit — kipindi kizima kinachofanana kinatiririka kama jibu moja la CSV, hivyo hakuna kikomo cha safu 500 kwa ukurasa cha kupitisha kwa uvutaji mkubwa wa data.

Mpangilio wa safu ni thabiti, lakini chambua safu kwa jina la kichwa badala ya nafasi maalum. Safu ya kichwa ipo daima na inalingana na orodha hii kikamilifu:

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

Jibu linatiririka (Transfer-Encoding: chunked) hivyo uhamishaji wa siku 90/safu 100,000 hauhitaji kuhifadhiwa kwenye kumbukumbu ya muda upande wowote — kilekeze moja kwa moja kwenye faili au kichambuzi.

Kikomo cha kipindi cha siku 90

Kila sehemu ya mwisho inayochukua from/to inakataa kipindi kinachozidi siku 90 kwa 400. Vuta data kidogo kidogo (mfano, ombi moja kwa wiki) ikiwa unahitaji historia ndefu zaidi — muhuri za muda za mzunguko wa maisha wa tiketi (calledAt, completedAt, …) zinakuruhusu kujenga upya muda wa kusubiri/huduma bila kuchukua safu zilezile mara mbili.

Vikomo vya Kiwango

Maombi 60 kwa dakika kwa kila tokeni (si kwa kila IP — bajeti hiyo inasafiri pamoja na tokeni). Kila jibu linabeba:

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

429 pia inabeba Retry-After (sekunde). Pumzika kisha ujaribu tena baada ya muda huo; usawazishaji uliopangwa kila dakika chache unabaki chini ya kikomo kwa urahisi.

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

Au soma uhamishaji wa CSV moja kwa moja — pandas inashughulikia jibu la mtiririko kwa uwazi:

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 (Kiunganishi cha Wavuti)

1. Katika Power BI Desktop: Get Data → Web.
2. Chagua Advanced, kisha jenga URL kwa kipindi chako cha tarehe, mfano https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z.
3. Chini ya HTTP request header parameters, ongeza kichwa kiitwacho Authorization chenye thamani Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
4. Bofya OK — Power BI inatambua CSV na kufungua Table Preview.
5. Bofya Load (au Transform Data kwanza ikiwa unataka kuweka aina za safu — createdAt/calledAt/n.k. zinaingizwa kama maandishi; zibadilishe kuwa Date/Time katika Power Query).
6. Weka usasishaji uliopangwa katika huduma ya Power BI ikiwa unavuta data kwa mzunguko; weka kipindi chini ya siku 90 kwa urahisi kwa kila usasishaji.

Tip

Hifadhi ya vitambulisho ya Power BI inaweka kichwa cha Authorization nje ya mfuatano wa hoja na nje ya msimbo wa M unaoonekana wa faili ya .pbix iliyohifadhiwa, hivyo hii ndiyo njia inayopendekezwa ya kuthibitisha kutoka Power BI — kamwe usiweke tokeni ndani ya URL yenyewe.