Partner API — швидкий старт

Ваше перше підключення вміщується на одному екрані.

Спробуйте зараз — без ключа й без реєстрації

Відкрийте цю адресу в браузері. Ви одразу побачите прикладові події.

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

1
Отримайте тестовий ключ
Увійдіть, розкажіть, хто ви, і натисніть «Створити тестовий ключ». Він починається з tt_test_ і бачить лише прикладові події.

Знайдіть події

Запитайте події в місті.

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

3
Покажіть подію
Кожна подія має назву, дату, місце, картинку, ціну й готові підписи для вашої картки.
4
Використовуйте buy_url
Використовуйте buy_url, який ми даємо. От і все. TimTim.Live сам позначає в цьому посиланні, що покупець прийшов від вас.
5
Дивіться результати
Дивіться, скільки людей ви привели, скільки квитків продано й скільки ви заробили — у кабінеті або через запит.
GET https://api.timtim.live/v1/earnings

Отримати тестовий ключ Спробувати без ключа

Статус TimTim.Live

Довідник

Куди надсилати запити

https://api.timtim.live/v1

Ваш ключ підключення

Надсилайте ключ у заголовку Authorization. Тестові ключі (tt_test_) бачать лише прикладові події. Ключі для сайту (tt_pk_live_) можна ставити на вебсторінку, вони лише читають події. Серверні ключі (tt_sk_live_) зберігаються на вашому сервері й можуть також читати дохід. Ми показуємо ключ один раз — бережіть його.

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

Фільтри

city: Події в цьому місті.
country: Код країни з двох літер, наприклад US.
category: Наприклад music, festival або conference.
from: Події в цю дату або пізніше (2026-10-20).
to: Події в цю дату або раніше.
changed_since: Лише події, які змінилися після цього часу.
commissioned: true = лише події, які платять винагороду.
minimum_earnings: Лише події, які платять не менше цієї суми за квиток.
near: Місце, наприклад near=Paris,FR.
limit: Скільки подій на сторінці, від 1 до 100 (20, якщо не вказати).

Повідомляйте лише про зміни

Збережіть час останньої синхронізації й надішліть його як changed_since. Ви отримаєте лише змінені події — зокрема скасовані й розпродані. Webhook не потрібен. Події, які треба перестати показувати, надходять у списку withdrawn.

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

Більше ніж одна сторінка

Якщо у відповіді є next, надішліть його назад як cursor=, щоб отримати наступну сторінку. Коли next порожній, у вас є все.

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

Дохід

Кожна подія має earn. Якщо earn.eligible дорівнює false, подія не має винагороди — її все одно варто показувати. Якщо true, earn.description каже, що ви отримаєте, наприклад «$5 за кожен відповідний квиток». Якщо за купівлю повернуть гроші, винагорода списується назад.

Повні стрічки (усе в одному файлі)

Збережіть повну стрічку в кабінеті, а потім завантажте всі її події одним стиснутим файлом: GET /v1/bulk/FEED_ID.ndjson.gz або .csv.gz, із серверним ключем. Додайте ?changed_since=, щоб отримати лише зміни, разом зі знятими подіями. Тестові ключі можуть спробувати це вже зараз; для реальної роботи потрібна перевірка TimTim.Live.

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

Продавайте квитки у власному застосунку (вбудований продаж)

Великі партнери можуть залишати покупців у власному застосунку. Запитайте GET /v1/events/EVENT_ID/tickets, щоб побачити, що є в продажу, потім надішліть POST /v1/orders з вибором покупця. Ви отримаєте платіжне посилання TimTim.Live, яке відкриєте покупцеві; продаж зараховується напряму вашій компанії. Тестові ключі можуть спробувати це вже зараз. Для справжнього використання потрібна перевірка від TimTim.Live і ввімкнені платежі карткою.

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

Пропозиції, прив'язані до картки (банки та бонусні програми)

