Partner API — Mulai Cepat

Integrasi pertama Anda muat dalam satu layar.

Coba sekarang — tanpa kunci, tanpa daftar

Buka alamat ini di browser Anda. Anda langsung melihat acara contoh.

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

1
Ambil kunci uji
Masuk, beri tahu kami siapa Anda, lalu tekan Buat Kunci Uji. Kunci ini diawali tt_test_ dan hanya melihat acara contoh.

Cari acara

Minta acara di sebuah kota.

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

3
Tampilkan acara
Setiap acara punya nama, tanggal, tempat, gambar, harga, dan label siap pakai untuk kartu Anda.
4
Pakai buy_url
Pakai buy_url yang kami berikan. Selesai. TimTim.Live mencatat asal penjualan di dalam tautan itu.
5
Lihat hasil
Lihat orang yang dikirim, tiket terjual, dan pendapatan di dasbor Anda, atau minta datanya.
GET https://api.timtim.live/v1/earnings

Ambil Kunci Uji Saya Coba Tanpa Kunci

Status TimTim.Live

Referensi

Ke mana mengirim permintaan

https://api.timtim.live/v1

Kunci Koneksi Anda

Kirim kunci Anda di header Authorization. Kunci uji (tt_test_) hanya melihat acara contoh. Kunci situs (tt_pk_live_) boleh ada di halaman web dan hanya membaca acara. Kunci server (tt_sk_live_) tetap di server Anda dan juga bisa membaca pendapatan. Kami hanya menampilkan kunci satu kali — simpan dengan aman.

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

Filter

city: Acara di kota ini.
country: Kode negara dua huruf, misalnya US.
category: Misalnya musik, festival, atau konferensi.
from: Acara pada atau setelah tanggal ini (2026-10-20).
to: Acara pada atau sebelum tanggal ini.
changed_since: Hanya acara yang berubah setelah waktu ini.
commissioned: true = hanya acara yang memberi hadiah.
minimum_earnings: Hanya acara yang membayar setidaknya sebesar ini per tiket.
near: Sebuah tempat, misalnya near=Paris,FR.
limit: Berapa acara per halaman, 1 sampai 100 (20 jika tidak diisi).

Hanya beri tahu yang berubah

Simpan waktu sinkronisasi terakhir Anda dan kirim sebagai changed_since. Anda hanya mendapat acara yang berubah — termasuk pembatalan dan pertunjukan yang habis terjual. Tidak perlu webhook. Acara yang harus berhenti kamu tampilkan datang dalam daftar withdrawn.

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

Lebih dari satu halaman

Jika jawaban berisi next, kirim kembali sebagai cursor= untuk mendapat halaman berikutnya. Jika next kosong, Anda sudah punya semuanya.

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

Pendapatan

Setiap acara punya earn. Jika earn.eligible bernilai false, acara itu tidak punya hadiah — tetap layak ditampilkan. Jika bernilai true, earn.description menyebutkan apa yang Anda dapat, misalnya "$5 per tiket yang memenuhi syarat". Jika pembelian dikembalikan dananya, hadiah dibatalkan.

Feed massal (semua dalam satu file)

Simpan feed massal di dasbor Anda, lalu unduh semua acaranya dalam satu file terkompresi: GET /v1/bulk/FEED_ID.ndjson.gz atau .csv.gz, dengan kunci server Anda. Tambahkan ?changed_since= untuk yang berubah saja, termasuk acara yang diturunkan. Kunci uji bisa mencobanya sekarang; pemakaian sungguhan perlu pemeriksaan dari TimTim.Live.

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

Jual tiket di aplikasi Anda sendiri (perdagangan tertanam)

Mitra besar bisa membuat pembeli tetap di aplikasi mereka sendiri. Minta GET /v1/events/EVENT_ID/tickets untuk melihat apa yang dijual, lalu kirim POST /v1/orders dengan pilihan pembeli. Anda mendapat tautan pembayaran TimTim.Live untuk dibuka bagi pembeli; penjualan dicatat langsung untuk perusahaan Anda. Kunci uji bisa mencobanya sekarang. Pemakaian sungguhan perlu tinjauan TimTim.Live dan pembayaran kartu yang sudah aktif.

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

Penawaran terhubung kartu (bank dan program hadiah)

