Partner API — Pikaopas

Ensimmäinen integraatiosi mahtuu yhdelle näytölle.

Kokeile heti — ei avainta, ei rekisteröitymistä

Avaa tämä osoite selaimessasi. Näet esimerkkitapahtumia heti.

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

1
Hae testiavain
Kirjaudu sisään, kerro kuka olet ja paina Luo testiavain. Se alkaa tt_test_ ja näkee vain esimerkkitapahtumat.

Etsi tapahtumia

Pyydä tapahtumia jostain kaupungista.

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

3
Näytä tapahtuma
Jokaisella tapahtumalla on nimi, päivä, paikka, kuva, hinta ja valmiit tekstit korttiisi.
4
Käytä buy_url-osoitetta
Käytä buy_url-osoitetta, jonka annamme. Siinä kaikki. TimTim.Live kirjaa linkin sisällä, mistä myynti tuli.
5
Katso tulokset
Näe lähettämäsi ihmiset, myydyt liput ja ansiot näkymässäsi, tai pyydä ne.
GET https://api.timtim.live/v1/earnings

Hae testiavaimeni Kokeile ilman avainta

TimTim.Live-palvelun tila

Viite

Minne pyynnöt lähetetään

https://api.timtim.live/v1

Yhteysavaimesi

Lähetä avaimesi Authorization-otsakkeessa. Testiavaimet (tt_test_) näkevät vain esimerkkitapahtumat. Sivustoavaimet (tt_pk_live_) voivat olla verkkosivulla ja lukevat vain tapahtumia. Palvelinavaimet (tt_sk_live_) pysyvät palvelimellasi ja voivat lukea myös ansiot. Näytämme avaimen vain kerran — pidä se tallessa.

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

Suodattimet

city: Tapahtumat tässä kaupungissa.
country: Kaksikirjaiminen maakoodi, esimerkiksi US.
category: Esimerkiksi musiikki, festivaali tai konferenssi.
from: Tapahtumat tänä päivänä tai sen jälkeen (2026-10-20).
to: Tapahtumat tänä päivänä tai sitä ennen.
changed_since: Vain tapahtumat, jotka ovat muuttuneet tämän ajan jälkeen.
commissioned: true = vain tapahtumat, joista saa palkkion.
minimum_earnings: Vain tapahtumat, jotka maksavat vähintään näin paljon lippua kohti.
near: Paikka, esimerkiksi near=Paris,FR.
limit: Montako tapahtumaa sivulla, 1–100 (20, jos jätät tyhjäksi).

Kerro vain, mikä muuttui

Tallenna viimeisimmän synkronoinnin aika ja lähetä se arvona changed_since. Saat vain muuttuneet tapahtumat — myös perutut ja loppuunmyydyt. Webhookia ei tarvita. Tapahtumat, joita et saa enää näyttää, tulevat withdrawn-listassa.

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

Useampi kuin yksi sivu

Jos vastauksessa on next, lähetä se takaisin muodossa cursor= saadaksesi seuraavan sivun. Kun next on tyhjä, sinulla on kaikki.

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

Ansainta

Jokaisella tapahtumalla on earn. Jos earn.eligible on false, tapahtumassa ei ole palkkiota — se kannattaa silti näyttää. Jos se on true, earn.description kertoo, mitä saat, esimerkiksi ”$5 jokaisesta ehdot täyttävästä lipusta”. Jos osto palautetaan, palkkio perutaan.

Massasyötteet (kaikki yhdessä tiedostossa)

Tallenna massasyöte näkymääsi ja lataa sitten kaikki sen tapahtumat yhtenä pakattuna tiedostona: GET /v1/bulk/FEED_ID.ndjson.gz tai .csv.gz, palvelinavaimellasi. Lisää ?changed_since= saadaksesi vain muutokset, myös poistetut tapahtumat. Testiavaimet voivat kokeilla sitä jo nyt; oikea käyttö vaatii TimTim.Liven tarkistuksen.

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

Myy lippuja omassa sovelluksessasi (upotettu kauppa)

Suuret kumppanit voivat pitää ostajat omassa sovelluksessaan. Kysy GET /v1/events/EVENT_ID/tickets, mitä on myynnissä, ja lähetä sitten POST /v1/orders ostajan valinnalla. Saat TimTim.Live-maksulinkin, jonka avaat ostajalle; myynti hyvitetään suoraan yrityksellesi. Testiavaimilla voi kokeilla jo nyt. Oikea käyttö vaatii TimTim.Liven tarkistuksen ja korttimaksujen käyttöönoton.

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

Korttiin liitetyt tarjoukset (pankit ja etuohjelmat)

