Partner API — クイックスタート

はじめての連携は、1画面でわかります。

今すぐ試す — キーも登録もいりません

このアドレスをブラウザで開いてください。すぐにサンプルイベントが見られます。

https://timtim.live/api/partner-network/demo?city=Washington

1
テストキーをもらう
ログインして、あなたのことを教えてから「テストキーを作る」を押してください。キーは tt_test_ で始まり、サンプルイベントだけが見られます。

イベントを探す

都市を指定してイベントをたずねます。

curl "https://api.timtim.live/v1/events?city=Washington&category=music" \
  -H "Authorization: Bearer tt_test_YOUR_KEY"

3
イベントを表示する
どのイベントにも、名前、日付、場所、画像、価格と、カードにそのまま使えるラベルがあります。
4
buy_url を使う
私たちが渡す buy_url を使ってください。それだけです。だれ経由の売上かは、TimTim.Live がそのリンクの中で記録します。
5
結果を見る
送った人数、売れたチケット、収益をダッシュボードで見られます。API でたずねることもできます。
GET https://api.timtim.live/v1/earnings

テストキーをもらうキーなしで試す

TimTim.Live ステータス

リファレンス

リクエストの送り先

https://api.timtim.live/v1

あなたの接続キー

キーは Authorization ヘッダーで送ります。テストキー（tt_test_）はサンプルイベントだけ見られます。ウェブサイトキー（tt_pk_live_）はウェブページに置けて、イベントを読むだけです。サーバーキー（tt_sk_live_）はあなたのサーバーに置き、収益も読めます。キーは一度しか表示しません。大切に保管してください。

curl

curl "https://api.timtim.live/v1/events?city=Washington&category=music" \
  -H "Authorization: Bearer tt_test_YOUR_KEY"

JavaScript

const res = await fetch("https://api.timtim.live/v1/events?city=Washington&category=music", {
  headers: { Authorization: "Bearer tt_test_YOUR_KEY" },
});
const { events, next } = await res.json();
for (const event of events) {
  console.log(event.name, event.display.date_label, event.tickets.buy_url);
}

Node

// Node 18+ — keep server keys (tt_sk_live_) on the server
const res = await fetch("https://api.timtim.live/v1/events?city=Washington", {
  headers: { Authorization: `Bearer ${process.env.TIMTIM_KEY}` },
});
if (!res.ok) {
  const problem = await res.json();
  throw new Error(`${problem.title} (${problem.request_id})`);
}
const { events } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.timtim.live/v1/events",
    params={"city": "Washington", "category": "music"},
    headers={"Authorization": f"Bearer {os.environ['TIMTIM_KEY']}"},
)
res.raise_for_status()
for event in res.json()["events"]:
    print(event["name"], event["tickets"]["buy_url"])

PHP

<?php
$ch = curl_init("https://api.timtim.live/v1/events?city=Washington&category=music");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer " . getenv("TIMTIM_KEY")]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
foreach ($data["events"] as $event) {
  echo $event["name"] . " " . $event["tickets"]["buy_url"] . PHP_EOL;
}

絞り込み

city: この都市のイベント。
country: 2文字の国コード。たとえば US。
category: たとえば音楽、フェス、カンファレンス。
from: この日かそれ以降のイベント（2026-10-20）。
to: この日かそれ以前のイベント。
changed_since: この時間のあとに変わったイベントだけ。
commissioned: true = 報酬があるイベントだけ。
minimum_earnings: チケット1枚あたり、この金額以上の報酬があるイベントだけ。
near: 場所。たとえば near=Paris,FR。
limit: 1ページあたりのイベント数。1から100（書かなければ20）。

変わったものだけ知りたい

前回同期した時間を保存して、changed_since として送ってください。変わったイベントだけが届きます。中止や売り切れも含みます。webhook はいりません。表示をやめるべきイベントは withdrawn リストで届きます。

GET https://api.timtim.live/v1/events?changed_since=2026-10-06T10:00:00Z

ページが2つ以上あるとき

答えに next があれば、それを cursor= として送ると次のページがもらえます。next が空なら、全部そろっています。

GET https://api.timtim.live/v1/events?city=Paris&cursor=eyJtIjoiZCIs…

収益

