読み取り専用分析API

api.jonot.io/v1/*のHTTP APIは、組織のチケットとキューのデータへの読み取り専用アクセスを提供します — Adminへのログインは不要で、ベアラートークンのみで利用できます。データウェアハウス、BIツール、カスタムダッシュボードへのデータ取り込みにご利用ください。

トークンの取得

admin.jonot.io/settings/integrationsを開きます。
API tokensタブをクリックします。
Create tokenをクリックし、名前（例：「Power BI」）を付けて確定します。
トークンはすぐにコピーしてください — 表示は一度限りで、後から復元することはできません。 紛失した場合は、そのトークンを無効化して新しく作成してください。

トークンにはjot_という接頭辞が付き、自動的に期限切れになることはありません。不要になったら同じタブから無効化してください。

認証

Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

ステータス	意味
`401`	トークンが未指定、不正な形式、不明、または無効化済みの場合。
`402`	トークンは有効だが、組織でAPI機能が有効になっていない場合。
`429`	レート制限を超過した場合 — 詳細は下記のレート制限を参照。
`400`	クエリパラメータが不正、または日付範囲が90日を超える場合。

エンドポイント

`GET /v1/queues`

組織の拠点とキューを、フィルタなし・ページングなしで返します。

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

返されたidの値を使って、/v1/ticketsとCSVエクスポートをqueueId／locationIdでフィルタできます。

`GET /v1/tickets`

組織にスコープされた、ページング対応のチケット読み取りエンドポイントです。

パラメータ	必須	繰り返し可	補足
`from`	必須	不可	ISO-8601形式、`createdAt`の下限（この値を含む）。
`to`	必須	不可	ISO-8601形式、上限（この値を含まない）。最大90日間の範囲。
`queueId`	任意	可	パラメータを繰り返して複数のキューでフィルタできます。
`locationId`	任意	可	パラメータを繰り返して複数の拠点でフィルタできます。
`status`	任意	可	`WAITING`、`CALLED`、`COMPLETED`、`CANCELED`、`SKIPPED`、`NO_SHOW`のいずれか。
`cursor`	任意	不可	前のページの`nextCursor`から得られる不透明な値。
`limit`	任意	不可	デフォルト100、最大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…"
}

各行にはチケットのベアラーハッシュや、お客様が入力したPII（名前、メモ、人数）は一切含まれません — id、ステータス、ライフサイクルのタイムスタンプのみです。

ページング：nextCursorがnullでない場合、次のリクエストでcursorとして渡すことで、前回の続きから取得できます（from/to/フィルタは同じ値を使用）。nextCursorがnullの場合は、範囲の終端に達したことを意味します。

`GET /v1/exports/tickets.csv`

/v1/ticketsと同じフィルタ（from/toは必須、queueId/locationId/statusは繰り返し可）からcursor/limitを除いたもので、一致する範囲全体が1つのCSVレスポンスとしてストリーミングされるため、大量データを一括で取得する際に500行のページ上限を回避する必要はありません。

列の順序は固定ですが、固定位置ではなくヘッダー名でパースしてください。ヘッダー行は常に存在し、次のリストと完全に一致します。

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

レスポンスはストリーミングされる（Transfer-Encoding: chunked）ため、90日／10万行のエクスポートでも送信側・受信側どちらもメモリにバッファする必要はありません — そのままファイルやパーサーにパイプできます。

90日間の範囲制限

from/toを受け取るすべてのエンドポイントは、90日を超える範囲を400で拒否します。より長い履歴が必要な場合は、段階的にデータを取得してください（例：週1回のリクエスト）— チケットのライフサイクルタイムスタンプ（calledAt、completedAtなど）を使えば、同じ行を再取得しなくても待ち時間・対応時間を再構築できます。

レート制限

トークンごとに毎分60リクエスト（IPごとではなく、上限はトークンに紐づきます）。すべてのレスポンスには次が含まれます。

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

429にはさらにRetry-After（秒数）が含まれます。その時間だけ待ってから再試行してください。数分おきのスケジュール同期であれば、余裕を持って制限内に収まります。

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

または、CSVエクスポートを直接読み込むこともできます — pandasはストリーミングレスポンスを透過的に処理します。

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コネクタ）

Power BI Desktopで：Get Data → Webを選択します。
Advancedを選び、日付範囲を含めたURLを組み立てます。例：https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z。
HTTP request header parametersの下で、名前をAuthorization、値をBearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxとしたヘッダーを追加します。
OKをクリックすると、Power BIがCSVを検出しTable Previewを開きます。
Loadをクリックします（列の型を設定したい場合は先にTransform Dataを使用してください — createdAt/calledAtなどはテキストとして取り込まれるため、Power QueryでDate/Time型に変換します）。
定期的に取得する場合は、Power BIサービスでスケジュール更新を設定してください。1回の更新あたりの範囲は90日を十分に下回るようにします。