Partner API — Bắt đầu nhanh

Lần kết nối đầu tiên của bạn chỉ cần một màn hình.

Thử ngay — không cần khóa, không cần đăng ký

Mở địa chỉ này trong trình duyệt. Bạn sẽ thấy sự kiện mẫu ngay.

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

1
Lấy khóa thử
Đăng nhập, cho chúng tôi biết bạn là ai, rồi bấm Tạo khóa thử. Khóa bắt đầu bằng tt_test_ và chỉ thấy sự kiện mẫu.

Tìm sự kiện

Hỏi các sự kiện ở một thành phố.

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

3
Hiện sự kiện
Mỗi sự kiện có tên, ngày, địa điểm, hình ảnh, giá và nhãn làm sẵn cho thẻ của bạn.
4
Dùng buy_url
Dùng buy_url chúng tôi đưa cho bạn. Vậy là xong. TimTim.Live ghi nhận lượt bán đến từ bạn ngay trong đường link đó.
5
Xem kết quả
Xem số người bạn gửi, số vé bán được và thu nhập trên bảng điều khiển, hoặc hỏi qua API.
GET https://api.timtim.live/v1/earnings

Lấy khóa thử của tôi Thử mà không cần khóa

Trạng thái TimTim.Live

Tra cứu

Gửi yêu cầu đến đâu

https://api.timtim.live/v1

Khóa kết nối của bạn

Gửi khóa của bạn trong header Authorization. Khóa thử (tt_test_) chỉ thấy sự kiện mẫu. Khóa trang web (tt_pk_live_) có thể đặt trong trang web và chỉ đọc sự kiện. Khóa máy chủ (tt_sk_live_) ở trên máy chủ của bạn và đọc được cả thu nhập. Chúng tôi chỉ hiện khóa một lần — hãy giữ cẩn thận.

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;
}

Bộ lọc

city: Sự kiện ở thành phố này.
country: Mã quốc gia hai chữ cái, ví dụ US.
category: Ví dụ âm nhạc, lễ hội hoặc hội nghị.
from: Sự kiện vào ngày này hoặc sau đó (2026-10-20).
to: Sự kiện vào ngày này hoặc trước đó.
changed_since: Chỉ những sự kiện thay đổi sau thời điểm này.
commissioned: true = chỉ những sự kiện có phần thưởng.
minimum_earnings: Chỉ những sự kiện trả ít nhất chừng này cho mỗi vé.
near: Một địa điểm, ví dụ near=Paris,FR.
limit: Bao nhiêu sự kiện mỗi trang, từ 1 đến 100 (để trống là 20).

Chỉ cho tôi biết điều gì đã thay đổi

Lưu thời điểm lần đồng bộ cuối và gửi nó dưới dạng changed_since. Bạn chỉ nhận những sự kiện đã thay đổi — gồm cả sự kiện bị hủy và đã hết vé. Không cần webhook. Những sự kiện bạn phải ngừng hiển thị sẽ nằm trong danh sách withdrawn.

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

Nhiều hơn một trang

Nếu câu trả lời có next, hãy gửi lại nó dưới dạng cursor= để lấy trang tiếp theo. Khi next trống, bạn đã có tất cả.

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

Thu nhập

Mỗi sự kiện có earn. Nếu earn.eligible là false, sự kiện không có phần thưởng — nhưng vẫn đáng để giới thiệu. Nếu là true, earn.description cho biết bạn nhận gì, ví dụ "$5 cho mỗi vé đủ điều kiện". Nếu lần mua được hoàn tiền, phần thưởng sẽ bị trừ lại.

Nguồn dữ liệu trọn gói (mọi thứ trong một tệp)

Lưu một nguồn dữ liệu trọn gói trên bảng điều khiển, rồi tải mọi sự kiện của nó trong một tệp nén duy nhất: GET /v1/bulk/FEED_ID.ndjson.gz hoặc .csv.gz, bằng khóa máy chủ của bạn. Thêm ?changed_since= để chỉ nhận phần đã thay đổi, kể cả sự kiện bị gỡ xuống. Khóa thử có thể dùng thử ngay; dùng thật cần TimTim.Live xem xét.

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

Bán vé ngay trong ứng dụng của bạn (thương mại nhúng)

Đối tác lớn có thể giữ người mua ở lại trong ứng dụng của mình. Gọi GET /v1/events/EVENT_ID/tickets để xem đang bán gì, rồi gửi POST /v1/orders với lựa chọn của người mua. Bạn nhận được một đường link thanh toán TimTim.Live để mở cho người mua; lượt bán được ghi thẳng cho công ty bạn. Khóa thử có thể dùng thử ngay bây giờ. Dùng thật cần TimTim.Live xem xét và bật thanh toán bằng thẻ.

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": "…"}

Ưu đãi gắn với thẻ (ngân hàng và chương trình ưu đãi)

