Partner API — szybki start

Twoje pierwsze połączenie mieści się na jednym ekranie.

Wypróbuj teraz — bez klucza, bez rejestracji

Otwórz ten adres w przeglądarce. Od razu zobaczysz przykładowe wydarzenia.

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

1
Weź klucz testowy
Zaloguj się, powiedz nam, kim jesteś, i naciśnij „Utwórz klucz testowy”. Zaczyna się od tt_test_ i widzi tylko przykładowe wydarzenia.

Znajdź wydarzenia

Poproś o wydarzenia w mieście.

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

3
Pokaż wydarzenie
Każde wydarzenie ma nazwę, datę, miejsce, zdjęcie, cenę i gotowe opisy do Twojej karty.
4
Użyj buy_url
Użyj buy_url, który Ci dajemy. To wszystko. TimTim.Live sam zapisuje w tym linku, że kupujący przyszedł od Ciebie.
5
Zobacz wyniki
Zobacz, ile osób przysłałeś, ile biletów sprzedano i ile zarobiłeś — w panelu albo przez zapytanie.
GET https://api.timtim.live/v1/earnings

Weź mój klucz testowy Wypróbuj bez klucza

Status TimTim.Live

Opis techniczny

Gdzie wysyłać zapytania

https://api.timtim.live/v1

Twój klucz połączenia

Wysyłaj klucz w nagłówku Authorization. Klucze testowe (tt_test_) widzą tylko przykładowe wydarzenia. Klucze do strony (tt_pk_live_) mogą być na stronie internetowej i tylko czytają wydarzenia. Klucze serwerowe (tt_sk_live_) zostają na Twoim serwerze i mogą też czytać zarobki. Pokazujemy klucz tylko raz — chroń go.

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: Wydarzenia w tym mieście.
country: Dwuliterowy kod kraju, na przykład US.
category: Na przykład music, festival lub conference.
from: Wydarzenia w tym dniu lub później (2026-10-20).
to: Wydarzenia w tym dniu lub wcześniej.
changed_since: Tylko wydarzenia zmienione po tym czasie.
commissioned: true = tylko wydarzenia, które płacą nagrodę.
minimum_earnings: Tylko wydarzenia, które płacą co najmniej tyle za bilet.
near: Miejsce, na przykład near=Paris,FR.
limit: Ile wydarzeń na stronę, od 1 do 100 (20, jeśli nic nie podasz).

Mów mi tylko, co się zmieniło

Zapisz czas ostatniej synchronizacji i wyślij go jako changed_since. Dostaniesz tylko zmienione wydarzenia — także odwołane i wyprzedane. Webhook nie jest potrzebny. Wydarzenia, których masz już nie pokazywać, przychodzą na liście withdrawn.

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

Więcej niż jedna strona

Jeśli odpowiedź ma next, odeślij go jako cursor=, aby dostać następną stronę. Gdy next jest pusty, masz już wszystko.

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

Zarabianie

Każde wydarzenie ma earn. Jeśli earn.eligible to false, wydarzenie nie ma nagrody — nadal warto je pokazać. Jeśli true, earn.description mówi, co dostajesz, na przykład „$5 za każdy uprawniony bilet”. Jeśli zakup zostanie zwrócony, nagroda zostaje cofnięta.

Pełne kanały (wszystko w jednym pliku)

Zapisz pełny kanał w swoim panelu, a potem pobierz wszystkie jego wydarzenia w jednym skompresowanym pliku: GET /v1/bulk/FEED_ID.ndjson.gz albo .csv.gz, swoim kluczem serwerowym. Dodaj ?changed_since=, aby dostać tylko zmiany, także zdjęte wydarzenia. Klucze testowe mogą to wypróbować już teraz; prawdziwe użycie wymaga sprawdzenia przez TimTim.Live.

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

Sprzedawaj bilety we własnej aplikacji (handel wbudowany)

Duzi partnerzy mogą zatrzymać kupujących we własnej aplikacji. Zapytaj GET /v1/events/EVENT_ID/tickets, co jest w sprzedaży, a potem wyślij POST /v1/orders z wyborem kupującego. Dostajesz link do płatności TimTim.Live, który otwierasz kupującemu; sprzedaż zapisuje się bezpośrednio na twoją firmę. Klucze testowe mogą to wypróbować już teraz. Prawdziwe użycie wymaga kontroli od TimTim.Live i włączonych płatności kartą.

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

Oferty powiązane z kartą (banki i programy nagród)

