Партньор 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

Вашият ключ за връзка

Изпрати ключа си в заглавната част. Клавиши за изпитване (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: Двубуквен код на страната, например САЩ.
category: Например музика, фестивал или конференция.
from: Събития на или след тази дата (2026-10-20).
to: Събития на или преди тази дата.
changed_since: Само събития, които се промениха след това време.
commissioned: вярно = само събития, които плащат награда.
minimum_earnings: Само събития, които плащат поне толкова за билет.
near: Място, например близо до Париж, FR.
limit: Колко събития на страница, от 1 до 100 (20 ако го пропуснете).

Само ми кажи какво се промени.

Спестете времето на последното синхронизиране и го изпратете като променено. Получавате само събития, които са се променили — включително анулации и разпродадени предавания. Няма нужда от кука. Събитията, които трябва да спрете да показвате, се връщат в изтегления списък.

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

Повече от една страница

Ако отговорът е следващ, изпратете го обратно като курсор = за да получите следващата страница. Когато следващият е празен, имаш всичко.

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

Печалба

Всяко събитие е спечелено. Ако припечелването е невярно, събитието няма награда — все още си заслужава да се покаже. Ако това е вярно, peat.desscription казва това, което получавате, например "$5 за допустим билет". Ако покупката бъде възстановена, наградата се отменя.

Насипни фуражи (всичко в един файл)

Спестете доста храна на таблото си. След това изтеглете всяко събитие, което обхваща в един zipped файл, с вашия сървър ключ: GET /v1/bulk/FEED_ID.ndjson.gz или .csv.gz. Добавяне ?променен_тъй = само за това, което се е променило, включително събития свален. Тестовите ключове могат да го изпробват сега; използването на живо се нуждае от TimTim.Live преглед.

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

Продавайте билети в собственото си приложение (вградена търговия)

Големите партньори могат да държат купувачите в собственото си приложение. Попитайте GET /v1/събития/EVENT_ID/тикети за това, което се продава, след това POST /v1/ поръчки по избор на купувача. Получавате 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

Статус на събитието и билети

статусът е планиран, отложен, отменен, анулиран, продаден или завършен. билети.Наличността е достъпна, ограничена, продадена_ out, не_on_ sale или приключила. Когато едно събитие се отмени, го свали.

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

Колко бързо можеш да попиташ

Тестови ключове: 60 заявки в минута. Ключовете на живо: 120 в минута. По-бързо получава 429 отговор с Retrie-After, броя на секундите, за да изчакате.

Кои събития получавате?

Събития, които TimTim.Live организатори създават и избират да споделят. Събитията, които внасяме от други сайтове за билети, никога не са включени, защото ние не притежаваме правото да ги споделяме.

Това, което никога не изпращаме.

Имена на купувача, имейл адреси, домашни адреси, телефонни номера и данни за картата. Партньорът 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>

Опции: данни-град, държава-данни, категория данни, лимит на данните (1-24), данни-ухрана= "вярно", lang и цвят на данните.

OAuth 2.0 (големи интеграции)

Незадължително. Направи клиент на таблото си. Променете самоличността и тайната на клиента му за достъп, който трае един час. Изпрати този знак вместо ключ. Тайната никога не пътува с вашите API разговори, и можете да поискате по-малко обхват, отколкото клиентът има.

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

За да сложите край на жетона по-рано, изпратете го до /v1/outh/revoke със същата самоличност и тайна на клиента. Изключването на клиента на таблото ви приключва всичките му символи наведнъж.

Заключване на ключ към сървърите

Незадължително. На таблото си, намери ключ от сървър, тестов ключ или OAuth клиент. Отворете "Заключване на сървърите ми" и избройте адресите на вашите сървъри. Повиквания — и жетонни заявки — от всяко друго място се отказват с ip_not_позволен, дори и с правилния ключ.

Сертификати за клиенти (mTLS), за големи компании: дайте ни личната карта на вашия сървър (сертификат) и я поставете на ключ. След това се обадете на https://api.timim.live с него. Отговаряме само на сървъра, който държи този сертификат.

# 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 Събития: блок и кратък код, който показва събития със собствени TimTim.Live билета връзки. Той е направен от TimTim.Live, говори само за Timtim.live, и актуализации само от Timmitim.liv.

Качете файла в Plugins → Добавяне на нов → Качете Plugin. Поставете вашия ключ в Настройки → TimTim.Live Събития и натиснете Test Connection. След това добавете TimTim.Live Събития блок към всяка страница.

Изтегляне на приставката WordPress

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

Фуражи

Същите събития като JSON Feed, RSS, XML, CSV или календарен файл (.ics). Google Календар, Apple Календар и 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 са незадължителни — changed_тъй като ви дава същата информация.

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

Проверете всяко съобщение: подписано е с вашата тайна. Откажи се от всичко по-старо от пет минути, и игнорирай Тим Тим-доставката, с която вече си се справил.

// 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, натиснете Buy Test Ticket, след което попитайте за приходите си. Симулирай възстановяване и го гледай как се обръща.

Когато нещо се обърка

Грешките се обясняват с ясни думи, със заглавие и какво да правят след това. Всеки отговор носи Тим Тим-Реквизит. Изпрати ни го и ще намерим молбата ти.

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.
409idempotency_conflictThat Idempotency-Key was already used for a different order. Send exactly the same order to get the same answer back, or use a new Idempotency-Key for a new order.
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.

Договорът

Пълното описание на всяко поле, във формат OpenAPI вашите инструменти могат да четат.

Изтегли openapi.yaml

Как се отварят клавишите на живо

Твоят тестов ключ работи веднага. За живи ключове, човек на TimTim.Live гледа името на вашата компания, вашия сайт и как ще покаже събитията. Виждаш отговора на таблото.

TimTim.Live Актуализации на API

Версия 1 расте само. Добавяме нови неща. Ние не премахваме или преименуваме това, което вече е там.

2026-10-08 — Отговорите на събитията сега носят ЕТАГ. Изпрати го обратно като ако-нищо-мач, за да получите бързо 304, когато нищо не се промени. Незадължително.
2026-10-08 — Website клавишите сега броят всеки посетител сами по себе си, така че заети сайтове продължават да работят. Няма нужда от действия.
2026-10-07 — Сертификатите за клиенти (mTLS) са отворени: запишете удостоверението си на ключ на таблото. Незадължително. Няма нужда от действия.
2026-10-07 — Bulk Feeds: всяко събитие, което можете да покажете, в един файл, в GET /v1/bulk. Незадължително. Няма нужда от действия.
2026-10-07 — API има свой собствен адрес: https://api.timitim.live/v1. https://timim.liv/v1 продължава да работи. Няма нужда от действия.
2026-10-06 — Вашата собствена маркова страница за напускане в Timmitim.live/checkout. Незадължително. Няма нужда от действия.
2026-10-06 — Продавайте билети в собственото си приложение: GET /v1/събития/EVENT_ID/тикети и POST /v1/ поръчки. Незадължително. Няма нужда от действия.
2026-10-06 — Публична страница за статус в /партньори/статус, проверявана всяка минута. Няма нужда от действия.
2026-10-06 — Месечни отчети за компании: GET /v1/stettlements. Няма нужда от действия.
2026-10-06 — Postbacks: добавете ?sub_id= към линк за покупка и ние го изпращаме обратно към вас с продажбата. Незадължително. Няма нужда от действия.
2026-10-06 — Свързани с карти оферти за банки и награди програми: GET /v1/offers. Незадължително. Няма нужда от действия.
2026-10-06 — Календар фураж: /v1/feeds/events.ics за Google Календар, Apple Календар и Outlook. Няма нужда от действия.
2026-10-06 — Заключване на ключ към сървърите: IP licenses сега, клиентски сертификати (mTLS) на api.tim.live. Незадължително. Няма нужда от действия.
2026-10-06 — OAuth 2.0 клиентски акредитиви за големи интеграции: POST /v1/outh/ken и /v1/auth/revoke. Ключовете продължават да работят. Няма нужда от действия.
2026-10-06 — Приставка за WordPress 1.0.0: блок, кратък код и страница за настройки. Той се обновява от Timtim.live. Няма нужда от действия.
2026-10-06 — Уеб сайт джаджа, JSON/RSS/XML/CSV фуражи и уеб куки (събитие.промени, печалби.променени). Няма нужда от действия.
2026-10-06 — Партньор API v1: събития, едно събитие, приходи, и пясъчника. Няма нужда от действия.