GET /v1/offers memberikan setiap acara yang membayar hadiah sebagai penawaran: penyelenggara, tanggal untuk membeli, harga, tempat, dan hadiah. Pelanggan Anda mengaktifkannya lewat tautan terlacak Anda, dan hadiah dibayarkan ke perusahaan Anda lewat /v1/earnings. Kunci uji melihat penawaran contoh. Penawaran nyata perlu ditinjau oleh TimTim.Live. Mencocokkan pembayaran kartu secara langsung perlu perjanjian dengan jaringan kartu atau bank, dan belum tersambung.

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

Status acara dan tiket

status bisa scheduled, postponed, rescheduled, cancelled, sold_out, atau completed. tickets.availability bisa available, limited, sold_out, not_on_sale, atau ended. Jika acara dibatalkan, turunkan acara itu.

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

Seberapa cepat Anda bisa bertanya

Kunci uji: 60 permintaan per menit. Kunci live: 120 per menit. Jika lebih cepat, Anda mendapat jawaban 429 dengan Retry-After, yaitu jumlah detik untuk menunggu.

Acara mana yang Anda dapat

Acara yang dibuat penyelenggara TimTim.Live dan mereka pilih untuk dibagikan. Acara yang kami ambil dari situs tiket lain tidak pernah disertakan, karena kami tidak punya hak untuk membagikannya.

Yang tidak pernah kami kirim

Nama pembeli, alamat email, alamat rumah, nomor telepon, dan data kartu. Partner API membagikan info acara, bukan anggota kami.

Widget situs

Satu baris HTML menampilkan acara di situs mana pun. Pakai kunci situs (tt_pk_live_) dan tambahkan situs Anda ke daftar situs yang diizinkan untuk kunci itu. Tanpa kunci, widget menampilkan acara contoh.

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

Pilihan: data-city, data-country, data-category, data-limit (1–24), data-earn="true", data-lang, dan data-color.

OAuth 2.0 (integrasi besar)

Opsional. Buat klien OAuth di dasbor Anda, lalu tukar client ID dan secret-nya dengan token akses satu jam, dan kirim token itu sebagai ganti kunci. Secret tidak pernah ikut dalam panggilan API Anda, dan Anda bisa meminta lebih sedikit izin (scopes) daripada yang dimiliki klien.

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

Untuk mengakhiri token lebih awal, kirim token itu dengan POST ke /v1/oauth/revoke memakai client ID dan secret yang sama. Mematikan klien di dasbor Anda mengakhiri semua tokennya sekaligus.

Batasi kunci ke server Anda

Opsional. Di dasbor Anda, buka "Kunci ke server saya" di bawah kunci server, kunci uji, atau klien OAuth, lalu tulis alamat publik server Anda. Panggilan — dan permintaan token — dari tempat lain ditolak dengan ip_not_allowed, meskipun kuncinya benar.

Sertifikat klien (mTLS): pasangkan sertifikat klien TLS Anda ke sebuah kunci, lalu panggil https://api.timtim.live dengan sertifikat itu. Setiap panggilan harus menunjukkan sertifikat itu; handshake TLS membuktikan bahwa Anda memegang kunci privatnya.

# 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

Pakai WordPress? Pasang TimTim.Live Events: satu blok dan satu shortcode yang menampilkan acara dengan tautan tiket TimTim.Live milik Anda sendiri. Plugin ini dibuat oleh TimTim.Live, hanya terhubung ke timtim.live, dan hanya diperbarui dari timtim.live.

Unggah file di Plugin → Tambah Baru → Unggah Plugin. Tempel kunci situs Anda di Pengaturan → TimTim.Live Events lalu tekan Test Connection. Setelah itu, tambahkan blok TimTim.Live Events ke halaman mana pun.

Unduh Plugin WordPress

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

Feed

Acara yang sama dalam JSON Feed, RSS, XML, CSV, atau kalender (.ics) yang bisa dilanggan oleh Google Calendar, Apple Calendar, dan Outlook. Pembaca feed tidak bisa mengirim header, jadi taruh kunci situs atau kunci uji di ?key=. Jangan pernah menaruh kunci server di tautan.

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

Tambahkan alamat di dasbor Anda dan kami mengirim pesan ke alamat itu saat ada yang berubah: event.changed atau earnings.changed. Webhook tidak wajib — changed_since memberi informasi yang sama.

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

Periksa setiap pesan: pesan ditandatangani dengan rahasia Anda. Tolak apa pun yang lebih lama dari lima menit, dan abaikan TimTim-Delivery-Id yang sudah Anda proses.

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

