Partner API — Fara da Sauri

Haɗinka na farko ya isa a allo ɗaya.

Gwada yanzu — babu mabuɗi, babu rajista

Buɗe wannan adireshin a burauzarka. Za ka ga tarukan misali nan take.

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

1
Samu mabuɗin gwaji
Shiga, gaya mana ko kai wane ne, sannan ka danna Ƙirƙiri Mabuɗin Gwaji. Yana farawa da tt_test_ kuma yana ganin tarukan misali kawai.

Nemo taruka

Nemi taruka a wani gari.

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

3
Nuna taron
Kowane taro yana da suna, kwanan wata, wuri, hoto, farashi da rubuce-rubuce shirye don katinka.
4
Yi amfani da buy_url
Yi amfani da buy_url da muka ba ka. Shi ke nan. TimTim.Live tana kula da bin diddigin sayarwa a cikin wannan hanyar haɗi.
5
Duba sakamako
Ga mutanen da ka aika, tikitin da aka sayar da kuɗin da aka samu a allon bayananka, ko ka nemi su.
GET https://api.timtim.live/v1/earnings

Samu Mabuɗin Gwaji Na Gwada Ba Tare da Mabuɗi Ba

Matsayin TimTim.Live

Bayani Dalla-dalla

Inda za a aika buƙatu

https://api.timtim.live/v1

Mabuɗin Haɗinka

Aika mabuɗinka a cikin header na Authorization. Mabuɗan gwaji (tt_test_) suna ganin tarukan misali kawai. Mabuɗan shafi (tt_pk_live_) za su iya zama a shafin yanar gizo kuma suna karanta taruka kawai. Mabuɗan server (tt_sk_live_) suna zama a server ɗinka kuma suna iya karanta kuɗin da aka samu. Muna nuna mabuɗi sau ɗaya kawai — ka adana shi lafiya.

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

Matatun Bincike

city: Taruka a wannan gari.
country: Lambar ƙasa mai haruffa biyu, misali US.
category: Misali music, festival ko conference.
from: Taruka a wannan rana ko bayanta (2026-10-20).
to: Taruka a wannan rana ko kafin ta.
changed_since: Tarukan da suka canza bayan wannan lokaci kawai.
commissioned: true = tarukan da suke biyan lada kawai.
minimum_earnings: Tarukan da suke biyan aƙalla wannan adadin kan kowane tikiti kawai.
near: Wani wuri, misali near=Paris,FR.
limit: Taruka nawa a kowane shafi, 1 zuwa 100 (20 idan ba ka saka ba).

Faɗa min abin da ya canza kawai

Adana lokacin daidaitawarka ta ƙarshe ka aika shi a matsayin changed_since. Za ka samu tarukan da suka canza kawai — har da waɗanda aka soke da waɗanda tikitinsu ya ƙare. Ba a buƙatar webhook. Tarukan da dole ka daina nunawa suna zuwa a cikin jerin withdrawn.

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

Fiye da shafi ɗaya

Idan amsar tana da next, mayar da shi a matsayin cursor= don samun shafi na gaba. Idan next babu komai, ka samu komai.

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

Samun kuɗi

Kowane taro yana da earn. Idan earn.eligible false ne, taron ba shi da lada — duk da haka yana da kyau a nuna shi. Idan true ne, earn.description yana faɗin abin da za ka samu, misali "$5 kan kowane tikiti da ya cancanta". Idan aka mayar da kuɗin sayen, za a dawo da ladan.

Feed na Gaba Ɗaya (komai a fayil ɗaya)

Adana Feed na Gaba Ɗaya a allon bayananka, sannan ka sauke duk tarukan da ya ƙunsa a cikin fayil ɗaya da aka matse: GET /v1/bulk/FEED_ID.ndjson.gz ko .csv.gz, da mabuɗin server ɗinka. Ƙara ?changed_since= don abin da ya canza kawai, har da tarukan da aka cire. Mabuɗan gwaji za su iya gwada shi yanzu; amfani na gaske yana buƙatar dubawa daga TimTim.Live.

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

Sayar da tikiti a cikin manhajarka (kasuwanci a ciki)

Manyan abokan hulɗa za su iya ajiye masu saye a cikin manhajarsu. Tambayi GET /v1/events/EVENT_ID/tickets don ganin abin da ake sayarwa, sannan ka aika POST /v1/orders da zaɓin mai saye. Za ka sami haɗin biyan kuɗi na TimTim.Live da za ka buɗe wa mai saye; ana ƙididdige cinikin ga kamfaninka kai tsaye. Mabuɗan gwaji za su iya gwada shi yanzu. Amfani na gaske yana buƙatar duba daga TimTim.Live da kunna biyan kuɗi da kati.

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

Tayi masu alaƙa da kati (bankuna da shirye-shiryen lada)

