Partner API — Gyors kezdés

Az első bekötésed elfér egy képernyőn.

Próbáld ki most — kulcs és regisztráció nélkül

Nyisd meg ezt a címet a böngésződben. Azonnal mintaeseményeket látsz.

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

1
Kérj tesztkulcsot
Jelentkezz be, mondd el, ki vagy, és nyomd meg a Tesztkulcs létrehozása gombot. A kulcs tt_test_ kezdetű, és csak mintaeseményeket lát.

Keress eseményeket

Kérj eseményeket egy városban.

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

3
Mutasd meg az eseményt
Minden eseménynek van neve, dátuma, helyszíne, képe, ára és kész felirata a kártyádhoz.
4
Használd a buy_url-t
Használd a buy_url-t, amit adunk. Ennyi. A TimTim.Live a linken belül rögzíti, honnan jött az eladás.
5
Nézd meg az eredményt
Az irányítópultodon látod, hány embert küldtél, hány jegy kelt el és mennyi a bevétel — vagy kérd le őket.
GET https://api.timtim.live/v1/earnings

Tesztkulcsot kérek Kipróbálom kulcs nélkül

TimTim.Live állapot

Referencia

Hová küldd a kéréseket

https://api.timtim.live/v1

A kapcsolódási kulcsod

Küldd a kulcsodat az Authorization fejlécben. A tesztkulcsok (tt_test_) csak mintaeseményeket látnak. A weboldalkulcsok (tt_pk_live_) lehetnek egy weboldalon, és csak eseményeket olvasnak. A szerverkulcsok (tt_sk_live_) a szervereden maradnak, és a bevételeket is olvassák. Egy kulcsot csak egyszer mutatunk meg — őrizd biztonságban.

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

Szűrők

city: Események ebben a városban.
country: Kétbetűs országkód, például US.
category: Például zene, fesztivál vagy konferencia.
from: Események ezen a napon vagy utána (2026-10-20).
to: Események ezen a napon vagy előtte.
changed_since: Csak az ez után az időpont után változott események.
commissioned: true = csak a jutalmat fizető események.
minimum_earnings: Csak azok az események, amelyek jegyenként legalább ennyit fizetnek.
near: Egy hely, például near=Paris,FR.
limit: Hány esemény legyen egy oldalon, 1 és 100 között (20, ha nem adod meg).

Csak azt mondd, mi változott

Mentsd el az utolsó szinkronizálás idejét, és küldd el changed_since értékként. Csak a megváltozott eseményeket kapod — a lemondásokat és a teltházas előadásokat is. Nem kell webhook. Azok az események, amelyeket már nem szabad megjelenítened, a withdrawn listában érkeznek.

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

Több oldal

Ha a válaszban van next, küldd vissza cursor= értékként a következő oldalért. Ha a next üres, mindent megkaptál.

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

Bevétel

Minden eseménynek van earn mezője. Ha az earn.eligible értéke false, az eseményhez nem tartozik jutalom — ettől még érdemes megmutatni. Ha true, az earn.description megmondja, mit kapsz, például „$5 jogosult jegyenként”. Ha a vásárlást visszatérítik, a jutalmat visszavonjuk.

Tömeges feedek (minden egy fájlban)

Ments el egy tömeges feedet az irányítópultodon, majd töltsd le az összes eseményét egyetlen tömörített fájlban: GET /v1/bulk/FEED_ID.ndjson.gz vagy .csv.gz, a szerverkulcsoddal. Add hozzá a ?changed_since= részt, ha csak a változásokat kéred, a levett eseményekkel együtt. A tesztkulcsok már most kipróbálhatják; az éles használathoz a TimTim.Live ellenőrzése kell.

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

Adj el jegyeket a saját alkalmazásodban (beépített értékesítés)

A nagy partnerek a saját alkalmazásukban tarthatják a vevőket. Kérdezd le GET /v1/events/EVENT_ID/tickets hívással, mi kapható, majd küldd el POST /v1/orders hívással a vevő választását. Kapsz egy TimTim.Live fizetési linket, amelyet megnyitsz a vevőnek; az eladást közvetlenül a cégednek írjuk jóvá. A tesztkulcsokkal már most kipróbálhatod. Az éles használathoz TimTim.Live ellenőrzés és bekapcsolt kártyás fizetés kell.

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

Kártyához kötött ajánlatok (bankok és hűségprogramok)