GET /v1/offers antaa jokaisen palkkion maksavan tapahtuman tarjouksena: järjestäjän, päivät, joina voi ostaa, hinnan, paikan ja palkkion. Asiakkaasi aktivoi sen seuratun linkkisi kautta, ja palkkio maksetaan yrityksellesi /v1/earnings-rajapinnan kautta. Testiavaimet näkevät esimerkkitarjouksia. Oikeat tarjoukset tarvitsevat TimTim.Liven tarkistuksen. Korttimaksujen suora yhdistäminen vaatii sopimuksen korttiverkon tai pankin kanssa, eikä sitä ole kytketty.

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

Tapahtuman tila ja liput

status on scheduled, postponed, rescheduled, cancelled, sold_out tai completed. tickets.availability on available, limited, sold_out, not_on_sale tai ended. Kun tapahtuma perutaan, poista se.

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

Kuinka nopeasti voit kysyä

Testiavaimet: 60 pyyntöä minuutissa. Live-avaimet: 120 minuutissa. Jos kysyt nopeammin, saat vastauksen 429 ja Retry-After-arvon, joka kertoo, montako sekuntia odottaa.

Mitkä tapahtumat saat

Tapahtumat, jotka TimTim.Liven järjestäjät luovat ja päättävät jakaa. Muilta lippusivustoilta tuotuja tapahtumia ei koskaan ole mukana, koska meillä ei ole oikeutta jakaa niitä.

Mitä emme koskaan lähetä

Ostajien nimiä, sähköpostiosoitteita, kotiosoitteita, puhelinnumeroita tai korttitietoja. Partner API jakaa tietoa tapahtumista, ei jäsenistämme.

Sivustowidget

Yksi HTML-rivi näyttää tapahtumat millä tahansa sivustolla. Käytä sivustoavainta (tt_pk_live_) ja lisää sivustosi avaimen sallittujen sivustojen listaan. Ilman avainta se näyttää esimerkkitapahtumia.

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

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

OAuth 2.0 (suuret integraatiot)

Valinnainen. Luo OAuth-asiakas näkymässäsi. Vaihda sitten sen asiakastunnus ja salaisuus tunnin käyttötunnisteeseen, ja lähetä se tunniste avaimen sijaan. Salaisuus ei koskaan kulje API-kutsujesi mukana, ja voit pyytää vähemmän oikeuksia (scopes) kuin asiakkaalla on.

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

Jos haluat lopettaa tunnisteen aiemmin, lähetä se POST-pyynnöllä osoitteeseen /v1/oauth/revoke samalla asiakastunnuksella ja salaisuudella. Kun suljet asiakkaan näkymässäsi, kaikki sen tunnisteet loppuvat kerralla.

Lukitse avain palvelimiisi

Valinnainen. Avaa näkymässäsi "Lukitse palvelimiini" palvelinavaimen, testiavaimen tai OAuth-asiakkaan alla ja kirjoita palvelimiesi julkiset osoitteet. Kutsut — ja token-pyynnöt — kaikkialta muualta hylätään koodilla ip_not_allowed, vaikka avain olisi oikea.

Asiakasvarmenteet (mTLS): liitä TLS-asiakasvarmenteesi avaimeen ja kutsu sitten https://api.timtim.live sen kanssa. Jokaisen kutsun on näytettävä se varmenne; TLS-kättely todistaa, että sinulla on sen yksityinen avain.

# 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-lisäosa

Käytätkö WordPressiä? Asenna TimTim.Live Events: lohko ja lyhytkoodi, jotka näyttävät tapahtumat omilla TimTim.Live-lippulinkeilläsi. Sen tekee TimTim.Live, se puhuu vain timtim.live-sivuston kanssa ja päivittyy vain timtim.live-sivustolta.

Lataa tiedosto kohdassa Lisäosat → Lisää uusi → Lataa lisäosa. Liitä sivustoavaimesi kohtaan Asetukset → TimTim.Live Events ja paina Test Connection. Lisää sitten TimTim.Live Events -lohko mille tahansa sivulle.

Lataa WordPress-lisäosa

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

Syötteet

Samat tapahtumat muodoissa JSON Feed, RSS, XML, CSV tai kalenterina (.ics), jonka Google Calendar, Apple Calendar ja Outlook voivat tilata. Syötteenlukijat eivät voi lähettää otsakkeita, joten laita sivustoavain tai testiavain kohtaan ?key=. Älä koskaan laita palvelinavainta linkkiin.

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

Webhookit

Lisää osoite omaan näkymääsi, niin lähetämme sinne viestin, kun jokin muuttuu: event.changed tai earnings.changed. Webhookit ovat vapaaehtoisia — changed_since antaa samat tiedot.

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

Tarkista jokainen viesti: se on allekirjoitettu salaisuudellasi. Hylkää kaikki yli viisi minuuttia vanhat viestit, ja ohita TimTim-Delivery-Id, jonka olet jo käsitellyt.

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

