Partner API — Anza Haraka

Muunganisho wako wa kwanza unatosha kwenye skrini moja.

Jaribu sasa — bila ufunguo, bila kujisajili

Fungua anwani hii kwenye kivinjari chako. Utaona matukio ya mfano mara moja.

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

1
Pata ufunguo wa majaribio
Ingia, tuambie wewe ni nani, kisha bonyeza Unda Ufunguo wa Majaribio. Unaanza na tt_test_ na unaona matukio ya mfano tu.

Tafuta matukio

Omba matukio ya jiji fulani.

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

3
Onyesha tukio
Kila tukio lina jina, tarehe, mahali, picha, bei na maandishi tayari kwa kadi yako.
4
Tumia buy_url
Tumia buy_url tunayokupa. Ni hivyo tu. TimTim.Live inashughulikia ufuatiliaji ndani ya kiungo hicho.
5
Tazama matokeo
Ona watu uliowatuma, tiketi zilizouzwa na mapato kwenye dashibodi yako, au uyaombe.
GET https://api.timtim.live/v1/earnings

Pata Ufunguo Wangu wa Majaribio Jaribu Bila Ufunguo

Hali ya TimTim.Live

Marejeo

Mahali pa kutuma maombi

https://api.timtim.live/v1

Ufunguo Wako wa Muunganisho

Tuma ufunguo wako kwenye kichwa cha Authorization. Funguo za majaribio (tt_test_) zinaona matukio ya mfano tu. Funguo za tovuti (tt_pk_live_) zinaweza kukaa kwenye ukurasa wa wavuti na zinasoma matukio tu. Funguo za seva (tt_sk_live_) zinabaki kwenye seva yako na zinaweza pia kusoma mapato. Tunaonyesha ufunguo mara moja tu — uutunze salama.

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

Vichujio

city: Matukio katika jiji hili.
country: Msimbo wa nchi wa herufi mbili, kwa mfano US.
category: Kwa mfano music, festival au conference.
from: Matukio ya tarehe hii au baadaye (2026-10-20).
to: Matukio ya tarehe hii au kabla yake.
changed_since: Matukio tu yaliyobadilika baada ya muda huu.
commissioned: true = matukio tu yanayolipa zawadi.
minimum_earnings: Matukio tu yanayolipa angalau kiasi hiki kwa kila tiketi.
near: Mahali, kwa mfano near=Paris,FR.
limit: Matukio mangapi kwa kila ukurasa, 1 hadi 100 (20 usipoweka).

Niambie tu kilichobadilika

Hifadhi muda wa usawazishaji wako wa mwisho na uutume kama changed_since. Utapata matukio tu yaliyobadilika — pamoja na yaliyoghairiwa na maonyesho yaliyojaa. Hakuna haja ya webhook. Matukio unayopaswa kuacha kuonyesha yanakuja kwenye orodha ya withdrawn.

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

Zaidi ya ukurasa mmoja

Jibu likiwa na next, lirudishe kama cursor= ili kupata ukurasa unaofuata. next ikiwa tupu, umepata kila kitu.

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

Kupata mapato

Kila tukio lina earn. Ikiwa earn.eligible ni false, tukio halina zawadi — bado linafaa kuonyeshwa. Ikiwa ni true, earn.description inasema unapata nini, kwa mfano "$5 kwa kila tiketi inayostahili". Ununuzi ukirudishiwa pesa, zawadi inarudishwa.

Mipasho kamili (kila kitu katika faili moja)

Hifadhi mpasho kamili kwenye dashibodi yako, kisha pakua matukio yake yote katika faili moja lililobanwa: GET /v1/bulk/FEED_ID.ndjson.gz au .csv.gz, kwa ufunguo wako wa seva. Ongeza ?changed_since= ili kupata yaliyobadilika tu, pamoja na matukio yaliyoondolewa. Funguo za majaribio zinaweza kuujaribu sasa; matumizi halisi yanahitaji ukaguzi wa TimTim.Live.

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

Uza tiketi ndani ya programu yako (biashara iliyopachikwa)

Washirika wakubwa wanaweza kuwaweka wanunuzi ndani ya programu yao. Uliza GET /v1/events/EVENT_ID/tickets kuona kinachouzwa, kisha tuma POST /v1/orders pamoja na chaguo la mnunuzi. Unapata kiungo cha malipo cha TimTim.Live cha kumfungulia mnunuzi; mauzo yanahesabiwa moja kwa moja kwa kampuni yako. Funguo za majaribio zinaweza kujaribu sasa. Matumizi halisi yanahitaji ukaguzi wa TimTim.Live na malipo ya kadi kuwashwa.

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

Ofa zilizounganishwa na kadi (benki na programu za zawadi)

