Partner API — 快速开始

你的第一次接入，一屏就能看完。

现在就试试——不要密钥，不用注册

在浏览器里打开这个地址。你马上就能看到示例活动。

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
查看结果
在控制台查看带来的人数、卖出的门票和收益，也可以通过请求获取。
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: 两个字母的国家代码，例如 US。
category: 例如音乐、节庆或会议。
from: 这一天或之后的活动（2026-10-20）。
to: 这一天或之前的活动。
changed_since: 只要这个时间之后有变化的活动。
commissioned: true = 只要有奖励的活动。
minimum_earnings: 只要每张票至少能赚这么多的活动。
near: 一个地点，例如 near=Paris,FR。
limit: 每页多少个活动，1 到 100（不填就是 20）。

只告诉我有什么变化

保存你上次同步的时间，作为 changed_since 发送。你只会收到有变化的活动，包括取消和售罄的演出。不需要 webhook。需要停止展示的活动会出现在 withdrawn 列表中。

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

不止一页

如果回复里有 next，把它作为 cursor= 发回来，就能拿到下一页。next 为空时，你就拿到全部了。

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

收益

每个活动都有 earn。如果 earn.eligible 是 false，这个活动没有奖励，但仍然值得展示。如果是 true，earn.description 会写明你能得到什么，例如“每张符合条件的门票 $5”。如果购买被退款，奖励会被收回。

批量数据源（所有内容在一个文件里）

在控制台保存一个批量数据源，然后把它包含的所有活动下载为一个压缩文件：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

请求速度上限

测试密钥：每分钟 60 次请求。正式密钥：每分钟 120 次。超过上限会收到 429 回复，并带有 Retry-After，也就是需要等待的秒数。

你能拿到哪些活动

TimTim.Live 主办方创建并选择分享的活动。我们从其他票务网站导入的活动绝不包括在内，因为我们没有分享它们的权利。

我们绝不发送的内容

买家姓名、电子邮件地址、家庭住址、电话号码和银行卡信息。Partner API 分享的是活动信息，不是我们的会员。

网站小部件

一行 HTML 就能在任何网站上展示活动。请使用网站密钥（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 和密码换取一个有效一小时的访问令牌，并用这个令牌代替密钥发送。密码永远不会随你的 API 请求传送，而且你可以申请比客户端更少的权限范围（scopes）。

# 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 和密码，把它 POST 到 /v1/oauth/revoke。在控制台关闭客户端，会一次结束它的所有令牌。

把密钥锁定到你的服务器

可选。在你的控制台中，打开服务器密钥、测试密钥或 OAuth 客户端下方的“锁定到我的服务器”，填写你服务器的公网地址。来自其他任何地方的请求（包括 token 请求）都会被拒绝，返回 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"
    }
  }
}

请检查每条消息：它用你的密钥签了名。超过五分钟的消息请拒绝。已经处理过的 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 — 批量数据源：你可以展示的所有活动，放在一个文件里，地址是 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 — Postback：在购买链接后加上 ?sub_id=，我们会把它和销售一起发回给你。可选。无需操作。
2026-10-06 — 给银行和奖励计划用的绑定银行卡的优惠：GET /v1/offers。可选。无需操作。
2026-10-06 — 日历订阅：/v1/feeds/events.ics，适用于 Google Calendar、Apple Calendar 和 Outlook。无需操作。
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：活动列表、单个活动、收益和沙盒。你不需要做任何事。