GET /v1/offers đưa mỗi sự kiện có trả phần thưởng thành một ưu đãi: người tổ chức, những ngày có thể mua, giá, địa điểm và phần thưởng. Khách hàng của bạn kích hoạt ưu đãi qua đường link theo dõi của bạn, và phần thưởng được trả cho công ty bạn qua /v1/earnings. Khóa thử thấy các ưu đãi mẫu. Ưu đãi thật cần TimTim.Live xem xét. Khớp trực tiếp các khoản thanh toán bằng thẻ cần thỏa thuận với một mạng lưới thẻ hoặc ngân hàng, và chưa được kết nối.

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

Trạng thái sự kiện và vé

status là scheduled, postponed, rescheduled, cancelled, sold_out hoặc completed. tickets.availability là available, limited, sold_out, not_on_sale hoặc ended. Khi sự kiện bị hủy, hãy gỡ nó xuống.

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

Bạn có thể hỏi nhanh đến đâu

Khóa thử: 60 yêu cầu mỗi phút. Khóa chính thức: 120 mỗi phút. Nhanh hơn sẽ nhận câu trả lời 429 kèm Retry-After, là số giây cần chờ.

Bạn nhận những sự kiện nào

Sự kiện do người tổ chức trên TimTim.Live tạo và chọn chia sẻ. Sự kiện chúng tôi lấy từ các trang bán vé khác không bao giờ có trong đó, vì chúng tôi không có quyền chia sẻ chúng.

Những gì chúng tôi không bao giờ gửi

Tên người mua, địa chỉ email, địa chỉ nhà, số điện thoại và thông tin thẻ. Partner API chia sẻ thông tin sự kiện, không chia sẻ thành viên của chúng tôi.

Widget cho trang web

Một dòng HTML hiện sự kiện trên bất kỳ trang web nào. Hãy dùng khóa trang web (tt_pk_live_) và thêm trang web của bạn vào danh sách được phép của khóa. Nếu không có khóa, widget hiện sự kiện mẫu.

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

Tùy chọn: data-city, data-country, data-category, data-limit (1–24), data-earn="true", data-lang và data-color.

OAuth 2.0 (tích hợp lớn)

Không bắt buộc. Tạo một client OAuth trên bảng điều khiển, rồi đổi mã client và mật mã của nó lấy một token truy cập một giờ, và gửi token đó thay cho khóa. Mật mã không bao giờ đi cùng các lệnh gọi API của bạn, và bạn có thể xin ít quyền (scopes) hơn những gì client có.

# 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"

Để kết thúc token sớm, hãy gửi nó bằng POST tới /v1/oauth/revoke với cùng mã client và mật mã. Tắt client trên bảng điều khiển sẽ kết thúc mọi token của nó cùng lúc.

Giới hạn khóa cho máy chủ của bạn

Không bắt buộc. Trên bảng điều khiển, mở "Chỉ dùng trên máy chủ của tôi" bên dưới một khóa máy chủ, khóa thử hoặc client OAuth, rồi ghi địa chỉ công khai của các máy chủ của bạn. Lệnh gọi — và yêu cầu token — từ bất kỳ nơi nào khác sẽ bị từ chối với ip_not_allowed, kể cả khi có đúng khóa.

Chứng chỉ client (mTLS): gắn chứng chỉ client TLS của bạn với một khóa, rồi gọi https://api.timtim.live bằng chứng chỉ đó. Mỗi lệnh gọi phải trình chứng chỉ đó; bắt tay TLS chứng minh bạn giữ khóa riêng của nó.

# 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"

Plugin WordPress

Bạn dùng WordPress? Hãy cài TimTim.Live Events: một khối và một shortcode hiện sự kiện kèm liên kết vé TimTim.Live của riêng bạn. Plugin do TimTim.Live làm, chỉ kết nối với timtim.live và chỉ cập nhật từ timtim.live.

Tải tệp lên ở Plugin → Cài mới → Tải plugin lên. Dán khóa trang web của bạn vào Cài đặt → TimTim.Live Events rồi bấm Test Connection. Sau đó thêm khối TimTim.Live Events vào trang bất kỳ.

Tải plugin WordPress

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

Nguồn dữ liệu

Cùng các sự kiện đó dưới dạng JSON Feed, RSS, XML, CSV hoặc lịch (.ics) mà Google Calendar, Apple Calendar và Outlook có thể đăng ký theo dõi. Trình đọc nguồn tin không gửi được header, nên hãy đặt khóa trang web hoặc khóa thử vào ?key=. Đừng bao giờ đặt khóa máy chủ vào đường link.

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

Bấm "Thêm địa chỉ" trên bảng điều khiển, và chúng tôi gửi tin nhắn đến địa chỉ đó khi có thay đổi: event.changed hoặc earnings.changed. Webhook không bắt buộc — changed_since cho bạn cùng thông tin.

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

