Partner API — rychlý start

Vaše první napojení se vejde na jednu obrazovku.

Vyzkoušejte to hned — bez klíče, bez registrace

Otevřete tuto adresu v prohlížeči. Hned uvidíte ukázkové akce.

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

1
Získejte testovací klíč
Přihlaste se, řekněte nám, kdo jste, a stiskněte „Vytvořit testovací klíč“. Začíná na tt_test_ a vidí jen ukázkové akce.

Najděte akce

Zeptejte se na akce ve městě.

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

3
Ukažte akci
Každá akce má název, datum, místo, obrázek, cenu a hotové popisky pro vaši kartu.
4
Použijte buy_url
Použijte buy_url, který vám dáme. To je vše. TimTim.Live si v tom odkazu sám zapíše, že kupující přišel od vás.
5
Podívejte se na výsledky
Uvidíte, kolik lidí jste poslali, kolik vstupenek se prodalo a kolik jste vydělali — v přehledu nebo dotazem.
GET https://api.timtim.live/v1/earnings

Získat testovací klíč Vyzkoušet bez klíče

Stav TimTim.Live

Technický popis

Kam posílat dotazy

https://api.timtim.live/v1

Váš klíč pro připojení

Posílejte klíč v hlavičce Authorization. Testovací klíče (tt_test_) vidí jen ukázkové akce. Klíče pro web (tt_pk_live_) mohou být na webové stránce a jen čtou akce. Serverové klíče (tt_sk_live_) zůstávají na vašem serveru a umí číst i výdělky. Klíč ukážeme jen jednou — dobře si ho schovejte.

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

Filtry

city: Akce v tomto městě.
country: Dvoupísmenný kód země, například US.
category: Například music, festival nebo conference.
from: Akce v tento den nebo později (2026-10-20).
to: Akce v tento den nebo dříve.
changed_since: Jen akce, které se změnily po tomto čase.
commissioned: true = jen akce, které platí odměnu.
minimum_earnings: Jen akce, které platí aspoň tolik za vstupenku.
near: Místo, například near=Paris,FR.
limit: Kolik akcí na stránku, 1 až 100 (20, když nic nezadáte).

Řekněte mi jen, co se změnilo

Uložte si čas poslední synchronizace a pošlete ho jako changed_since. Dostanete jen akce, které se změnily — včetně zrušených a vyprodaných. Webhook není potřeba. Akce, které už nesmíte zobrazovat, přijdou v seznamu withdrawn.

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

Víc než jedna stránka

Pokud odpověď obsahuje next, pošlete ho zpět jako cursor= a dostanete další stránku. Když je next prázdný, máte všechno.

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

Výdělek

Každá akce má earn. Pokud je earn.eligible false, akce nemá odměnu — pořád stojí za to ji ukázat. Pokud je true, earn.description řekne, co dostanete, například „$5 za každou oprávněnou vstupenku“. Pokud se za nákup vrátí peníze, odměna se odečte zpět.

Hromadné kanály (vše v jednom souboru)

Uložte si hromadný kanál ve svém přehledu a pak stáhněte všechny jeho akce v jednom komprimovaném souboru: GET /v1/bulk/FEED_ID.ndjson.gz nebo .csv.gz, se svým serverovým klíčem. Přidejte ?changed_since= jen pro změny, včetně stažených akcí. Testovací klíče to mohou vyzkoušet už teď; ostré použití vyžaduje kontrolu od TimTim.Live.

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

Prodávejte vstupenky ve vlastní aplikaci (vestavěný prodej)

Velcí partneři mohou nechat kupující ve své aplikaci. Zeptejte se GET /v1/events/EVENT_ID/tickets, co je v prodeji, a pak pošlete POST /v1/orders s volbou kupujícího. Dostanete platební odkaz TimTim.Live, který kupujícímu otevřete; prodej se připíše přímo vaší firmě. Testovací klíče to mohou zkusit hned. Skutečné použití potřebuje kontrolu od TimTim.Live a zapnuté platby kartou.

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

Nabídky propojené s kartou (banky a věrnostní programy)