A GET /v1/offers minden jutalmat fizető eseményt ajánlatként ad meg: a szervezőt, a vásárlási napokat, az árat, a helyet és a jutalmat. Az ügyfeled a követett linkeden keresztül aktiválja, a jutalmat pedig a /v1/earnings útján fizetjük a cégednek. A tesztkulcsok mintaajánlatokat látnak. A valódi ajánlatokhoz TimTim.Live ellenőrzés kell. A kártyás fizetések közvetlen párosításához megállapodás kell egy kártyahálózattal vagy bankkal, és ez nincs bekötve.

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

Eseményállapot és jegyek

A status értéke scheduled, postponed, rescheduled, cancelled, sold_out vagy completed. A tickets.availability értéke available, limited, sold_out, not_on_sale vagy ended. Ha egy eseményt lemondanak, vedd le.

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

Milyen gyorsan kérdezhetsz

Tesztkulcsok: percenként 60 kérés. Éles kulcsok: percenként 120. Ha gyorsabb vagy, 429-es választ kapsz Retry-After értékkel, ami megmondja, hány másodpercet várj.

Milyen eseményeket kapsz

Olyan eseményeket, amelyeket TimTim.Live szervezők hoznak létre és megosztanak. A más jegyoldalakról átvett események soha nincsenek benne, mert nincs jogunk megosztani őket.

Amit soha nem küldünk el

Vevők nevét, e-mail-címét, lakcímét, telefonszámát és kártyaadatait. A Partner API eseményadatokat oszt meg, nem a tagjainkat.

Weboldal-widget

Egy sor HTML bármelyik weboldalon megmutatja az eseményeket. Használj weboldalkulcsot (tt_pk_live_), és add hozzá a weboldaladat a kulcs engedélyezett listájához. Kulcs nélkül mintaeseményeket mutat.

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

Beállítások: data-city, data-country, data-category, data-limit (1–24), data-earn="true", data-lang és data-color.

OAuth 2.0 (nagy integrációk)

Nem kötelező. Hozz létre egy OAuth-klienst az irányítópultodon. Utána cseréld be a kliensazonosítóját és a titkát egy egyórás hozzáférési tokenre, és kulcs helyett ezt a tokent küldd. A titok soha nem utazik az API-hívásaiddal, és kevesebb jogosultságot (scopes) is kérhetsz, mint amennyi a kliensnek van.

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

Ha korábban le akarsz zárni egy tokent, küldd el POST-tal a /v1/oauth/revoke címre ugyanazzal a kliensazonosítóval és titokkal. Ha kikapcsolod a klienst az irányítópultodon, az összes tokenje egyszerre megszűnik.

Zárolj egy kulcsot a szervereidre

Nem kötelező. Az irányítópultodon nyisd meg a „Zárolás a szervereimre” részt egy szerverkulcs, tesztkulcs vagy OAuth-kliens alatt, és írd be a szervereid nyilvános címeit. A máshonnan jövő hívásokat — és token-kéréseket — ip_not_allowed hibával elutasítjuk, még a helyes kulccsal is.

Kliens-tanúsítványok (mTLS): kösd a TLS kliens-tanúsítványodat egy kulcshoz, majd azzal hívd a https://api.timtim.live címet. Minden hívásnak meg kell mutatnia ezt a tanúsítványt; a TLS-kézfogás bizonyítja, hogy nálad van a privát kulcsa.

# 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-bővítmény

WordPresst használsz? Telepítsd a TimTim.Live Events bővítményt: egy blokk és egy rövidkód, amelyek a saját TimTim.Live jegylinkjeiddel mutatják az eseményeket. A TimTim.Live készítette, csak a timtim.live-val beszél, és csak a timtim.live-ról frissül.

Töltsd fel a fájlt itt: Bővítmények → Új hozzáadása → Bővítmény feltöltése. Illeszd be a weboldalkulcsodat itt: Beállítások → TimTim.Live Events, és nyomd meg a Test Connection gombot. Utána add hozzá a TimTim.Live Events blokkot bármelyik oldalhoz.

A WordPress-bővítmény letöltése

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

Feedek

Ugyanazok az események JSON Feed, RSS, XML, CSV formában vagy naptárként (.ics), amelyre a Google Calendar, az Apple Calendar és az Outlook fel tud iratkozni. A feedolvasók nem tudnak fejlécet küldeni, ezért a weboldalkulcsot vagy a tesztkulcsot a ?key= részbe tedd. Szerverkulcsot soha ne tegyél linkbe.

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

Webhookok

Az irányítópulton nyomd meg a „Cím hozzáadása” gombot, és ha valami változik, üzenetet küldünk arra a címre: event.changed vagy earnings.changed. A webhookok nem kötelezők — a changed_since ugyanezt az információt adja.

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

