Partner API — început rapid

Prima ta integrare încape pe un singur ecran.

Încearcă acum — fără cheie, fără înregistrare

Deschide această adresă în browser. Vei vedea imediat evenimente de probă.

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

1
Ia o cheie de test
Conectează-te, spune-ne cine ești și apasă „Creează cheie de test”. Începe cu tt_test_ și vede doar evenimente de probă.

Găsește evenimente

Cere evenimentele dintr-un oraș.

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

3
Arată evenimentul
Fiecare eveniment are nume, dată, loc, imagine, preț și etichete gata făcute pentru cardul tău.
4
Folosește buy_url
Folosește buy_url pe care ți-l dăm. Asta e tot. TimTim.Live notează singur în acel link că cumpărătorul a venit de la tine.
5
Vezi rezultatele
Vezi câți oameni ai trimis, câte bilete s-au vândut și cât ai câștigat — în panou sau printr-o cerere.
GET https://api.timtim.live/v1/earnings

Ia-mi cheia de test Încearcă fără cheie

Starea TimTim.Live

Referință

Unde trimiți cererile

https://api.timtim.live/v1

Cheia ta de conectare

Trimite cheia în antetul Authorization. Cheile de test (tt_test_) văd doar evenimente de probă. Cheile pentru site (tt_pk_live_) pot sta într-o pagină web și doar citesc evenimente. Cheile de server (tt_sk_live_) rămân pe serverul tău și pot citi și câștigurile. Îți arătăm o cheie o singură dată — păstreaz-o în siguranță.

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

Filtre

city: Evenimente din acest oraș.
country: Codul țării din două litere, de exemplu US.
category: De exemplu music, festival sau conference.
from: Evenimente din această zi sau mai târziu (2026-10-20).
to: Evenimente din această zi sau mai devreme.
changed_since: Doar evenimentele care s-au schimbat după acest moment.
commissioned: true = doar evenimentele care plătesc o recompensă.
minimum_earnings: Doar evenimentele care plătesc cel puțin atât pe bilet.
near: Un loc, de exemplu near=Paris,FR.
limit: Câte evenimente pe pagină, de la 1 la 100 (20 dacă nu scrii nimic).

Spune-mi doar ce s-a schimbat

Salvează ora ultimei sincronizări și trimite-o ca changed_since. Primești doar evenimentele care s-au schimbat — inclusiv cele anulate și cele cu biletele epuizate. Nu ai nevoie de webhook. Evenimentele pe care trebuie să nu le mai afișezi vin în lista withdrawn.

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

Mai mult de o pagină

Dacă răspunsul are next, trimite-l înapoi ca cursor= ca să primești pagina următoare. Când next este gol, ai tot.

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

Câștiguri

Fiecare eveniment are earn. Dacă earn.eligible este false, evenimentul nu are recompensă — merită totuși arătat. Dacă este true, earn.description spune ce primești, de exemplu „$5 pentru fiecare bilet eligibil”. Dacă cumpărarea este rambursată, recompensa se anulează.

Fluxuri complete (totul într-un fișier)

Salvează un flux complet în panoul tău, apoi descarcă toate evenimentele lui într-un singur fișier comprimat: GET /v1/bulk/FEED_ID.ndjson.gz sau .csv.gz, cu cheia ta de server. Adaugă ?changed_since= ca să primești doar ce s-a schimbat, inclusiv evenimentele scoase. Cheile de test îl pot încerca acum; folosirea reală are nevoie de o verificare de la TimTim.Live.

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

Vinde bilete în propria aplicație (comerț integrat)

Partenerii mari pot păstra cumpărătorii în propria aplicație. Cere GET /v1/events/EVENT_ID/tickets ca să vezi ce este de vânzare, apoi trimite POST /v1/orders cu alegerea cumpărătorului. Primești un link de plată TimTim.Live pe care îl deschizi pentru cumpărător; vânzarea este creditată direct firmei tale. Cheile de test îl pot încerca acum. Folosirea reală are nevoie de o verificare TimTim.Live și de plățile cu cardul pornite.

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

Oferte legate de card (bănci și programe de recompense)