GET /v1/offers dává každou akci, která vyplácí odměnu, jako nabídku: pořadatele, data, kdy lze nakoupit, cenu, místo a odměnu. Váš zákazník ji aktivuje přes váš sledovaný odkaz a odměna se vaší firmě vyplatí přes /v1/earnings. Testovací klíče vidí ukázkové nabídky. Skutečné nabídky potřebují kontrolu od TimTim.Live. Přímé párování plateb kartou potřebuje dohodu s karetní sítí nebo bankou a není zapojené.

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

Stav akce a vstupenky

status je scheduled, postponed, rescheduled, cancelled, sold_out nebo completed. tickets.availability je available, limited, sold_out, not_on_sale nebo ended. Když je akce zrušená, stáhněte ji.

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

Jak rychle se můžete ptát

Testovací klíče: 60 dotazů za minutu. Ostré klíče: 120 za minutu. Když budete rychlejší, dostanete odpověď 429 s Retry-After, tedy počtem sekund, kolik počkat.

Které akce dostanete

Akce, které vytvoří pořadatelé TimTim.Live a rozhodnou se je sdílet. Akce převzaté z jiných vstupenkových webů nikdy nejsou zahrnuty, protože nemáme právo je sdílet.

Co nikdy neposíláme

Jména kupujících, e-mailové adresy, adresy bydliště, telefonní čísla a údaje karet. Partner API sdílí informace o akcích, ne o našich členech.

Widget pro web

Jeden řádek HTML ukáže akce na jakémkoli webu. Použijte klíč pro web (tt_pk_live_) a přidejte svůj web do seznamu povolených webů klíče. Bez klíče ukazuje ukázkové akce.

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

Možnosti: data-city, data-country, data-category, data-limit (1–24), data-earn="true", data-lang a data-color.

OAuth 2.0 (velké integrace)

Volitelné. Vytvořte OAuth klienta v přehledu. Pak vyměňte jeho ID klienta a tajný klíč za přístupový token na jednu hodinu a posílejte tento token místo klíče. Tajný klíč nikdy necestuje s vašimi voláními API a můžete požádat o méně oprávnění (scopes), než má klient.

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

Chcete-li token ukončit dřív, pošlete ho přes POST na /v1/oauth/revoke se stejným ID klienta a tajným klíčem. Když klienta v přehledu vypnete, skončí všechny jeho tokeny najednou.

Zamkněte klíč na své servery

Volitelné. Ve svém přehledu otevřete „Zamknout na mé servery“ u serverového klíče, testovacího klíče nebo OAuth klienta a zapište veřejné adresy svých serverů. Volání — i žádosti o token — odjinud odmítneme s ip_not_allowed, i se správným klíčem.

Klientské certifikáty (mTLS): připojte svůj klientský certifikát TLS ke klíči a pak s ním volejte https://api.timtim.live. Každé volání musí ten certifikát ukázat; TLS handshake dokazuje, že máte jeho soukromý klíč.

# 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 pro WordPress

Používáte WordPress? Nainstalujte TimTim.Live Events: blok a shortcode, které ukazují akce s vašimi vlastními odkazy na vstupenky TimTim.Live. Dělá ho TimTim.Live, mluví jen s timtim.live a aktualizuje se jen z timtim.live.

Nahrajte soubor v Pluginy → Instalace pluginů → Nahrát plugin. Vložte svůj klíč pro web do Nastavení → TimTim.Live Events a klikněte na Test Connection. Pak přidejte blok TimTim.Live Events na jakoukoli stránku.

Stáhnout plugin pro WordPress

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

Datové kanály

Stejné akce jako JSON Feed, RSS, XML, CSV nebo kalendář (.ics), který můžete odebírat v Google Calendar, Apple Calendar a Outlook. Čtečky kanálů neumí posílat hlavičky, proto dejte klíč pro web nebo testovací klíč do ?key=. Nikdy nedávejte serverový klíč do odkazu.

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

Webhooky

Přidejte adresu na svém přehledu a my na ni pošleme zprávu, když se něco změní: event.changed nebo earnings.changed. Webhooky nejsou povinné — changed_since vám dá stejné informace.

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

Kontrolujte každou zprávu: je podepsaná vaším tajemstvím. Odmítněte vše, co je starší než pět minut, a nevšímejte si TimTim-Delivery-Id, které jste už zpracovali.

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