GET /v1/offers podaje każde wydarzenie, które wypłaca nagrodę, jako ofertę: organizatora, daty, kiedy można kupić, cenę, miejsce i nagrodę. Twój klient aktywuje ją przez twój śledzony link, a nagroda trafia do twojej firmy przez /v1/earnings. Klucze testowe widzą przykładowe oferty. Prawdziwe oferty wymagają sprawdzenia przez TimTim.Live. Bezpośrednie dopasowanie płatności kartą wymaga umowy z siecią kart albo bankiem i nie jest podłączone.

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

Stan wydarzenia i bilety

status to scheduled, postponed, rescheduled, cancelled, sold_out lub completed. tickets.availability to available, limited, sold_out, not_on_sale lub ended. Gdy wydarzenie jest odwołane, usuń je.

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

Jak często możesz pytać

Klucze testowe: 60 zapytań na minutę. Klucze produkcyjne: 120 na minutę. Szybciej dostaniesz odpowiedź 429 z Retry-After, czyli liczbą sekund do odczekania.

Jakie wydarzenia dostajesz

Wydarzenia, które tworzą organizatorzy TimTim.Live i chcą udostępnić. Wydarzenia pobrane z innych stron z biletami nigdy nie są dołączane, bo nie mamy prawa ich udostępniać.

Czego nigdy nie wysyłamy

Imion kupujących, adresów e-mail, adresów domowych, numerów telefonów i danych kart. Partner API udostępnia informacje o wydarzeniach, a nie o naszych członkach.

Widżet na stronę

Jedna linijka HTML pokazuje wydarzenia na każdej stronie. Użyj klucza do strony (tt_pk_live_) i dodaj swoją stronę do listy stron dozwolonych dla klucza. Bez klucza widżet pokazuje przykładowe wydarzenia.

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

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

OAuth 2.0 (duże integracje)

Opcjonalne. Utwórz klienta OAuth w panelu. Potem wymień jego identyfikator klienta i sekret na token dostępu ważny godzinę i wysyłaj ten token zamiast klucza. Sekret nigdy nie podróżuje z twoimi wywołaniami API, a możesz poprosić o mniej uprawnień (scopes), niż ma 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"

Aby zakończyć token wcześniej, wyślij go przez POST do /v1/oauth/revoke z tym samym identyfikatorem klienta i sekretem. Wyłączenie klienta w panelu kończy od razu wszystkie jego tokeny.

Zablokuj klucz na swoje serwery

Opcjonalne. W swoim panelu otwórz „Zablokuj na moje serwery” pod kluczem serwerowym, kluczem testowym lub klientem OAuth i wpisz publiczne adresy swoich serwerów. Wywołania — i prośby o token — z każdego innego miejsca są odrzucane z kodem ip_not_allowed, nawet z właściwym kluczem.

Certyfikaty klienta (mTLS): przypisz swój certyfikat klienta TLS do klucza, a potem wywołuj z nim https://api.timtim.live. Każde wywołanie musi pokazać ten certyfikat; uzgadnianie TLS dowodzi, że masz jego klucz prywatny.

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

Wtyczka WordPress

Masz WordPress? Zainstaluj TimTim.Live Events: blok i shortcode, które pokazują wydarzenia z twoimi własnymi linkami do biletów TimTim.Live. Robi ją TimTim.Live, łączy się tylko z timtim.live i aktualizuje się tylko z timtim.live.

Wyślij plik w Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer. Wklej klucz do strony w Ustawienia → TimTim.Live Events i kliknij Test Connection. Potem dodaj blok TimTim.Live Events do dowolnej strony.

Pobierz wtyczkę WordPress

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

Kanały danych

Te same wydarzenia jako JSON Feed, RSS, XML, CSV lub kalendarz (.ics), który można subskrybować w Google Calendar, Apple Calendar i Outlook. Czytniki kanałów nie umieją wysyłać nagłówków, więc wpisz klucz do strony lub klucz testowy w ?key=. Nigdy nie wpisuj klucza serwerowego do linku.

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

Webhooki

Dodaj adres w swoim panelu, a my wyślemy na niego wiadomość, gdy coś się zmieni: event.changed lub earnings.changed. Webhooki nie są obowiązkowe — changed_since daje te same informacje.

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

Sprawdzaj każdą wiadomość: jest podpisana Twoim sekretem. Odrzucaj wszystko, co ma więcej niż pięć minut, i pomijaj TimTim-Delivery-Id, który już obsłużyłeś.

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