GET /v1/offers dă fiecare eveniment care plătește o recompensă ca ofertă: organizatorul, datele în care se poate cumpăra, prețul, locul și recompensa. Clientul tău o activează prin linkul tău urmărit, iar recompensa este plătită firmei tale prin /v1/earnings. Cheile de test văd oferte de exemplu. Ofertele reale au nevoie de o verificare TimTim.Live. Potrivirea directă a plăților cu cardul are nevoie de un acord cu o rețea de carduri sau o bancă și nu este conectată.

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

Starea evenimentului și biletele

status este scheduled, postponed, rescheduled, cancelled, sold_out sau completed. tickets.availability este available, limited, sold_out, not_on_sale sau ended. Când un eveniment este anulat, scoate-l.

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

Cât de des poți întreba

Cheile de test: 60 de cereri pe minut. Cheile live: 120 pe minut. Dacă mergi mai repede, primești răspunsul 429 cu Retry-After, adică numărul de secunde de așteptat.

Ce evenimente primești

Evenimentele pe care organizatorii TimTim.Live le creează și aleg să le împartă. Evenimentele preluate de pe alte site-uri de bilete nu sunt incluse niciodată, pentru că nu avem dreptul să le împărțim.

Ce nu trimitem niciodată

Numele cumpărătorilor, adresele de e-mail, adresele de acasă, numerele de telefon și datele cardurilor. Partner API împarte informații despre evenimente, nu despre membrii noștri.

Widget pentru site

Un singur rând de HTML arată evenimente pe orice site. Folosește o cheie pentru site (tt_pk_live_) și adaugă site-ul tău în lista de site-uri permise a cheii. Fără cheie, arată evenimente de probă.

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

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

OAuth 2.0 (integrări mari)

Opțional. Creează un client OAuth în panou. Apoi schimbă ID-ul de client și secretul pe un token de acces de o oră și trimite acel token în locul unei chei. Secretul nu călătorește niciodată cu apelurile tale API și poți cere mai puține permisiuni (scopes) decât are clientul.

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

Ca să oprești un token mai devreme, trimite-l prin POST la /v1/oauth/revoke cu același ID de client și secret. Dacă oprești clientul în panou, toate tokenurile lui se termină deodată.

Blochează o cheie pe serverele tale

Opțional. În panoul tău, deschide „Blochează pe serverele mele” sub o cheie de server, o cheie de test sau un client OAuth și scrie adresele publice ale serverelor tale. Apelurile — și cererile de token — de oriunde altundeva sunt refuzate cu ip_not_allowed, chiar și cu cheia corectă.

Certificate de client (mTLS): leagă certificatul tău de client TLS de o cheie, apoi apelează https://api.timtim.live cu el. Fiecare apel trebuie să arate acel certificat; handshake-ul TLS dovedește că ai cheia lui privată.

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

Modul WordPress

Folosești WordPress? Instalează TimTim.Live Events: un bloc și un shortcode care arată evenimente cu propriile tale linkuri de bilete TimTim.Live. E făcut de TimTim.Live, vorbește doar cu timtim.live și se actualizează doar de pe timtim.live.

Încarcă fișierul în Module → Adaugă nou → Încarcă modul. Lipește cheia pentru site în Setări → TimTim.Live Events și apasă Test Connection. Apoi adaugă blocul TimTim.Live Events pe orice pagină.

Descarcă modulul WordPress

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

Fluxuri de date

Aceleași evenimente ca JSON Feed, RSS, XML, CSV sau ca un calendar (.ics) la care se pot abona Google Calendar, Apple Calendar și Outlook. Cititoarele de fluxuri nu pot trimite antete, așa că pune o cheie pentru site sau o cheie de test în ?key=. Nu pune niciodată o cheie de server într-un link.

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

Webhookuri

Adaugă o adresă în panoul tău și îi trimitem un mesaj când se schimbă ceva: event.changed sau earnings.changed. Webhookurile nu sunt obligatorii — changed_since îți dă aceleași informații.

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

Verifică fiecare mesaj: este semnat cu secretul tău. Refuză orice e mai vechi de cinci minute și ignoră un TimTim-Delivery-Id pe care l-ai tratat deja.

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

