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: למשל music, festival או conference.
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 בלוח שלכם, ואז החליפו את מזהה הלקוח והסוד שלו באסימון גישה לשעה אחת, ושלחו את האסימון הזה במקום מפתח. הסוד אף פעם לא עובר עם קריאות ה-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"

כדי לסיים אסימון מוקדם, שלחו אותו ב-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 או כלוח שנה (.ics) ש-Google Calendar, Apple Calendar ו-Outlook יכולים להירשם אליו. קוראי פידים לא יכולים לשלוח כותרות, אז שימו מפתח אתר או מפתח ניסיון ב-?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

Webhooks

לחצו על "הוספת כתובת" בלוח הבקרה, ואנחנו נשלח לכתובת הודעה כשמשהו משתנה: event.changed או earnings.changed. Webhooks הם לא חובה — 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);
});

ענו עם כל 2xx תוך 10 שניות. אם לא, ננסה שוב אחרי 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 — Postbacks: הוסיפו ?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 client credentials לחיבורים גדולים: POST /v1/oauth/token ו-/v1/oauth/revoke. המפתחות ממשיכים לעבוד. לא צריך לעשות כלום.
2026-10-06 — תוסף WordPress 1.0.0: בלוק, שורטקוד ועמוד הגדרות. הוא מתעדכן לבד מ-timtim.live. לא צריך לעשות כלום.
2026-10-06 — וידג'ט לאתר, פידים של JSON/RSS/XML/CSV ו-webhooks (event.changed, earnings.changed). לא צריך לעשות כלום.
2026-10-06 — Partner API גרסה 1: אירועים, אירוע בודד, רווחים וסביבת הניסוי. לא צריך לעשות כלום.