GET /v1/offers віддає кожну подію, за яку платиться винагорода, як пропозицію: організатор, дати, коли можна купити, ціна, місце і винагорода. Ваш клієнт активує її через ваше відстежуване посилання, а винагорода виплачується вашій компанії через /v1/earnings. Тестові ключі бачать зразкові пропозиції. Справжнім пропозиціям потрібна перевірка TimTim.Live. Пряме зіставлення оплат карткою потребує угоди з платіжною системою або банком і не підключене.

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

Статус події та квитки

status буває scheduled, postponed, rescheduled, cancelled, sold_out або completed. tickets.availability буває available, limited, sold_out, not_on_sale або ended. Якщо подію скасовано, приберіть її.

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

Як часто можна питати

Тестові ключі: 60 запитів на хвилину. Робочі ключі: 120 на хвилину. Якщо швидше, прийде відповідь 429 з Retry-After — скільки секунд зачекати.

Які події ви отримуєте

Події, які створюють організатори TimTim.Live і вирішують ними поділитися. Події, взяті з інших квиткових сайтів, ніколи не входять, бо ми не маємо права ними ділитися.

Що ми ніколи не надсилаємо

Імена покупців, адреси пошти, домашні адреси, номери телефонів і дані карток. Partner API ділиться інформацією про події, а не про наших учасників.

Віджет для сайту

Один рядок HTML показує події на будь-якому сайті. Використовуйте ключ для сайту (tt_pk_live_) і додайте свій сайт до списку дозволених сайтів ключа. Без ключа віджет показує прикладові події.

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

Налаштування: data-city, data-country, data-category, data-limit (1–24), data-earn="true", data-lang і data-color.

OAuth 2.0 (великі інтеграції)

Необов'язково. Створіть OAuth-клієнт у кабінеті. Потім обміняйте його ID і секрет на токен доступу на одну годину й надсилайте цей токен замість ключа. Секрет ніколи не передається разом із вашими запитами до API, і можна попросити менше прав (scopes), ніж має клієнт.

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

Щоб завершити токен раніше, надішліть його через POST на /v1/oauth/revoke з тим самим ID клієнта й секретом. Якщо вимкнути клієнт у кабінеті, усі його токени закінчаться одразу.

Прив'яжіть ключ до своїх серверів

Необов'язково. У кабінеті відкрийте «Прив'язати до моїх серверів» під серверним ключем, тестовим ключем або OAuth-клієнтом і вкажіть публічні адреси своїх серверів. Запити — і запити токена — звідки-небудь ще відхиляються з ip_not_allowed, навіть із правильним ключем.

Клієнтські сертифікати (mTLS): прив'яжіть свій клієнтський сертифікат TLS до ключа, потім звертайтеся до https://api.timtim.live з ним. Кожен запит має показати цей сертифікат; рукостискання TLS доводить, що у вас є його закритий ключ.

# 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

Користуєтеся WordPress? Встановіть TimTim.Live Events: блок і шорткод, які показують події з вашими посиланнями на квитки TimTim.Live. Його зробив TimTim.Live, він спілкується лише з timtim.live і оновлюється лише з timtim.live.

Завантажте файл у розділі Плагіни → Додати новий → Завантажити плагін. Вставте ключ для сайту в Налаштування → TimTim.Live Events і натисніть Test Connection. Потім додайте блок TimTim.Live Events на будь-яку сторінку.

Завантажити плагін для WordPress

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

Стрічки

Ті самі події у форматі JSON Feed, RSS, XML, CSV або як календар (.ics), на який можна підписатися в Google Calendar, Apple Calendar і Outlook. Програми для читання стрічок не вміють надсилати заголовки, тому вкажіть ключ для сайту або тестовий ключ у ?key=. Ніколи не ставте серверний ключ у посилання.

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

Webhooks

Додайте адресу в особистому кабінеті, і ми надішлемо на неї повідомлення, коли щось зміниться: event.changed або earnings.changed. Webhooks не обов'язкові — changed_since дає ту саму інформацію.

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

Перевіряйте кожне повідомлення: воно підписане вашим секретом. Відхиляйте все, що старше за п'ять хвилин, і пропускайте TimTim-Delivery-Id, який ви вже обробили.

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