どのイベントにも earn があります。earn.eligible が false なら、そのイベントに報酬はありません。それでも紹介する価値はあります。true なら、earn.description にもらえるものが書いてあります。たとえば「対象チケット1枚につき $5」です。購入が返金されると、報酬は取り消されます。

一括フィード(すべてを1つのファイルに)

ダッシュボードで一括フィードを保存し、対象のイベントをすべて1つの圧縮ファイルでダウンロードします: GET /v1/bulk/FEED_ID.ndjson.gz または .csv.gz、サーバーキーを使います。?changed_since= を付けると、取り下げられたイベントも含めて変わった分だけ受け取れます。テストキーなら今すぐ試せます。本番での利用には TimTim.Live の審査が必要です。

GET https://api.timtim.live/v1/bulk/bfs_YOURFEED.ndjson.gz?changed_since=2026-10-06T00:00:00Z

自分のアプリでチケットを売る（組み込み型の販売）

大きなパートナーは、購入者を自分のアプリの中にとどめておけます。GET /v1/events/EVENT_ID/tickets で販売中のものを確認し、購入者が選んだ内容で POST /v1/orders を送ります。購入者に開いてもらう TimTim.Live の支払いリンクが返ってきます。売上はあなたの会社に直接記録されます。テストキーなら今すぐ試せます。本番での利用には TimTim.Live の審査と、カード決済の有効化が必要です。

POST https://api.timtim.live/v1/orders  (Idempotency-Key: …)  {"event_id": "evt_test_washington_konpa", "ticket_type_id": "tt_test_washington_konpa", "quantity": 2, "buyer_email": "…", "buyer_name": "…"}

カード連動オファー（銀行・ポイントサービス）

GET /v1/offers は、報酬が出るイベントをオファーとして返します。主催者、購入できる日、価格、場所、報酬が入っています。お客さまはあなたの追跡リンクから有効にし、報酬は /v1/earnings を通じてあなたの会社に支払われます。テストキーではサンプルのオファーが見えます。本番のオファーには TimTim.Live の審査が必要です。カード決済を直接ひも付けるにはカードネットワークか銀行との契約が必要で、まだつながっていません。

GET https://api.timtim.live/v1/offers?country=US

イベントの状態とチケット

status は scheduled、postponed、rescheduled、cancelled、sold_out、completed のどれかです。tickets.availability は available、limited、sold_out、not_on_sale、ended のどれかです。イベントが中止になったら、表示から外してください。

GET https://api.timtim.live/v1/events/evt_test_washington_konpa

リクエストの速さの上限

テストキー：1分に60回。本番キー：1分に120回。それより速いと 429 が返り、Retry-After に待つ秒数が入ります。

届くイベント

TimTim.Live の主催者が作って、共有を選んだイベントです。ほかのチケットサイトから取り込んだイベントは入りません。共有する権利がないからです。

絶対に送らないもの

購入者の名前、メールアドレス、住所、電話番号、カード情報。Partner API が共有するのはイベントの情報で、会員の情報ではありません。

ウェブサイト用ウィジェット

HTML を1行入れるだけで、どのサイトにもイベントを表示できます。ウェブサイトキー（tt_pk_live_）を使い、キーの許可リストにあなたのサイトを追加してください。キーがないときは、サンプルイベントを表示します。

<script src="https://timtim.live/widget/events.js"
        data-key="tt_pk_live_YOUR_WEBSITE_KEY"
        data-city="Washington" data-category="music" async></script>

オプション：data-city、data-country、data-category、data-limit（1–24）、data-earn="true"、data-lang、data-color。

OAuth 2.0（大規模な連携）

任意です。ダッシュボードで OAuth クライアントを作り、そのクライアント ID とシークレットを1時間有効なアクセストークンと交換します。キーの代わりにそのトークンを送ってください。シークレットが API 呼び出しと一緒に送られることはありません。クライアントより少ないスコープを求めることもできます。

# 1. Trade the client ID and secret for a one-hour token
curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d "scope=events:read events:details" \
  https://api.timtim.live/v1/oauth/token
# → {"access_token":"tt_at_…","token_type":"Bearer","expires_in":3600,"scope":"events:read events:details"}

# 2. Use the token exactly like a key
curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://api.timtim.live/v1/events?city=Washington"