Ellenőrizz minden üzenetet: a titkos kulcsoddal van aláírva. Utasíts el mindent, ami öt percnél régebbi, és hagyd figyelmen kívül azt a TimTim-Delivery-Id-t, amit már feldolgoztál.

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

Válaszolj bármilyen 2xx kóddal 10 másodpercen belül. Ha nem, újra próbáljuk 1 perc, 5 perc, 30 perc, majd 2, 6, 12 és 24 óra múlva, aztán abbahagyjuk. Átirányítást soha nem követünk.

A sandbox

A tesztkulcsok TESZTESEMÉNY — NEM VALÓDI PÉNZ jelölésű mintaeseményeket kapnak. Nyiss meg egy buy_url-t, nyomd meg a Tesztjegy vásárlása gombot, majd kérd le a bevételeidet. Próbálj ki egy visszatérítést, és nézd meg, ahogy visszavonódik.

Ha valami nem sikerül

A hibák egyszerű szavakkal magyarázzák el magukat, címmel és a következő lépéssel. Minden válaszban van TimTim-Request-Id. Küldd el nekünk, és megtaláljuk a kérésedet.

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.

A szerződés

Minden mező teljes leírása OpenAPI formátumban, amit az eszközeid be tudnak olvasni.

openapi.yaml letöltése

Hogyan nyílnak meg az éles kulcsok

A tesztkulcsod azonnal működik. Az éles kulcsoknál a TimTim.Live egyik munkatársa megnézi a céged nevét, a weboldaladat és azt, hogyan mutatod majd az eseményeket. A választ az irányítópultodon látod.

TimTim.Live API frissítések

Az 1-es verzió csak bővül. Új dolgokat adunk hozzá. Ami már ott van, azt nem vesszük el és nem nevezzük át.

2026-10-08 — Az eseményválaszokban mostantól ETag is van. Küldd vissza az If-None-Match fejlécben, és gyors 304-et kapsz, ha semmi sem változott. Nem kötelező.
2026-10-08 — A webhelykulcsok mostantól minden látogatót külön számolnak, így a forgalmas oldalak is működnek tovább. Nincs teendőd.
2026-10-07 — Az ügyféltanúsítványok (mTLS) elérhetők: kösd a tanúsítványodat egy kulcshoz az irányítópultodon. Nem kötelező. Nincs teendőd.
2026-10-07 — Tömeges feedek: minden esemény, amit megmutathatsz, egy fájlban, a GET /v1/bulk címen. Nem kötelező. Nincs teendőd.
2026-10-07 — Az API-nak saját címe van: https://api.timtim.live/v1. A(z) https://timtim.live/v1 továbbra is működik. Nincs teendő.
2026-10-06 — Saját márkás fizetési oldalad a timtim.live/checkout címen. Nem kötelező. Nincs teendőd.
2026-10-06 — Jegyeladás a saját alkalmazásodban: GET /v1/events/EVENT_ID/tickets és POST /v1/orders. Nem kötelező. Nincs teendőd.
2026-10-06 — Nyilvános állapotoldal a /partners/status címen, minden percben ellenőrizve. Nincs teendőd.
2026-10-06 — Havi kimutatások cégeknek: GET /v1/settlements. Nincs teendőd.
2026-10-06 — Postbackek: tedd a ?sub_id= részt egy vásárlási linkhez, és az eladással együtt visszaküldjük neked. Nem kötelező. Nincs teendőd.
2026-10-06 — Kártyához kötött ajánlatok bankoknak és hűségprogramoknak: GET /v1/offers. Nem kötelező. Nincs teendőd.
2026-10-06 — Naptár-feed: /v1/feeds/events.ics a Google Calendar, az Apple Calendar és az Outlook számára. Semmit sem kell tenned.
2026-10-06 — Zárolj egy kulcsot a szervereidre: IP-engedélylisták már most, kliens-tanúsítványok (mTLS) az api.timtim.live címen. Nem kötelező. Semmit sem kell tenned.
2026-10-06 — OAuth 2.0 client credentials nagy integrációkhoz: POST /v1/oauth/token és /v1/oauth/revoke. A kulcsok továbbra is működnek. Nincs teendőd.
2026-10-06 — WordPress-bővítmény 1.0.0: egy blokk, egy rövidkód és egy beállítási oldal. Magától frissül a timtim.live-ról. Nincs teendőd.
2026-10-06 — Weboldal-widget, JSON/RSS/XML/CSV feedek és webhookok (event.changed, earnings.changed). Nincs teendőd.
2026-10-06 — Partner API v1: események, egy esemény, bevételek és a sandbox. Nincs teendőd.