Дайте відповідь будь-яким кодом 2xx протягом 10 секунд. Якщо ні, ми спробуємо знову через 1 хвилину, 5 хвилин, 30 хвилин, потім через 2, 6, 12 і 24 години, а тоді зупинимося. Ми ніколи не переходимо за перенаправленнями.

Пісочниця

З тестовим ключем ви отримуєте прикладові події з позначкою ТЕСТОВА ПОДІЯ — БЕЗ СПРАВЖНІХ ГРОШЕЙ. Відкрийте buy_url, натисніть «Купити тестовий квиток», потім запитайте свій дохід. Імітуйте повернення й подивіться, як суму списано назад.

Якщо щось пішло не так

Помилки пояснюють себе простими словами: заголовок і що робити далі. Кожна відповідь має TimTim-Request-Id. Надішліть його нам, і ми знайдемо ваш запит.

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.

Опис API

Повний опис кожного поля у форматі OpenAPI, який розуміють ваші інструменти.

Завантажити openapi.yaml

Як відкриваються робочі ключі

Тестовий ключ працює одразу. Для робочих ключів працівник TimTim.Live дивиться на назву вашої компанії, ваш сайт і те, як ви показуватимете події. Відповідь ви побачите у своєму кабінеті.

Новини TimTim.Live API

Версія 1 лише росте. Ми додаємо нове. Ми не видаляємо й не перейменовуємо те, що вже є.

2026-10-08 — Відповіді про події тепер містять ETag. Надішліть його назад в If-None-Match і отримайте швидкий 304, коли нічого не змінилося. Необов'язково.
2026-10-08 — Ключі для сайтів тепер рахують кожного відвідувача окремо, тож сайти з великою відвідуваністю працюють далі. Нічого робити не потрібно.
2026-10-07 — Клієнтські сертифікати (mTLS) відкриті: прив'яжіть сертифікат до ключа у своєму кабінеті. Необов'язково. Нічого робити не потрібно.
2026-10-07 — Повні стрічки: усі події, які ви можете показувати, в одному файлі, за адресою GET /v1/bulk. Необов'язково. Нічого робити не потрібно.
2026-10-07 — API має власну адресу: https://api.timtim.live/v1. https://timtim.live/v1 і далі працює. Нічого робити не потрібно.
2026-10-06 — Власна сторінка оплати з вашим брендом на timtim.live/checkout. Необов'язково. Нічого робити не потрібно.
2026-10-06 — Продаж квитків у вашому застосунку: GET /v1/events/EVENT_ID/tickets і POST /v1/orders. Необов'язково. Нічого робити не потрібно.
2026-10-06 — Відкрита сторінка статусу /partners/status, перевірка щохвилини. Нічого робити не потрібно.
2026-10-06 — Щомісячні звіти для компаній: GET /v1/settlements. Нічого робити не потрібно.
2026-10-06 — Postbacks: додайте ?sub_id= до посилання на покупку, і ми повернемо його вам разом із продажем. Необов'язково. Нічого робити не потрібно.
2026-10-06 — Пропозиції, прив'язані до картки, для банків і бонусних програм: GET /v1/offers. Необов'язково. Нічого робити не потрібно.
2026-10-06 — Стрічка календаря: /v1/feeds/events.ics для Google Calendar, Apple Calendar і Outlook. Нічого робити не потрібно.
2026-10-06 — Прив'яжіть ключ до своїх серверів: списки дозволених IP уже зараз, клієнтські сертифікати (mTLS) на api.timtim.live. Необов'язково. Нічого робити не потрібно.
2026-10-06 — OAuth 2.0 client credentials для великих інтеграцій: POST /v1/oauth/token і /v1/oauth/revoke. Ключі й далі працюють. Нічого робити не треба.
2026-10-06 — Плагін WordPress 1.0.0: блок, шорткод і сторінка налаштувань. Він сам оновлюється з timtim.live. Нічого робити не треба.
2026-10-06 — Віджет для сайту, стрічки JSON/RSS/XML/CSV і webhooks (event.changed, earnings.changed). Нічого робити не треба.
2026-10-06 — Partner API v1: події, одна подія, дохід і пісочниця. Нічого робити не треба.