Salt Okunur Analitik API'si

api.jonot.io/v1/* HTTP API’si, kuruluşunuzun sıra numarası ve sıra verilerine salt okunur erişim verir. Admin girişi yerine bir Bearer belirteciyle kimlik doğrulayın. API’yi verileri bir veri ambarına, bir iş zekâsı aracına veya özel bir gösterge paneline aktarmak için kullanın.

Dikkat

API, Pro planı ve üzerinde kullanılabilir. Entegrasyonlar sayfasındaki API belirteçleri sekmesi, Başlangıç planında bir yükseltme istemi gösterir.

Belirteç alma

1. admin.jonot.io/settings/integrations adresini açın.
2. API belirteçleri sekmesine tıklayın.
3. Belirteç oluştur’a tıklayın, bir ad verin (ör. “Power BI”) ve onaylayın.
4. Belirteci hemen kopyalayın — yalnızca bir kez gösterilir ve tekrar alınamaz. Kaybederseniz iptal edip yenisini oluşturun.

Belirteçler jot_ önekini taşır ve kendiliğinden süresi dolmaz; artık gerek kalmadığında aynı sekmeden iptal edin.

Kimlik doğrulama

Tehlike

Belirteci yalnızca Authorization başlığında gönderin. Asla bir sorgu dizesine (query string) koymayın — sorgu dizeleri erişim günlüklerinde, proxy günlüklerinde ve tarayıcı geçmişinde kalır. ?token=... üzerinden gönderilen bir belirteç 401 ile reddedilir.

Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Durum	Anlamı
401	Belirteç eksik, hatalı biçimlendirilmiş, bilinmiyor veya iptal edilmiş.
402	Belirteç geçerli, ancak kuruluşta API özelliği etkin değil.
429	Hız sınırı aşıldı — aşağıdaki Hız sınırları bölümüne bakın.
400	Geçersiz sorgu parametreleri veya 90 günü aşan bir tarih aralığı.

Uç noktalar

GET /v1/queues

Kuruluşunuzun konumlarını ve sıralarını, filtrelenmemiş ve sayfalanmamış şekilde döndürür:

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

/v1/tickets ve CSV dışa aktarımını queueId / locationId ile filtrelemek için döndürülen id değerlerini kullanın.

GET /v1/tickets

Kuruluşunuzla sınırlı, sayfalanmış sıra numarası okuma.

Parametre	Zorunlu	Tekrarlanabilir	Notlar
from	evet	hayır	ISO-8601, createdAt üzerinde dahil edilen alt sınır.
to	evet	hayır	ISO-8601, hariç tutulan üst sınır. En fazla 90 günlük aralık.
queueId	hayır	evet	Birden fazla sırayı filtrelemek için parametreyi tekrarlayın.
locationId	hayır	evet	Birden fazla konumu filtrelemek için parametreyi tekrarlayın.
status	hayır	evet	WAITING, CALLED, COMPLETED, CANCELED, SKIPPED, NO_SHOW değerlerinden biri.
cursor	hayır	hayır	Önceki sayfanın nextCursor değerinden gelen opak bir değer.
limit	hayır	hayır	Varsayılan 100, en fazla 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…"
}

Satırlar hiçbir zaman sıra numarasına erişim sağlayan hash değerini veya müşterinin girdiği kişisel verileri (ad, not, grup büyüklüğü) içermez. Yalnızca kimlikler, durum ve yaşam döngüsü zaman damgaları yer alır.

Sayfalama: nextCursor değeri null değilse, bir sonraki istekte cursor olarak geçirin. from, to ve filtre değerlerini aynı tutun. nextCursor değerinin null olması, aralığın sonuna ulaştığınız anlamına gelir.

GET /v1/exports/tickets.csv

Bu uç nokta /v1/tickets ile aynı filtreleri kabul eder: from ve to zorunludur; queueId, locationId ve status tekrarlanabilir. cursor ve limit kabul edilmez. Eşleşen aralığın tamamı tek bir CSV yanıtı olarak akar, bu yüzden 500 satırlık sayfa sınırı geçerli değildir.

Sütun sırası sabittir, ancak sütunları sabit konuma göre değil başlık adına göre ayrıştırın. Başlık satırı her zaman mevcuttur ve tam olarak bu listeyle eşleşir:

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

Yanıt Transfer-Encoding: chunked kullanır. 100 bin satırlık 90 günlük bir dışa aktarımın iki uçta da bellekte tutulması gerekmez. Doğrudan bir dosyaya veya ayrıştırıcıya gönderin.

90 günlük aralık sınırı

from ve to alan her uç nokta, 90 günü aşan bir aralığı 400 ile reddeder. Daha uzun bir geçmişe ihtiyacınız varsa daha kısa aralıklar isteyin, örneğin haftada bir istek. Bekleme ve hizmet sürelerini aynı satırları iki kez istemeden hesaplamak için calledAt ve completedAt gibi yaşam döngüsü zaman damgalarını kullanın.

Hız sınırları

Her belirteç dakikada 60 isteğe izin verir. Sınır IP adresine değil, belirtece uygulanır. Her yanıt şunları içerir:

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

Bir 429 yanıtı ayrıca Retry-After (saniye) değerini de içerir. Bu süre dolana kadar bekleyip tekrar deneyin; birkaç dakikada bir zamanlanmış bir senkronizasyon rahatlıkla sınırın altında kalır.

Demo kuruluşları

Bir demo kuruluşunun günde 50 istek şeklinde ek bir sınırı vardır. Dakika başına sınır da geçerlidir. Demo API’siyle bir entegrasyonu baştan sona sınayabilirsiniz: sıralarınızı listeleyin, sıra numaralarını isteyin ve bir CSV dışa aktarımı oluşturun. Günlük sınır üretimde kullanım için yeterli değildir. Bu sınırı aşarsanız API, nedenini belirten bir gövdeyle 429 döndürür:

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

Demo CSV dışa aktarımları da işaretlenir, böylece dışa aktarılan bir dosya üretim verisiyle karıştırılamaz: dosya adının başına demo- öneki eklenir, yanıt X-Jonot-Demo: 1 başlığını taşır ve CSV’nin sonuna ek bir demo sütunu eklenir. Ücretli dışa aktarımlar değişmez — ek sütun yok, ek başlık yok. Ücretli bir plana abone olmak günlük kotayı kaldırır ve işaretlemeleri siler.

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

Ya da CSV dışa aktarımını doğrudan okuyun — pandas, akış halindeki yanıtı şeffaf bir şekilde işler:

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 bağlayıcı)

1. Power BI Desktop’ta: Get Data → Web.
2. Advanced’i seçin ve URL’yi tarih aralığınızla oluşturun, ör. https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z.
3. HTTP request header parameters altında, Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx değerine sahip Authorization adlı bir başlık ekleyin.
4. OK’e tıklayın — Power BI, CSV’yi algılar ve Table Preview’ı açar.
5. Load’a tıklayın (sütun türlerini ayarlamak isterseniz önce Transform Data’ya tıklayın — createdAt/calledAt gibi alanlar metin olarak içe aktarılır; bunları Power Query’de Date/Time’a dönüştürün).
6. Belirli bir düzenle veri çekiyorsanız Power BI hizmetinde zamanlanmış bir yenileme ayarlayın; her yenilemede aralığı rahatlıkla 90 günün altında tutun.

İpucu

Power BI’nin kimlik bilgisi deposu, Authorization başlığını sorgu dizesinin ve kaydedilen .pbix dosyasının görünür M kodunun dışında tutar, bu yüzden Power BI’dan kimlik doğrulamanın önerilen yolu budur — belirteci asla URL’nin içine gömmeyin.