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 za shirika lako. Tumia tokeni ya Bearer badala ya kuingia kwenye akaunti ya usimamizi. Wewe ndiye unayeomba data unapoihitaji: Jonot haiisukumi yenyewe. Tumia API hii kuvuta data katika ghala la data, zana ya akili-biashara, au dashibodi yako mwenyewe.

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 Unda tokeni, ipe jina (mfano, “Power BI”), kisha thibitisha.
4. Nakili tokeni papo hapo. Inaonyeshwa mara moja tu na haiwezi kupatikana tena. 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 wala taarifa binafsi zilizoingizwa na mteja (PII), kama vile jina, dokezo, au idadi ya watu. Zinajumuisha vitambulisho, hali, na muhuri za muda za mzunguko wa maisha pekee.

Kurasa: nextCursor isipokuwa null, ituma kama cursor katika ombi linalofuata. Tumia thamani zilezile za from, to, na vichujio. nextCursor yenye thamani null inamaanisha umefikia mwisho wa kipindi.

GET /v1/exports/tickets.csv

Sehemu hii ya mwisho inakubali vichujio vilevile kama /v1/tickets: from na to ni lazima, na queueId, locationId, na status vinaweza kurudufiwa. Haikubali cursor wala limit. Kipindi kizima kinacholingana kinatiririka kama jibu moja la CSV, hivyo kikomo cha safu 500 kwa ukurasa hakitumiki.

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 linatumia Transfer-Encoding: chunked. Uhamishaji wa siku 90 wenye safu 100,000 hauhitaji kubaki kwenye kumbukumbu upande wowote. Lipeleke moja kwa moja kwenye faili au kichambuzi.

Kikomo cha kipindi cha siku 90

Kila sehemu ya mwisho inayochukua from na to inakataa kipindi kinachozidi siku 90 kwa 400. Ikiwa unahitaji historia ndefu zaidi, omba vipindi vifupi zaidi, kwa mfano ombi moja kwa kila wiki. Tumia muhuri za muda za mzunguko wa maisha kama calledAt na completedAt kupiga hesabu ya muda wa kusubiri na wa huduma bila kuomba safu zilezile mara mbili.

Vikomo vya Kiwango

Kila tokeni inaruhusiwa maombi 60 kwa dakika. Kikomo hiki ni cha tokeni, si cha anwani ya IP. Kila jibu linajumuisha:

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.

Mashirika ya demo

Shirika la demo lina kikomo cha ziada cha maombi 50 kwa siku. Kikomo cha kila dakika nacho kinatumika. Unaweza kutumia API ya demo kujaribu muunganisho kamili kwa kuorodhesha foleni, kuomba tiketi, na kutengeneza uhamishaji wa CSV. Kikomo cha kila siku hakitoshi kwa matumizi ya uzalishaji. Ukikizidi, API inarudisha 429 yenye jibu linaloonyesha sababu:

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

Uhamishaji wa CSV wa demo pia unawekwa alama, ili faili iliyohamishwa isichanganywe na data ya uzalishaji: jina la faili linapata kiambishi awali demo-, jibu linabeba X-Jonot-Demo: 1, na safu wima ya ziada ya demo inaongezwa mwishoni mwa CSV. Uhamishaji wa shirika linalolipia haubadiliki — hakuna safu ya ziada wala kichwa cha ziada. Kujiunga na mpango unaolipiwa huondoa kikomo cha kila siku na alama hizo.

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.