Odpovězte jakýmkoli 2xx do 10 sekund. Pokud ne, zkusíme to znovu po 1 minutě, 5 minutách, 30 minutách, potom po 2, 6, 12 a 24 hodinách, a pak přestaneme. Nikdy nesledujeme přesměrování.

Pískoviště

Testovací klíče dostanou ukázkové akce označené TESTOVACÍ AKCE — ŽÁDNÉ SKUTEČNÉ PENÍZE. Otevřete buy_url, stiskněte „Koupit testovací vstupenku“ a pak se zeptejte na své výdělky. Zkuste vrácení peněz a uvidíte, jak se částka odečte zpět.

Když se něco pokazí

Chyby se vysvětlí jednoduchými slovy: nadpis a co dělat dál. Každá odpověď nese TimTim-Request-Id. Pošlete nám ho a váš dotaz najdeme.

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.

Úplný popis API

Úplný popis každého pole ve formátu OpenAPI, který vaše nástroje umí přečíst.

Stáhnout openapi.yaml

Jak se otevírají ostré klíče

Váš testovací klíč funguje hned. U ostrých klíčů se člověk z TimTim.Live podívá na název vaší firmy, váš web a na to, jak budete akce ukazovat. Odpověď uvidíte ve svém přehledu.

Novinky TimTim.Live API

Verze 1 jen roste. Přidáváme nové věci. Nic, co už existuje, neodebíráme ani nepřejmenováváme.

2026-10-08 — Odpovědi s akcemi teď nesou ETag. Pošlete ho zpět v If-None-Match a když se nic nezměnilo, dostanete rychlé 304. Volitelné.
2026-10-08 — Klíče pro weby teď počítají každého návštěvníka zvlášť, takže i hodně navštěvované weby fungují dál. Nemusíte nic dělat.
2026-10-07 — Klientské certifikáty (mTLS) jsou otevřené: připněte svůj certifikát ke klíči ve svém přehledu. Volitelné. Nemusíte nic dělat.
2026-10-07 — Hromadné kanály: všechny akce, které smíte ukazovat, v jednom souboru, na GET /v1/bulk. Volitelné. Nemusíte nic dělat.
2026-10-07 — API má vlastní adresu: https://api.timtim.live/v1. https://timtim.live/v1 dál funguje. Není potřeba nic dělat.
2026-10-06 — Vlastní platební stránka s vaší značkou na timtim.live/checkout. Volitelné. Nemusíte nic dělat.
2026-10-06 — Prodej vstupenek ve vaší vlastní aplikaci: GET /v1/events/EVENT_ID/tickets a POST /v1/orders. Volitelné. Nemusíte nic dělat.
2026-10-06 — Veřejná stránka stavu na /partners/status, kontrolovaná každou minutu. Nemusíte nic dělat.
2026-10-06 — Měsíční výpisy pro firmy: GET /v1/settlements. Nemusíte nic dělat.
2026-10-06 — Postbacky: přidejte ?sub_id= k odkazu na nákup a my vám ho pošleme zpátky spolu s prodejem. Volitelné. Nemusíte nic dělat.
2026-10-06 — Nabídky propojené s kartou pro banky a věrnostní programy: GET /v1/offers. Volitelné. Nemusíte nic dělat.
2026-10-06 — Kalendářový kanál: /v1/feeds/events.ics pro Google Calendar, Apple Calendar a Outlook. Nemusíte nic dělat.
2026-10-06 — Zamkněte klíč na své servery: seznamy povolených IP už teď, klientské certifikáty (mTLS) na api.timtim.live. Volitelné. Nemusíte nic dělat.
2026-10-06 — OAuth 2.0 client credentials pro velké integrace: POST /v1/oauth/token a /v1/oauth/revoke. Klíče dál fungují. Nemusíte nic dělat.
2026-10-06 — Plugin pro WordPress 1.0.0: blok, shortcode a stránka nastavení. Sám se aktualizuje z timtim.live. Nemusíte nic dělat.
2026-10-06 — Widget pro web, datové kanály JSON/RSS/XML/CSV a webhooky (event.changed, earnings.changed). Nemusíte nic dělat.
2026-10-06 — Partner API v1: akce, jedna akce, výdělky a pískoviště. Nemusíte nic dělat.