Balas dengan 2xx apa pun dalam 10 detik. Jika tidak, kami coba lagi setelah 1 menit, 5 menit, 30 menit, lalu 2, 6, 12, dan 24 jam, lalu berhenti. Kami tidak pernah mengikuti pengalihan.

Sandbox

Kunci uji mendapat acara contoh bertanda ACARA UJI — BUKAN UANG SUNGGUHAN. Buka buy_url, tekan Beli Tiket Uji, lalu minta pendapatan Anda. Coba pengembalian dana dan lihat pendapatan dibatalkan.

Saat ada yang salah

Pesan kesalahan menjelaskan dirinya dengan kata-kata sederhana, dengan judul dan langkah berikutnya. Setiap jawaban membawa TimTim-Request-Id. Kirimkan ke kami dan kami bisa menemukan permintaan Anda.

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.

Kontraknya

Penjelasan lengkap setiap kolom, dalam format OpenAPI yang bisa dibaca alat Anda.

Unduh openapi.yaml

Cara kunci live dibuka

Kunci uji Anda langsung berfungsi. Untuk kunci live, seseorang di TimTim.Live melihat nama perusahaan Anda, situs web Anda, dan cara Anda akan menampilkan acara. Anda melihat jawabannya di dasbor Anda.

Pembaruan API TimTim.Live

Versi 1 hanya bertambah. Kami menambah hal baru. Kami tidak menghapus atau mengganti nama yang sudah ada.

2026-10-08 — Jawaban acara kini membawa ETag. Kirim kembali di If-None-Match untuk mendapat 304 yang cepat saat tidak ada yang berubah. Opsional.
2026-10-08 — Kunci situs web kini menghitung setiap pengunjung secara terpisah, sehingga situs yang ramai tetap berjalan. Tidak perlu tindakan apa pun.
2026-10-07 — Sertifikat klien (mTLS) sudah dibuka: pasangkan sertifikat Anda ke sebuah kunci di dasbor Anda. Opsional. Tidak perlu tindakan apa pun.
2026-10-07 — Feed massal: setiap acara yang boleh Anda tampilkan, dalam satu file, di GET /v1/bulk. Opsional. Tidak perlu tindakan apa pun.
2026-10-07 — API punya alamat sendiri: https://api.timtim.live/v1. https://timtim.live/v1 tetap berfungsi. Tidak perlu melakukan apa pun.
2026-10-06 — Halaman pembayaran dengan merek Anda sendiri di timtim.live/checkout. Opsional. Tidak perlu tindakan apa pun.
2026-10-06 — Jual tiket di aplikasi Anda sendiri: GET /v1/events/EVENT_ID/tickets dan POST /v1/orders. Opsional. Tidak perlu tindakan apa pun.
2026-10-06 — Halaman status publik di /partners/status, diperiksa setiap menit. Tidak perlu tindakan apa pun.
2026-10-06 — Laporan bulanan untuk perusahaan: GET /v1/settlements. Tidak perlu tindakan apa pun.
2026-10-06 — Postback: tambahkan ?sub_id= ke tautan beli dan kami kirim kembali kepada Anda bersama penjualannya. Opsional. Tidak perlu tindakan apa pun.
2026-10-06 — Penawaran terhubung kartu untuk bank dan program hadiah: GET /v1/offers. Opsional. Tidak perlu tindakan apa pun.
2026-10-06 — Feed kalender: /v1/feeds/events.ics untuk Google Calendar, Apple Calendar, dan Outlook. Tidak perlu melakukan apa pun.
2026-10-06 — Batasi kunci ke server Anda: daftar IP yang diizinkan sekarang, sertifikat klien (mTLS) di api.timtim.live. Opsional. Tidak perlu melakukan apa pun.
2026-10-06 — OAuth 2.0 client credentials untuk integrasi besar: POST /v1/oauth/token dan /v1/oauth/revoke. Kunci tetap berfungsi. Tidak perlu tindakan apa pun.
2026-10-06 — Plugin WordPress 1.0.0: satu blok, satu shortcode, dan satu halaman pengaturan. Plugin ini memperbarui dirinya sendiri dari timtim.live. Tidak perlu tindakan apa pun.
2026-10-06 — Widget situs, feed JSON/RSS/XML/CSV, dan webhook (event.changed, earnings.changed). Tidak perlu tindakan apa pun.
2026-10-06 — Partner API v1: acara, satu acara, pendapatan, dan sandbox. Tidak perlu tindakan apa pun.