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: события, одно событие, доход и песочница. Ничего делать не нужно.