Hãy kiểm tra mọi tin nhắn: nó được ký bằng mã bí mật của bạn. Hãy từ chối tin nhắn cũ hơn năm phút, và bỏ qua TimTim-Delivery-Id bạn đã xử lý rồi.

// 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);
});

Hãy trả lời bằng bất kỳ mã 2xx nào trong vòng 10 giây. Nếu không, chúng tôi thử lại sau 1 phút, 5 phút, 30 phút, rồi 2, 6, 12 và 24 giờ, rồi dừng. Chúng tôi không bao giờ đi theo chuyển hướng.

Sandbox

Khóa thử nhận sự kiện mẫu có nhãn SỰ KIỆN THỬ — KHÔNG CÓ TIỀN THẬT. Mở một buy_url, bấm Mua vé thử, rồi hỏi thu nhập của bạn. Thử hoàn tiền và xem thu nhập bị trừ lại.

Khi có lỗi

Lỗi được giải thích bằng lời đơn giản, có tiêu đề và việc cần làm tiếp theo. Mỗi câu trả lời đều có TimTim-Request-Id. Gửi nó cho chúng tôi để chúng tôi tìm được yêu cầu của bạn.

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.

Bản mô tả

Mô tả đầy đủ mọi trường dữ liệu, theo định dạng OpenAPI mà công cụ của bạn đọc được.

Tải openapi.yaml

Khóa thật được mở như thế nào

Khóa thử của bạn dùng được ngay. Với khóa thật, một người ở TimTim.Live sẽ xem tên công ty, trang web của bạn và cách bạn sẽ hiển thị sự kiện. Bạn sẽ thấy câu trả lời trên bảng điều khiển.

Cập nhật API TimTim.Live

Phiên bản 1 chỉ lớn thêm. Chúng tôi thêm cái mới. Chúng tôi không xóa hay đổi tên những gì đã có.

2026-10-08 — Câu trả lời về sự kiện giờ có ETag. Gửi lại nó trong If-None-Match để nhận 304 nhanh khi không có gì thay đổi. Không bắt buộc.
2026-10-08 — Khóa trang web giờ đếm từng khách truy cập riêng, nên các trang đông khách vẫn hoạt động. Bạn không cần làm gì.
2026-10-07 — Chứng chỉ client (mTLS) đã mở: gắn chứng chỉ của bạn với một khóa trên bảng điều khiển. Không bắt buộc. Bạn không cần làm gì.
2026-10-07 — Nguồn dữ liệu trọn gói: mọi sự kiện bạn được hiển thị, trong một tệp, tại GET /v1/bulk. Không bắt buộc. Bạn không cần làm gì.
2026-10-07 — API có địa chỉ riêng: https://api.timtim.live/v1. https://timtim.live/v1 vẫn tiếp tục hoạt động. Không cần làm gì.
2026-10-06 — Trang thanh toán mang thương hiệu của riêng bạn tại timtim.live/checkout. Không bắt buộc. Bạn không cần làm gì.
2026-10-06 — Bán vé trong ứng dụng của bạn: GET /v1/events/EVENT_ID/tickets và POST /v1/orders. Không bắt buộc. Bạn không cần làm gì.
2026-10-06 — Trang trạng thái công khai tại /partners/status, được kiểm tra mỗi phút. Bạn không cần làm gì.
2026-10-06 — Bảng kê hằng tháng cho công ty: GET /v1/settlements. Bạn không cần làm gì.
2026-10-06 — Postback: thêm ?sub_id= vào đường link mua và chúng tôi gửi lại nó cho bạn cùng với lượt bán. Không bắt buộc. Bạn không cần làm gì.
2026-10-06 — Ưu đãi gắn với thẻ cho ngân hàng và chương trình ưu đãi: GET /v1/offers. Không bắt buộc. Bạn không cần làm gì.
2026-10-06 — Nguồn lịch: /v1/feeds/events.ics cho Google Calendar, Apple Calendar và Outlook. Bạn không cần làm gì.
2026-10-06 — Giới hạn khóa cho máy chủ của bạn: danh sách IP được phép ngay bây giờ, chứng chỉ client (mTLS) trên api.timtim.live. Không bắt buộc. Bạn không cần làm gì.
2026-10-06 — OAuth 2.0 client credentials cho các tích hợp lớn: POST /v1/oauth/token và /v1/oauth/revoke. Khóa vẫn dùng được. Bạn không cần làm gì.
2026-10-06 — Plugin WordPress 1.0.0: một khối, một shortcode và một trang cài đặt. Plugin tự cập nhật từ timtim.live. Bạn không cần làm gì.
2026-10-06 — Widget cho trang web, nguồn dữ liệu JSON/RSS/XML/CSV và webhook (event.changed, earnings.changed). Bạn không cần làm gì.
2026-10-06 — Partner API v1: danh sách sự kiện, một sự kiện, thu nhập và sandbox. Bạn không cần làm gì.