GET /v1/offers inatoa kila tukio linalolipa zawadi kama ofa: mratibu, tarehe unazoweza kununua, bei, mahali na zawadi. Mteja wako anaiwasha kupitia kiungo chako kinachofuatiliwa, na zawadi inalipwa kwa kampuni yako kupitia /v1/earnings. Funguo za majaribio zinaona ofa za mfano. Ofa halisi zinahitaji ukaguzi wa TimTim.Live. Kulinganisha malipo ya kadi moja kwa moja kunahitaji makubaliano na mtandao wa kadi au benki, na hilo halijaunganishwa.

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

Hali ya tukio na tiketi

status ni scheduled, postponed, rescheduled, cancelled, sold_out au completed. tickets.availability ni available, limited, sold_out, not_on_sale au ended. Tukio likiwa cancelled, liondoe.

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

Unaweza kuuliza kwa kasi gani

Funguo za majaribio: maombi 60 kwa dakika. Funguo halisi: 120 kwa dakika. Ukienda kasi zaidi utapata jibu la 429 lenye Retry-After, idadi ya sekunde za kusubiri.

Matukio gani unapata

Matukio ambayo waratibu wa TimTim.Live wanaunda na kuchagua kushiriki. Matukio tuliyoleta kutoka tovuti nyingine za tiketi hayajumuishwi kamwe, kwa sababu hatuna haki ya kuyashiriki.

Tusichotuma kamwe

Majina ya wanunuzi, anwani za barua pepe, anwani za nyumbani, namba za simu na taarifa za kadi. Partner API inashiriki habari za matukio, si wanachama wetu.

Wijeti ya tovuti

Mstari mmoja wa HTML unaonyesha matukio kwenye tovuti yoyote. Tumia ufunguo wa tovuti (tt_pk_live_) na uongeze tovuti yako kwenye orodha ya tovuti zinazoruhusiwa za ufunguo huo. Bila ufunguo inaonyesha matukio ya mfano.

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

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

OAuth 2.0 (miunganisho mikubwa)

Si lazima. Unda mteja wa OAuth kwenye dashibodi yako, kisha badilisha kitambulisho chake cha mteja na siri kupata tokeni ya ufikiaji ya saa moja, na utume tokeni hiyo badala ya ufunguo. Siri haisafiri kamwe na maombi yako ya API, na unaweza kuomba ruhusa (scopes) chache kuliko alizo nazo mteja.

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

Ili kumaliza tokeni mapema, itume kwa POST kwenda /v1/oauth/revoke ukitumia kitambulisho cha mteja na siri ileile. Ukizima mteja kwenye dashibodi yako, tokeni zake zote zinaisha mara moja.

Funga ufunguo kwa seva zako

Si lazima. Kwenye dashibodi yako, fungua "Funga kwa seva zangu" chini ya ufunguo wa seva, ufunguo wa majaribio au mteja wa OAuth, kisha andika anwani za umma za seva zako. Simu — na maombi ya token — kutoka mahali pengine popote zinakataliwa kwa ip_not_allowed, hata kwa ufunguo sahihi.

Vyeti vya mteja (mTLS): unganisha cheti chako cha mteja cha TLS na ufunguo, kisha piga https://api.timtim.live ukitumia cheti hicho. Kila simu lazima ionyeshe cheti hicho; handshake ya TLS inathibitisha kwamba unashikilia ufunguo wake wa siri.

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

Programu-jalizi ya WordPress

Unatumia WordPress? Sakinisha TimTim.Live Events: bloku na shortcode zinazoonyesha matukio pamoja na viungo vyako vya tiketi vya TimTim.Live. Imetengenezwa na TimTim.Live, inazungumza na timtim.live tu, na inasasishwa kutoka timtim.live tu.

Pakia faili katika Plugins → Add New → Upload Plugin. Bandika ufunguo wako wa tovuti katika Settings → TimTim.Live Events na ubonyeze Test Connection. Kisha ongeza bloku ya TimTim.Live Events kwenye ukurasa wowote.

Pakua Programu-jalizi ya WordPress

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

Mipasho

Matukio yale yale kama JSON Feed, RSS, XML, CSV au kalenda (.ics) ambayo Google Calendar, Apple Calendar na Outlook zinaweza kujisajili. Visomaji vya mipasho haviwezi kutuma headers, kwa hiyo weka ufunguo wa tovuti au ufunguo wa majaribio kwenye ?key=. Usiweke kamwe ufunguo wa seva kwenye kiungo.

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

Ongeza anwani kwenye dashibodi yako, nasi tutaitumia ujumbe kitu kinapobadilika: event.changed au earnings.changed. Webhooks si lazima — changed_since inakupa taarifa zile zile.

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

Kagua kila ujumbe: umetiwa sahihi kwa siri yako. Kataa chochote kilicho na zaidi ya dakika tano, na upuuze TimTim-Delivery-Id ambayo tayari umeishughulikia.

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