GET /v1/offers yana ba da kowane taro da ke biyan lada a matsayin tayi: mai shiryawa, ranakun da za a iya saya, farashi, wuri da lada. Abokin cinikinka yana kunna shi ta hanyar haɗinka da ake bibiya, kuma ana biyan ladan ga kamfaninka ta /v1/earnings. Mabuɗan gwaji suna ganin tayin samfuri. Tayi na gaske suna bukatar dubawa daga TimTim.Live. Daidaita biyan kuɗi da kati kai tsaye yana bukatar yarjejeniya da cibiyar katuna ko banki, kuma ba a haɗa shi ba.

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

Matsayin taro da tikiti

status shi ne scheduled, postponed, rescheduled, cancelled, sold_out ko completed. tickets.availability shi ne available, limited, sold_out, not_on_sale ko ended. Idan taro ya zama cancelled, ka cire shi.

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

Yaya saurin da za ka iya tambaya

Mabuɗan gwaji: buƙatu 60 a minti ɗaya. Mabuɗan gaske: 120 a minti ɗaya. Idan ka yi sauri fiye da haka za ka samu amsar 429 tare da Retry-After, adadin daƙiƙun da za ka jira.

Wane taruka za ka samu

Tarukan da masu shiryawa na TimTim.Live suka ƙirƙira kuma suka zaɓi su raba. Tarukan da muka kawo daga wasu shafukan tikiti ba a taɓa saka su ba, saboda ba mu da ikon raba su.

Abin da ba mu taɓa aikawa

Sunayen masu saye, adireshin imel, adireshin gida, lambobin waya da bayanan kati. Partner API tana raba bayanan taruka, ba membobinmu ba.

Widget na shafi

Layin HTML ɗaya yana nuna taruka a kowane shafin yanar gizo. Yi amfani da mabuɗin shafi (tt_pk_live_), kuma ka ƙara shafinka cikin jerin shafukan da mabuɗin ya yarda da su. Idan babu mabuɗi, yana nuna tarukan misali.

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

Zaɓuɓɓuka: data-city, data-country, data-category, data-limit (1–24), data-earn="true", data-lang da data-color.

OAuth 2.0 (manyan haɗe-haɗe)

Ba dole ba ne. Ƙirƙiri client na OAuth a allon bayananka, sannan ka ba da client ID da secret ɗinsa don samun access token na awa ɗaya, ka aika wannan token maimakon mabuɗi. Secret ba ya tafiya tare da kiran API ɗinka, kuma za ka iya neman izini (scopes) ƙasa da na client ɗin.

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

Don ƙare token da wuri, aika shi ta POST zuwa /v1/oauth/revoke da client ID da secret iri ɗaya. Kashe client ɗin a allon bayananka yana ƙare dukkan token ɗinsa lokaci ɗaya.

Kulle mabuɗi zuwa server ɗinka

Na zaɓi ne. A allon bayananka, buɗe "Kulle zuwa server ɗina" a ƙarƙashin mabuɗin server, mabuɗin gwaji ko client na OAuth, sannan ka rubuta adireshin jama'a na server ɗinka. Kira — da buƙatun token — daga ko'ina kuma za a ƙi su da ip_not_allowed, ko da mabuɗin daidai ne.

Takardun shaidar client (mTLS): haɗa takardar shaidar client ta TLS ɗinka da mabuɗi, sannan ka kira https://api.timtim.live da ita. Kowane kira dole ne ya nuna wannan takardar shaida; musafahar TLS tana tabbatar da cewa kana riƙe da mabuɗinta na sirri.

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

Plugin na WordPress

Kana amfani da WordPress? Saka TimTim.Live Events: block da shortcode da ke nuna taruka tare da hanyoyin tikitin TimTim.Live naka. TimTim.Live ne ya yi shi, yana magana da timtim.live kawai, kuma yana sabuntuwa daga timtim.live kawai.

Ɗora fayil ɗin a Plugins → Add New → Upload Plugin. Liƙa mabuɗin shafinka a Settings → TimTim.Live Events, sannan ka danna Test Connection. Bayan haka ka ƙara block na TimTim.Live Events a kowane shafi.

Sauke Plugin na WordPress

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

Feed

Tarukan iri ɗaya a matsayin JSON Feed, RSS, XML, CSV ko kalanda (.ics) da Google Calendar, Apple Calendar da Outlook za su iya yin rajista a kai. Masu karanta feed ba sa iya aika headers, don haka saka mabuɗin shafi ko mabuɗin gwaji a cikin ?key=. Kada ka taɓa saka mabuɗin server a cikin hanyar haɗi.

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

Ƙara adireshi a allon bayananka, kuma za mu aika masa saƙo idan wani abu ya canza: event.changed ko earnings.changed. Webhooks ba dole ba ne — changed_since yana ba ka bayanai iri ɗaya.

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

Duba kowane saƙo: an sa masa hannu da sirrinka. Ƙi duk abin da ya wuce minti biyar, kuma ka yi watsi da TimTim-Delivery-Id da ka riga ka kula da shi.

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