Vastaa millä tahansa 2xx-koodilla 10 sekunnin sisällä. Muuten yritämme uudelleen 1 minuutin, 5 minuutin ja 30 minuutin päästä, sitten 2, 6, 12 ja 24 tunnin päästä, ja sitten lopetamme. Emme koskaan seuraa uudelleenohjauksia.

Hiekkalaatikko

Testiavaimet saavat esimerkkitapahtumia, joissa on merkintä TESTITAPAHTUMA — EI OIKEAA RAHAA. Avaa buy_url, paina Osta testilippu ja pyydä sitten ansiosi. Kokeile palautusta ja katso, kun se perutaan.

Kun jokin menee pieleen

Virheet kertovat itsestään selkein sanoin: otsikko ja mitä tehdä seuraavaksi. Jokaisessa vastauksessa on TimTim-Request-Id. Lähetä se meille, niin löydämme pyyntösi.

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.

Sopimus

Jokaisen kentän täysi kuvaus OpenAPI-muodossa, jota työkalusi osaavat lukea.

Lataa openapi.yaml

Miten oikeat avaimet avautuvat

Testiavaimesi toimii heti. Oikeita avaimia varten ihminen TimTim.Live-tiimistä katsoo yrityksesi nimen, verkkosivustosi ja sen, miten aiot näyttää tapahtumia. Näet vastauksen näkymässäsi.

TimTim.Liven API-päivitykset

Versio 1 vain kasvaa. Lisäämme uusia asioita. Emme poista emmekä nimeä uudelleen sitä, mikä on jo olemassa.

2026-10-08 — Tapahtumavastauksissa on nyt ETag. Lähetä se takaisin If-None-Match-otsakkeessa, niin saat nopean 304:n, kun mikään ei ole muuttunut. Valinnainen.
2026-10-08 — Verkkosivuavaimet laskevat nyt jokaisen kävijän erikseen, joten vilkkaat sivustot toimivat edelleen. Sinun ei tarvitse tehdä mitään.
2026-10-07 — Asiakasvarmenteet (mTLS) ovat auki: liitä varmenteesi avaimeen näkymässäsi. Valinnainen. Sinun ei tarvitse tehdä mitään.
2026-10-07 — Massasyötteet: jokainen tapahtuma, jonka saat näyttää, yhdessä tiedostossa, osoitteessa GET /v1/bulk. Valinnainen. Sinun ei tarvitse tehdä mitään.
2026-10-07 — API:lla on oma osoite: https://api.timtim.live/v1. https://timtim.live/v1 toimii edelleen. Toimenpiteitä ei tarvita.
2026-10-06 — Oma maksusivu omalla brändilläsi osoitteessa timtim.live/checkout. Valinnainen. Sinun ei tarvitse tehdä mitään.
2026-10-06 — Myy lippuja omassa sovelluksessasi: GET /v1/events/EVENT_ID/tickets ja POST /v1/orders. Valinnainen. Sinun ei tarvitse tehdä mitään.
2026-10-06 — Julkinen tilasivu osoitteessa /partners/status, tarkistetaan joka minuutti. Sinun ei tarvitse tehdä mitään.
2026-10-06 — Kuukausittaiset tiliotteet yrityksille: GET /v1/settlements. Sinun ei tarvitse tehdä mitään.
2026-10-06 — Postbackit: lisää ?sub_id= ostolinkkiin, niin lähetämme sen sinulle takaisin myynnin kanssa. Valinnainen. Sinun ei tarvitse tehdä mitään.
2026-10-06 — Korttiin liitetyt tarjoukset pankeille ja etuohjelmille: GET /v1/offers. Valinnainen. Sinun ei tarvitse tehdä mitään.
2026-10-06 — Kalenterisyöte: /v1/feeds/events.ics palveluille Google Calendar, Apple Calendar ja Outlook. Sinun ei tarvitse tehdä mitään.
2026-10-06 — Lukitse avain palvelimiisi: sallittujen IP-osoitteiden listat nyt, asiakasvarmenteet (mTLS) osoitteessa api.timtim.live. Valinnainen. Sinun ei tarvitse tehdä mitään.
2026-10-06 — OAuth 2.0 client credentials suurille integraatioille: POST /v1/oauth/token ja /v1/oauth/revoke. Avaimet toimivat edelleen. Sinun ei tarvitse tehdä mitään.
2026-10-06 — WordPress-lisäosa 1.0.0: lohko, lyhytkoodi ja asetussivu. Se päivittää itsensä timtim.live-sivustolta. Sinun ei tarvitse tehdä mitään.
2026-10-06 — Sivustowidget, JSON/RSS/XML/CSV-syötteet ja webhookit (event.changed, earnings.changed). Sinun ei tarvitse tehdä mitään.
2026-10-06 — Partner API v1: tapahtumat, yksi tapahtuma, ansiot ja hiekkalaatikko. Sinun ei tarvitse tehdä mitään.