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 sağlar — admin girişi gerekmez, yalnızca bir Bearer belirteci yeterlidir. Verileri bir veri ambarına, bir BI 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, sıra numarasının taşıyıcı hash değerini veya müşteri tarafından girilen herhangi bir kişisel veriyi (ad, not, grup büyüklüğü) hiçbir zaman içermez — yalnızca kimlikler, durum ve yaşam döngüsü zaman damgaları bulunur.

Sayfalama: nextCursor null değilse, kaldığınız yerden devam etmek için bir sonraki istekte cursor olarak geçirin (aynı from/to/filtreler). nextCursor değerinin null olması, aralığın sonuna ulaştığınız anlamına gelir.

GET /v1/exports/tickets.csv

/v1/tickets ile aynı filtreler (from/to zorunlu, queueId/locationId/status tekrarlanabilir) ancak cursor/limit hariç — eşleşen tüm aralık tek bir CSV yanıtı olarak akar, bu yüzden toplu bir çekim için aşılması gereken 500 satırlık bir sayfa sınırı yoktur.

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 akış halinde gelir (Transfer-Encoding: chunked), bu yüzden 90 günlük/100 bin satırlık bir dışa aktarımın her iki uçta da bellekte arabelleğe alınması gerekmez — doğrudan bir dosyaya veya ayrıştırıcıya yönlendirin.

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

from/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 veriyi aşamalı olarak çekin (ör. haftada bir çağrı) — sıra numarası yaşam döngüsü zaman damgaları (calledAt, completedAt, …), aynı satırları iki kez çekmeden bekleme/hizmet sürelerini yeniden oluşturmanızı sağlar.

Hız sınırları

Belirteç başına dakikada 60 istek (IP başına değil — kota belirteçle birlikte taşını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.

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.