Amsa da kowane 2xx cikin daƙiƙa 10. Idan ba haka ba, za mu sake gwadawa bayan minti 1, minti 5, minti 30, sannan awa 2, 6, 12 da 24, sannan mu daina. Ba ma bin juyawa zuwa wani adireshi ko kaɗan.

Wurin gwaji

Mabuɗan gwaji suna samun tarukan misali masu alamar TARON GWAJI — BABU KUƊI NA GASKE. Buɗe buy_url, danna Sayi Tikitin Gwaji, sannan ka nemi kuɗin da ka samu. Gwada mayar da kuɗi ka ga yadda aka dawo da shi.

Idan wani abu ya lalace

Kurakurai suna bayyana kansu da kalmomi masu sauƙi, tare da take da abin da za a yi a gaba. Kowace amsa tana ɗauke da TimTim-Request-Id. Aiko mana da shi za mu nemo buƙatarka.

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.

Yarjejeniyar API

Cikakken bayanin kowane fili, a tsarin OpenAPI da kayan aikinka za su iya karantawa.

Sauke openapi.yaml

Yadda mabuɗan gaske ke buɗewa

Mabuɗin gwajinka yana aiki nan take. Don mabuɗan gaske, wani mutum a TimTim.Live yana duba sunan kamfaninka, shafinka da yadda za ka nuna taruka. Za ka ga amsar a allon bayananka.

Sabbin Labaran API na TimTim.Live

Siga ta 1 tana ƙaruwa ne kawai. Muna ƙara sababbin abubuwa. Ba ma cire ko sake sunan abin da yake nan.

2026-10-08 — Amsoshin taruka yanzu suna ɗauke da ETag. Mayar da shi a If-None-Match don samun 304 cikin sauri idan babu abin da ya canza. Na zaɓi ne.
2026-10-08 — Mabuɗan gidan yanar gizo yanzu suna ƙidaya kowane baƙo daban, don shafuka masu yawan baƙi su ci gaba da aiki. Ba ka buƙatar yin komai.
2026-10-07 — Takardun shaidar client (mTLS) sun buɗe: haɗa takardar shaidarka da mabuɗi a allon bayananka. Na zaɓi ne. Ba ka buƙatar yin komai.
2026-10-07 — Feed na gaba ɗaya: kowane taro da za ka iya nunawa, a fayil ɗaya, a GET /v1/bulk. Na zaɓi ne. Ba ka buƙatar yin komai.
2026-10-07 — API na da adireshinsa: https://api.timtim.live/v1. https://timtim.live/v1 yana ci gaba da aiki. Babu abin da ake bukata.
2026-10-06 — Shafin biyan kuɗi naka mai alamarka a timtim.live/checkout. Na zaɓi ne. Ba ka buƙatar yin komai.
2026-10-06 — Sayar da tikiti a manhajarka: GET /v1/events/EVENT_ID/tickets da POST /v1/orders. Na zaɓi ne. Ba ka buƙatar yin komai.
2026-10-06 — Shafin matsayi na jama'a a /partners/status, ana duba shi kowane minti. Ba ka buƙatar yin komai.
2026-10-06 — Takardun bayanin kuɗi na wata-wata don kamfanoni: GET /v1/settlements. Ba ka buƙatar yin komai.
2026-10-06 — Postback: ƙara ?sub_id= a hanyar haɗin sayayya kuma za mu mayar maka da shi tare da sayayyar. Na zaɓi ne. Ba ka buƙatar yin komai.
2026-10-06 — Tayi masu alaƙa da kati don bankuna da shirye-shiryen lada: GET /v1/offers. Na zaɓi ne. Ba ka buƙatar yin komai.
2026-10-06 — Feed na kalanda: /v1/feeds/events.ics don Google Calendar, Apple Calendar da Outlook. Ba ka buƙatar yin komai.
2026-10-06 — Kulle mabuɗi zuwa server ɗinka: jerin IP da aka yarda yanzu, takardun shaidar client (mTLS) a api.timtim.live. Na zaɓi ne. Ba ka buƙatar yin komai.
2026-10-06 — OAuth 2.0 client credentials don manyan haɗe-haɗe: POST /v1/oauth/token da /v1/oauth/revoke. Mabuɗan suna ci gaba da aiki. Ba sai ka yi komai ba.
2026-10-06 — Plugin na WordPress 1.0.0: block ɗaya, shortcode ɗaya da shafin saituna. Yana sabunta kansa daga timtim.live. Ba sai ka yi komai ba.
2026-10-06 — Widget na shafi, feed na JSON/RSS/XML/CSV da webhooks (event.changed, earnings.changed). Ba sai ka yi komai ba.
2026-10-06 — Partner API v1: taruka, taro ɗaya, kuɗin da aka samu, da wurin gwaji. Ba sai ka yi komai ba.