Răspunde cu orice 2xx în 10 secunde. Dacă nu, încercăm din nou după 1 minut, 5 minute, 30 de minute, apoi după 2, 6, 12 și 24 de ore, apoi ne oprim. Nu urmăm niciodată redirecționări.

Sandboxul

Cheile de test primesc evenimente de probă marcate EVENIMENT DE TEST — FĂRĂ BANI ADEVĂRAȚI. Deschide un buy_url, apasă „Cumpără bilet de test”, apoi cere-ți câștigurile. Simulează o rambursare și vezi cum se anulează.

Când ceva nu merge

Erorile se explică în cuvinte simple, cu un titlu și ce să faci mai departe. Fiecare răspuns are un TimTim-Request-Id. Trimite-ni-l și îți găsim cererea.

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.

Descrierea completă

Descrierea completă a fiecărui câmp, în formatul OpenAPI pe care uneltele tale îl pot citi.

Descarcă openapi.yaml

Cum se deschid cheile live

Cheia ta de test funcționează imediat. Pentru cheile live, o persoană de la TimTim.Live se uită la numele companiei tale, la site-ul tău și la cum vei arăta evenimentele. Vezi răspunsul în panoul tău.

Noutăți TimTim.Live API

Versiunea 1 doar crește. Adăugăm lucruri noi. Nu ștergem și nu redenumim ce există deja.

2026-10-08 — Răspunsurile despre evenimente au acum un ETag. Trimite-l înapoi în If-None-Match ca să primești un 304 rapid când nu s-a schimbat nimic. Opțional.
2026-10-08 — Cheile de site numără acum fiecare vizitator separat, ca site-urile aglomerate să funcționeze în continuare. Nu trebuie să faci nimic.
2026-10-07 — Certificatele de client (mTLS) sunt deschise: leagă certificatul tău de o cheie în panoul tău. Opțional. Nu trebuie să faci nimic.
2026-10-07 — Fluxuri complete: fiecare eveniment pe care îl poți arăta, într-un singur fișier, la GET /v1/bulk. Opțional. Nu trebuie să faci nimic.
2026-10-07 — API-ul are propria adresă: https://api.timtim.live/v1. https://timtim.live/v1 continuă să funcționeze. Nu trebuie să faceți nimic.
2026-10-06 — Propria ta pagină de plată, cu marca ta, la timtim.live/checkout. Opțional. Nu trebuie să faci nimic.
2026-10-06 — Vinde bilete în propria ta aplicație: GET /v1/events/EVENT_ID/tickets și POST /v1/orders. Opțional. Nu trebuie să faci nimic.
2026-10-06 — O pagină publică de stare la /partners/status, verificată în fiecare minut. Nu trebuie să faci nimic.
2026-10-06 — Situații lunare pentru companii: GET /v1/settlements. Nu trebuie să faci nimic.
2026-10-06 — Postbackuri: adaugă ?sub_id= la un link de cumpărare și ți-l trimitem înapoi odată cu vânzarea. Opțional. Nu trebuie să faci nimic.
2026-10-06 — Oferte legate de card pentru bănci și programe de recompense: GET /v1/offers. Opțional. Nu trebuie să faci nimic.
2026-10-06 — Flux de calendar: /v1/feeds/events.ics pentru Google Calendar, Apple Calendar și Outlook. Nu trebuie să faci nimic.
2026-10-06 — Blochează o cheie pe serverele tale: liste de IP permise acum, certificate de client (mTLS) pe api.timtim.live. Opțional. Nu trebuie să faci nimic.
2026-10-06 — OAuth 2.0 client credentials pentru integrări mari: POST /v1/oauth/token și /v1/oauth/revoke. Cheile merg în continuare. Nu trebuie să faci nimic.
2026-10-06 — Modul WordPress 1.0.0: un bloc, un shortcode și o pagină de setări. Se actualizează singur de pe timtim.live. Nu trebuie să faci nimic.
2026-10-06 — Widget pentru site, fluxuri de date JSON/RSS/XML/CSV și webhookuri (event.changed, earnings.changed). Nu trebuie să faci nimic.
2026-10-06 — Partner API v1: evenimente, un singur eveniment, câștiguri și sandboxul. Nu trebuie să faci nimic.