トークンを早めに終わらせるには、同じクライアント ID とシークレットを使って、/v1/oauth/revoke に POST してください。ダッシュボードでクライアントをオフにすると、そのトークンはすべて一度に終わります。

キーを自分のサーバーに固定する

任意です。ダッシュボードで、サーバーキー、テストキー、OAuth クライアントの下にある「自分のサーバーだけに固定」を開き、サーバーの公開アドレスを入れてください。それ以外の場所からの呼び出しとトークン要求は、正しいキーでも ip_not_allowed で断られます。

クライアント証明書（mTLS）：TLS クライアント証明書をキーにひもづけ、その証明書で https://api.timtim.live を呼び出します。すべての呼び出しでその証明書が必要です。TLS ハンドシェイクで、あなたが秘密鍵を持っていることが証明されます。

# Your certificate's SHA-256 — paste this (or the PEM) under "Lock to my servers"
openssl x509 -in client.crt -noout -fingerprint -sha256

# Every call then presents the certificate
curl --cert client.crt --key client.key \
  -H "Authorization: Bearer $KEY" "https://api.timtim.live/v1/events?city=Washington"

WordPress プラグイン

WordPress を使っていますか？ TimTim.Live Events を入れましょう。あなた自身の TimTim.Live チケットリンクつきでイベントを表示する、ブロックとショートコードです。TimTim.Live が作っていて、timtim.live とだけ通信し、timtim.live からだけ更新されます。

プラグイン → 新規追加 → プラグインのアップロードでファイルをアップロードします。設定 → TimTim.Live Events にウェブサイトキーを貼り付けて、Test Connection を押します。そのあと、どのページにも TimTim.Live Events ブロックを追加できます。

WordPress プラグインをダウンロード

[timtim_events city="Washington" category="music" limit="6"]

フィード

同じイベントを JSON Feed、RSS、XML、CSV でも取れます。Google Calendar、Apple Calendar、Outlook で購読できるカレンダー（.ics）もあります。フィードリーダーはヘッダーを送れないので、ウェブサイトキーかテストキーを ?key= に入れてください。サーバーキーは絶対にリンクに入れないでください。

https://timtim.live/v1/feeds/events.json?key=tt_pk_live_YOUR_KEY&city=Paris
https://timtim.live/v1/feeds/events.rss?key=tt_pk_live_YOUR_KEY&city=Paris
https://timtim.live/v1/feeds/events.xml?key=tt_pk_live_YOUR_KEY&city=Paris
https://timtim.live/v1/feeds/events.csv?key=tt_pk_live_YOUR_KEY&city=Paris
https://timtim.live/v1/feeds/events.ics?key=tt_pk_live_YOUR_KEY&city=Paris

Webhook

ダッシュボードで「アドレスを追加」を押すと、何かが変わったときにそのアドレスへお知らせを送ります：event.changed または earnings.changed。Webhook は必須ではありません。changed_since でも同じ情報が取れます。

{
  "id": "whd_8Fk2mQxR7tLp",
  "type": "event.changed",
  "created_at": "2026-10-06T15:04:05.000Z",
  "mode": "live",
  "data": {
    "event": {
      "id": "ev_…",
      "name": "…",
      "status": "cancelled",
      "tickets": {
        "availability": "ended",
        "buy_url": "https://timtim.live/b/…"
      },
      "…": "the same event object as GET /v1/events"
    }
  }
}

お知らせは毎回確認してください。あなたのシークレットで署名されています。5分より古いものは受け取らないでください。すでに処理した TimTim-Delivery-Id は無視してください。

// Node — Express with the RAW body (do not JSON.parse before checking)
import crypto from "node:crypto";

