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، واكتب العناوين العامة لخوادمك. الطلبات — وطلبات الرمز — من أي مكان آخر تُرفض مع 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 — أصبح للواجهة البرمجية عنوانها الخاص: 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 للتكاملات الكبيرة: 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: الفعاليات، وفعالية واحدة، والأرباح، وبيئة الاختبار. لا تحتاج إلى فعل شيء.