Odpowiedz dowolnym kodem 2xx w ciągu 10 sekund. Jeśli nie, spróbujemy znowu po 1 minucie, 5 minutach, 30 minutach, potem po 2, 6, 12 i 24 godzinach, a potem przestaniemy. Nigdy nie idziemy za przekierowaniami.

Piaskownica

Klucze testowe dostają przykładowe wydarzenia oznaczone WYDARZENIE TESTOWE — BEZ PRAWDZIWYCH PIENIĘDZY. Otwórz buy_url, naciśnij „Kup bilet testowy”, a potem poproś o swoje zarobki. Udawaj zwrot i zobacz, jak kwota zostaje cofnięta.

Gdy coś pójdzie nie tak

Błędy tłumaczą się prostymi słowami: tytuł i co zrobić dalej. Każda odpowiedź ma TimTim-Request-Id. Wyślij go nam, a znajdziemy Twoje zapytanie.

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.

Pełny opis API

Pełny opis każdego pola w formacie OpenAPI, który rozumieją Twoje narzędzia.

Pobierz openapi.yaml

Jak dostać klucze live

Twój klucz testowy działa od razu. Przy kluczach live osoba z TimTim.Live sprawdza nazwę Twojej firmy, Twoją stronę i to, jak pokażesz wydarzenia. Odpowiedź zobaczysz w swoim panelu.

Nowości w TimTim.Live API

Wersja 1 tylko rośnie. Dodajemy nowe rzeczy. Nie usuwamy ani nie zmieniamy nazw tego, co już jest.

2026-10-08 — Odpowiedzi o wydarzeniach mają teraz ETag. Odeślij go w If-None-Match, a dostaniesz szybkie 304, gdy nic się nie zmieniło. Opcjonalne.
2026-10-08 — Klucze witryn liczą teraz każdego odwiedzającego osobno, więc popularne strony dalej działają. Nic nie trzeba robić.
2026-10-07 — Certyfikaty klienta (mTLS) są już dostępne: przypnij swój certyfikat do klucza w swoim panelu. Opcjonalne. Nic nie trzeba robić.
2026-10-07 — Pełne kanały: każde wydarzenie, które możesz pokazać, w jednym pliku, pod GET /v1/bulk. Opcjonalne. Nic nie trzeba robić.
2026-10-07 — API ma własny adres: https://api.timtim.live/v1. https://timtim.live/v1 nadal działa. Nic nie trzeba robić.
2026-10-06 — Twoja własna strona płatności z Twoją marką pod timtim.live/checkout. Opcjonalne. Nic nie trzeba robić.
2026-10-06 — Sprzedawaj bilety w swojej aplikacji: GET /v1/events/EVENT_ID/tickets i POST /v1/orders. Opcjonalne. Nic nie trzeba robić.
2026-10-06 — Publiczna strona statusu pod /partners/status, sprawdzana co minutę. Nic nie trzeba robić.
2026-10-06 — Miesięczne zestawienia dla firm: GET /v1/settlements. Nic nie trzeba robić.
2026-10-06 — Postbacki: dodaj ?sub_id= do linku zakupu, a odeślemy go do Ciebie razem ze sprzedażą. Opcjonalne. Nic nie trzeba robić.
2026-10-06 — Oferty powiązane z kartą dla banków i programów nagród: GET /v1/offers. Opcjonalne. Nic nie trzeba robić.
2026-10-06 — Kanał kalendarza: /v1/feeds/events.ics dla Google Calendar, Apple Calendar i Outlook. Nic nie musisz robić.
2026-10-06 — Zablokuj klucz na swoje serwery: listy dozwolonych IP już teraz, certyfikaty klienta (mTLS) na api.timtim.live. Opcjonalne. Nic nie musisz robić.
2026-10-06 — OAuth 2.0 client credentials dla dużych integracji: POST /v1/oauth/token i /v1/oauth/revoke. Klucze dalej działają. Nic nie musisz robić.
2026-10-06 — Wtyczka WordPress 1.0.0: blok, shortcode i strona ustawień. Sama aktualizuje się z timtim.live. Nic nie musisz robić.
2026-10-06 — Widżet na stronę, kanały danych JSON/RSS/XML/CSV i webhooki (event.changed, earnings.changed). Nic nie musisz robić.
2026-10-06 — Partner API v1: wydarzenia, jedno wydarzenie, zarobki i piaskownica. Nic nie musisz robić.