Jibu kwa 2xx yoyote ndani ya sekunde 10. Usipojibu, tunajaribu tena baada ya dakika 1, dakika 5, dakika 30, kisha saa 2, 6, 12 na 24, kisha tunaacha. Hatufuati kamwe uelekezaji upya.

Eneo la majaribio

Funguo za majaribio zinapata matukio ya mfano yenye alama TUKIO LA MAJARIBIO — HAKUNA PESA HALISI. Fungua buy_url, bonyeza Nunua Tiketi ya Majaribio, kisha omba mapato yako. Jaribu kurudisha pesa na uone yakirudishwa.

Kitu kikienda vibaya

Makosa yanajieleza kwa maneno rahisi, yakiwa na kichwa na nini cha kufanya baadaye. Kila jibu lina TimTim-Request-Id. Tutumie, nasi tutapata ombi lako.

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.

Mkataba wa API

Maelezo kamili ya kila sehemu, katika muundo wa OpenAPI ambao zana zako zinaweza kusoma.

Pakua openapi.yaml

Jinsi funguo halisi zinavyofunguliwa

Ufunguo wako wa majaribio unafanya kazi mara moja. Kwa funguo halisi, mtu wa TimTim.Live anaangalia jina la kampuni yako, tovuti yako na jinsi utakavyoonyesha matukio. Utaona jibu kwenye dashibodi yako.

Habari Mpya za API ya TimTim.Live

Toleo la 1 linakua tu. Tunaongeza vitu vipya. Hatuondoi wala kubadilisha jina la kilichopo tayari.

2026-10-08 — Majibu ya matukio sasa yana ETag. Irudishe kwenye If-None-Match upate 304 haraka wakati hakuna kilichobadilika. Si lazima.
2026-10-08 — Funguo za tovuti sasa zinahesabu kila mgeni peke yake, ili tovuti zenye wageni wengi ziendelee kufanya kazi. Huhitaji kufanya chochote.
2026-10-07 — Vyeti vya mteja (mTLS) vimefunguliwa: unganisha cheti chako na ufunguo kwenye dashibodi yako. Si lazima. Huhitaji kufanya chochote.
2026-10-07 — Mipasho kamili: kila tukio unaloruhusiwa kuonyesha, katika faili moja, kwenye GET /v1/bulk. Si lazima. Huhitaji kufanya chochote.
2026-10-07 — API ina anwani yake: https://api.timtim.live/v1. https://timtim.live/v1 inaendelea kufanya kazi. Hakuna kinachohitajika kufanywa.
2026-10-06 — Ukurasa wako wa malipo wenye chapa yako kwenye timtim.live/checkout. Si lazima. Huhitaji kufanya chochote.
2026-10-06 — Uza tiketi ndani ya programu yako: GET /v1/events/EVENT_ID/tickets na POST /v1/orders. Si lazima. Huhitaji kufanya chochote.
2026-10-06 — Ukurasa wa hali ulio wazi kwa wote kwenye /partners/status, unaokaguliwa kila dakika. Huhitaji kufanya chochote.
2026-10-06 — Taarifa za kila mwezi kwa makampuni: GET /v1/settlements. Huhitaji kufanya chochote.
2026-10-06 — Postbacks: ongeza ?sub_id= kwenye kiungo cha kununua na tutakurudishia pamoja na mauzo. Si lazima. Huhitaji kufanya chochote.
2026-10-06 — Ofa zilizounganishwa na kadi kwa benki na programu za zawadi: GET /v1/offers. Si lazima. Huhitaji kufanya chochote.
2026-10-06 — Mpasho wa kalenda: /v1/feeds/events.ics kwa Google Calendar, Apple Calendar na Outlook. Huhitaji kufanya chochote.
2026-10-06 — Funga ufunguo kwa seva zako: orodha za IP zinazoruhusiwa sasa, vyeti vya mteja (mTLS) kwenye api.timtim.live. Si lazima. Huhitaji kufanya chochote.
2026-10-06 — OAuth 2.0 client credentials kwa miunganisho mikubwa: POST /v1/oauth/token na /v1/oauth/revoke. Funguo zinaendelea kufanya kazi. Huhitaji kufanya chochote.
2026-10-06 — Programu-jalizi ya WordPress 1.0.0: bloku, shortcode na ukurasa wa mipangilio. Inajisasisha yenyewe kutoka timtim.live. Huhitaji kufanya chochote.
2026-10-06 — Wijeti ya tovuti, mipasho ya JSON/RSS/XML/CSV na webhooks (event.changed, earnings.changed). Huhitaji kufanya chochote.
2026-10-06 — Partner API v1: matukio, tukio moja, mapato, na eneo la majaribio. Huhitaji kufanya chochote.