app.post("/timtim", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("TimTim-Signature") ?? "";           // t=1700000000,v1=<hex>
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const body = req.body.toString("utf8");
  const expected = crypto.createHmac("sha256", process.env.TIMTIM_WEBHOOK_SECRET)
    .update(`${parts.t}.${body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  const same = expected.length === (parts.v1 ?? "").length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  if (!fresh || !same) return res.sendStatus(400);

  const message = JSON.parse(body);                            // { id, type, mode, data }
  if (alreadyHandled(req.get("TimTim-Delivery-Id"))) return res.sendStatus(200);
  // message.type === "event.changed"    → message.data.event
  // message.type === "earnings.changed" → message.data.earning
  res.sendStatus(200);
});

10秒以内に 2xx のどれかで返事をしてください。返事がないときは、1分後、5分後、30分後、そのあと 2、6、12、24 時間後にもう一度送り、そこで止めます。リダイレクトには従いません。

サンドボックス

テストキーでは「テストイベント — 本当のお金は動きません」と書かれたサンプルイベントが届きます。buy_url を開いて「テストチケットを買う」を押し、収益をたずねてみてください。返金を試すと、取り消されるのが見られます。

うまくいかないとき

エラーは、タイトルと次にやることを、わかりやすい言葉で伝えます。どの答えにも TimTim-Request-Id がついています。それを送ってもらえれば、あなたのリクエストを探せます。

401missing_keyPlease add your TimTim.Live key. Send it as: Authorization: Bearer tt_test_… — get a test key at /partners/dashboard.
401invalid_keyWe do not recognise that key. Check you copied the whole key, or make a new one at /partners/dashboard.
401revoked_keyThat key was switched off. Make a new key at /partners/dashboard.
403partner_inactiveThis partner account cannot use live keys right now. Your test key still works. Contact TimTim.Live partnerships to review the account.
403missing_scopeThis key is not allowed to do that. Earnings need a secret key (tt_sk_live_…) or a test key, used from your server.
403domain_not_allowedThis website is not allowed to use this key. Add the website to the key's allowed domains at /partners/dashboard.
400unknown_parameterWe do not know one of those parameters. See /partners/docs for the list.
400invalid_countryWe could not read that country. Use a two-letter code, for example country=US or country=FR.
400invalid_dateWe could not read that date. Dates look like 2026-10-20.
400invalid_changed_sinceWe could not read changed_since. Use a full time, for example changed_since=2026-10-06T10:00:00Z.
400invalid_booleanThat value must be true or false. For example commissioned=true.
400invalid_numberThat value must be a number. For example minimum_earnings=5.
400invalid_nearWe could not find that place. Try near=Paris,FR or city=Paris&country=FR.
400invalid_locationWe could not read that location. Send lat, lng and optionally radius in kilometres.
400invalid_limitlimit must be between 1 and 100. Leave it out to get 20.
400invalid_cursorThat cursor is not one we gave you. Use the `next` value from the previous page exactly as it came.
404event_not_foundWe could not find that event. It may have been removed, or it is not shared with partners.
403capability_requiredCard-linked offers are not switched on for your account. Offers are an enterprise feature. Your test key shows sample offers now; ask TimTim.Live partnerships to review your account for live offers.
403server_key_requiredThis is for your server only. Use a secret key (tt_sk_live_…) or a test key from your server, never a website key in a web page.
403commerce_not_enabledSelling tickets in your own app is not switched on for your account. This is an enterprise feature (EMBEDDED_CHECKOUT). Your test key can try it now; ask TimTim.Live partnerships to review your account. Until then, use each event's buy_url.
503checkout_not_openCard payments are not open on TimTim.Live yet. Send the buyer to the event's buy_url instead. Your test key can still rehearse orders.
409ticket_not_availableThat ticket cannot be bought right now. It may be sold out, not on sale yet, or no longer on sale. Ask /v1/events/{id}/tickets for what is on sale now.
400order_invalidWe could not read that order. See /partners/docs for the fields an order needs.
400idempotency_key_requiredPlease send an Idempotency-Key header. 8 to 80 letters, digits, - or _. Send the same key again to retry safely — you will get the same order, never a second one.
404order_not_foundWe could not find that order. Only orders your company began with this kind of key (test or live) can be read here.
403bulk_not_enabledBulk feeds are not switched on for your account. This is an enterprise feature (BULK_FEEDS). Your test key can try it now; ask TimTim.Live partnerships to review your account. Until then, page through /v1/events or the feeds.
404bulk_not_foundWe could not find that bulk feed. Use the address shown on /partners/dashboard: /v1/bulk/<subscription id>.ndjson.gz or .csv.gz.
429bulk_too_soonA full file was made for this feed a few minutes ago. Full files can be made every 15 minutes. For what changed since, add changed_since=<time> — that is not limited.
410event_withdrawnThis event is no longer shared with partners. Stop showing it and remove its buy_url. Nothing else is needed — your old link still takes people to the event page.
400invalid_trackWe could not read that tracking signal. Send {"type":"impression"}, {"type":"event_view","event_id":"…"} or {"type":"event_click","event_id":"…"}. Sales are recorded by TimTim.Live, never sent from a page.
404not_foundThere is nothing at this address. The Partner API lives at /v1/events, /v1/events/{id}, /v1/offers and /v1/earnings.
405method_not_allowedThis address does not answer that method. The Allow header lists the methods it answers.
401key_in_urlSend your key in the Authorization header. Only /v1/feeds reads a key from the URL (?key=). Everywhere else use Authorization: Bearer <key> — keys in URLs end up in logs.
403ip_not_allowedThis key only works from your listed servers. Call from an address on the key's allowlist, or change the list at /partners/dashboard.
401certificate_requiredThis key needs your client certificate. Connect to https://api.timtim.live with the TLS client certificate pinned to this key.
401certificate_mismatchThat is not the certificate pinned to this key. Use the certificate whose SHA-256 is on your dashboard, or pin the new one there.
429rate_limitedToo many requests — please slow down. Wait the number of seconds in Retry-After, then try again.
503unavailableThe Partner API is resting for a moment. Please try again in a minute.
500server_errorSomething went wrong on our side. Please try again. If it keeps happening, send us your TimTim Request ID.

仕様書

すべての項目の説明です。ツールで読める OpenAPI 形式です。

openapi.yaml をダウンロード

本番キーが使えるまで

テストキーはすぐに使えます。本番キーは、TimTim.Live のスタッフが、会社名、ウェブサイト、イベントの見せ方を確認します。結果はダッシュボードで見られます。

TimTim.Live API のお知らせ

バージョン1は増えるだけです。新しいものを足します。今あるものを消したり、名前を変えたりはしません。

2026-10-08 — イベントの応答にETagが付くようになりました。If-None-Matchで送り返すと、変更がないときは素早く304が返ります。任意です。
2026-10-08 — ウェブサイトキーは訪問者ごとに数えるようになり、アクセスの多いサイトでも動き続けます。対応は不要です。
2026-10-07 — クライアント証明書（mTLS）が使えるようになりました：ダッシュボードで証明書をキーに結びつけてください。任意です。対応は不要です。
2026-10-07 — 一括フィード：表示できるすべてのイベントを1つのファイルで、GET /v1/bulk から。任意です。対応は不要です。
2026-10-07 — API に専用のアドレスができました：https://api.timtim.live/v1。https://timtim.live/v1 も引き続き使えます。対応は不要です。
2026-10-06 — あなたのブランドの支払いページ：timtim.live/checkout。任意です。対応は不要です。
2026-10-06 — あなたのアプリでチケットを販売：GET /v1/events/EVENT_ID/tickets と POST /v1/orders。任意です。対応は不要です。
2026-10-06 — 公開ステータスページ：/partners/status。毎分チェックしています。対応は不要です。
2026-10-06 — 企業向けの月次明細：GET /v1/settlements。対応は不要です。
2026-10-06 — ポストバック：購入リンクに ?sub_id= を付けると、売上と一緒にそれをお返しします。任意です。対応は不要です。
2026-10-06 — 銀行やポイントサービス向けのカード連動オファー：GET /v1/offers。任意です。対応は不要です。
2026-10-06 — カレンダーフィード：Google Calendar、Apple Calendar、Outlook 向けの /v1/feeds/events.ics。対応は不要です。
2026-10-06 — キーを自分のサーバーに固定：IP 許可リストは今すぐ、クライアント証明書（mTLS）は api.timtim.live で。任意です。対応は不要です。
2026-10-06 — 大規模な連携向けの OAuth 2.0 クライアントクレデンシャル：POST /v1/oauth/token と /v1/oauth/revoke。キーはそのまま使えます。対応は不要です。
2026-10-06 — WordPress プラグイン 1.0.0：ブロック、ショートコード、設定ページ。timtim.live から自動で更新されます。対応は不要です。
2026-10-06 — ウェブサイト用ウィジェット、JSON/RSS/XML/CSV のフィード、webhook（event.changed、earnings.changed）。対応は不要です。
2026-10-06 — Partner API v1：イベント一覧、1件のイベント、収益、サンドボックス。対応は不要です。