Partner API — Démarrage rapide

Votre première intégration tient sur un seul écran.

Essayez maintenant — sans clé, sans inscription

Ouvrez cette adresse dans votre navigateur. Vous verrez tout de suite des exemples d'événements.

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

1
Obtenez une clé test
Connectez-vous, dites-nous qui vous êtes, puis appuyez sur Créer une clé test. Elle commence par tt_test_ et ne voit que des événements d'exemple.

Trouvez des événements

Demandez les événements d'une ville.

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

3
Affichez l'événement
Chaque événement a un nom, une date, un lieu, une image, un prix et des textes prêts pour votre carte.
4
Utilisez le buy_url
Utilisez le buy_url que nous vous donnons. C'est tout. TimTim.Live gère l'attribution dans ce lien.
5
Voyez les résultats
Voyez les personnes envoyées, les billets vendus et vos gains sur votre tableau de bord, ou demandez-les.
GET https://api.timtim.live/v1/earnings

Obtenir ma clé test Essayer sans clé

Statut de TimTim.Live

Référence

Où envoyer les demandes

https://api.timtim.live/v1

Votre clé de connexion

Envoyez votre clé dans l'en-tête Authorization. Les clés test (tt_test_) ne voient que des événements d'exemple. Les clés site web (tt_pk_live_) peuvent être dans une page web et ne lisent que les événements. Les clés serveur (tt_sk_live_) restent sur votre serveur et peuvent aussi lire les gains. Nous montrons une clé une seule fois — gardez-la bien.

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

Filtres

city: Événements dans cette ville.
country: Code pays à deux lettres, par exemple US.
category: Par exemple musique, festival ou conférence.
from: Événements à cette date ou après (2026-10-20).
to: Événements à cette date ou avant.
changed_since: Seulement les événements qui ont changé après ce moment.
commissioned: true = seulement les événements qui donnent une récompense.
minimum_earnings: Seulement les événements qui rapportent au moins ce montant par billet.
near: Un lieu, par exemple near=Paris,FR.
limit: Nombre d'événements par page, de 1 à 100 (20 si vous ne mettez rien).

Dites-moi seulement ce qui a changé

Gardez l'heure de votre dernière synchro et envoyez-la dans changed_since. Vous recevez seulement les événements qui ont changé — y compris les annulations et les concerts complets. Pas besoin de webhook. Les événements que vous devez cesser d'afficher arrivent dans la liste withdrawn.

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

Plus d'une page

Si la réponse contient next, renvoyez-le avec cursor= pour avoir la page suivante. Quand next est vide, vous avez tout.

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

Gains

Chaque événement a earn. Si earn.eligible vaut false, l'événement n'a pas de récompense — il vaut quand même la peine d'être montré. S'il vaut true, earn.description dit ce que vous gagnez, par exemple « $5 par billet éligible ». Si l'achat est remboursé, la récompense est annulée.

Flux complets (tout dans un seul fichier)

Enregistrez un flux complet sur votre tableau de bord, puis téléchargez tous ses événements dans un seul fichier compressé : GET /v1/bulk/FEED_ID.ndjson.gz ou .csv.gz, avec votre clé serveur. Ajoutez ?changed_since= pour n'avoir que ce qui a changé, y compris les événements retirés. Les clés test peuvent l'essayer dès maintenant ; l'usage réel demande un examen par TimTim.Live.

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

Vendez des billets dans votre propre app (commerce intégré)

Les grands partenaires peuvent garder les acheteurs dans leur propre app. Demandez GET /v1/events/EVENT_ID/tickets pour voir ce qui est en vente, puis envoyez POST /v1/orders avec le choix de l'acheteur. Vous recevez un lien de paiement TimTim.Live à ouvrir pour l'acheteur ; la vente est créditée directement à votre entreprise. Les clés test peuvent l'essayer dès maintenant. L'usage réel demande une vérification de TimTim.Live et les paiements par carte activés.

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

Offres liées à la carte (banques et programmes de fidélité)

GET /v1/offers donne chaque événement qui paie une récompense sous forme d'offre : l'organisateur, les dates où l'on peut acheter, le prix, le lieu et la récompense. Votre client l'active par votre lien suivi, et la récompense est versée à votre entreprise via /v1/earnings. Les clés test voient des offres d'exemple. Les offres réelles demandent une vérification par TimTim.Live. Relier directement les paiements par carte demande un accord avec un réseau de cartes ou une banque, et ce n'est pas branché.

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

Statut de l'événement et billets

status vaut scheduled, postponed, rescheduled, cancelled, sold_out ou completed. tickets.availability vaut available, limited, sold_out, not_on_sale ou ended. Quand un événement est annulé, retirez-le.

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

À quelle vitesse vous pouvez demander

Clés test : 60 demandes par minute. Clés live : 120 par minute. Plus vite, vous recevez une réponse 429 avec Retry-After, le nombre de secondes à attendre.

Quels événements vous recevez

Les événements que les organisateurs TimTim.Live créent et choisissent de partager. Les événements importés d'autres sites de billets ne sont jamais inclus, car nous n'avons pas le droit de les partager.

Ce que nous n'envoyons jamais

Les noms des acheteurs, les adresses e-mail, les adresses postales, les numéros de téléphone et les données de carte. La Partner API partage des infos sur les événements, pas nos membres.

Widget pour site web

Une seule ligne de HTML montre des événements sur n'importe quel site. Utilisez une clé site web (tt_pk_live_) et ajoutez votre site à la liste des sites autorisés de la clé. Sans clé, il montre des événements d'exemple.

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

Options : data-city, data-country, data-category, data-limit (1–24), data-earn="true", data-lang et data-color.

OAuth 2.0 (grandes intégrations)

Facultatif. Créez un client OAuth sur votre tableau de bord, puis échangez son identifiant client et son secret contre un jeton d'accès d'une heure. Envoyez ce jeton à la place d'une clé. Le secret ne voyage jamais avec vos appels API, et vous pouvez demander moins de droits (scopes) que le client n'en a.

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

Pour arrêter un jeton plus tôt, envoyez-le en POST à /v1/oauth/revoke avec le même identifiant client et le même secret. Désactiver le client sur votre tableau de bord arrête tous ses jetons d'un coup.

Verrouillez une clé sur vos serveurs

Facultatif. Sur votre tableau de bord, ouvrez « Verrouiller sur mes serveurs » sous une clé serveur, une clé test ou un client OAuth, et indiquez les adresses publiques de vos serveurs. Les appels — et les demandes de token — venant d'ailleurs sont refusés avec ip_not_allowed, même avec la bonne clé.

Certificats client (mTLS) : associez votre certificat client TLS à une clé, puis appelez https://api.timtim.live avec lui. Chaque appel doit présenter ce certificat ; la poignée de main TLS prouve que vous détenez sa clé privée.

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

Extension WordPress

Vous utilisez WordPress ? Installez TimTim.Live Events : un bloc et un code court qui montrent des événements avec vos propres liens de billets TimTim.Live. Elle est faite par TimTim.Live, ne parle qu'à timtim.live et ne se met à jour que depuis timtim.live.

Téléversez le fichier dans Extensions → Ajouter → Téléverser une extension. Collez votre clé site web dans Réglages → TimTim.Live Events et appuyez sur Test Connection. Ajoutez ensuite le bloc TimTim.Live Events à n'importe quelle page.

Télécharger l'extension WordPress

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

Flux

Les mêmes événements en JSON Feed, RSS, XML, CSV ou en calendrier (.ics) auquel Google Calendar, Apple Calendar et Outlook peuvent s'abonner. Les lecteurs de flux ne peuvent pas envoyer d'en-têtes : mettez donc une clé site web ou une clé test dans ?key=. Ne mettez jamais une clé serveur dans un lien.

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

Ajoutez une adresse dans votre tableau de bord et nous lui envoyons un message quand quelque chose change : event.changed ou earnings.changed. Les webhooks sont facultatifs — changed_since vous donne les mêmes informations.

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

Vérifiez chaque message : il est signé avec votre secret. Refusez tout message de plus de cinq minutes, et ignorez un TimTim-Delivery-Id que vous avez déjà traité.

// 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épondez avec n'importe quel 2xx en moins de 10 secondes. Sinon, nous réessayons après 1 minute, 5 minutes, 30 minutes, puis 2, 6, 12 et 24 heures, puis nous arrêtons. Nous ne suivons jamais les redirections.

Le bac à sable

Les clés test reçoivent des événements d'exemple marqués ÉVÉNEMENT TEST — PAS DE VRAI ARGENT. Ouvrez un buy_url, appuyez sur Acheter un billet test, puis demandez vos gains. Simulez un remboursement et regardez-le s'annuler.

Quand quelque chose ne va pas

Les erreurs s'expliquent avec des mots simples, avec un titre et ce qu'il faut faire ensuite. Chaque réponse porte un TimTim-Request-Id. Envoyez-le-nous et nous pourrons retrouver votre demande.

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.

Le contrat

La description complète de chaque champ, au format OpenAPI que vos outils savent lire.

Télécharger openapi.yaml

Comment s'ouvrent les clés réelles

Votre clé test marche tout de suite. Pour les clés réelles, une personne de TimTim.Live regarde le nom de votre entreprise, votre site web et la façon dont vous allez montrer les événements. Vous voyez la réponse sur votre tableau de bord.

Nouveautés de l'API TimTim.Live

La version 1 ne fait que grandir. Nous ajoutons des choses. Nous ne retirons rien et ne renommons rien de ce qui existe déjà.

2026-10-08 — Les réponses sur les événements portent maintenant un ETag. Renvoyez-le dans If-None-Match pour recevoir un 304 rapide quand rien n'a changé. Facultatif.
2026-10-08 — Les clés de site web comptent désormais chaque visiteur séparément, pour que les sites très fréquentés continuent de fonctionner. Rien à faire de votre côté.
2026-10-07 — Les certificats client (mTLS) sont ouverts : liez votre certificat à une clé sur votre tableau de bord. Facultatif. Rien à faire de votre côté.
2026-10-07 — Flux complets : tous les événements que vous pouvez montrer, dans un seul fichier, sur GET /v1/bulk. Facultatif. Rien à faire de votre côté.
2026-10-07 — L'API a sa propre adresse : https://api.timtim.live/v1. https://timtim.live/v1 continue de fonctionner. Aucune action requise.
2026-10-06 — Votre propre page de paiement, à votre image, sur timtim.live/checkout. Facultatif. Rien à faire de votre côté.
2026-10-06 — Vendez des billets dans votre propre appli : GET /v1/events/EVENT_ID/tickets et POST /v1/orders. Facultatif. Rien à faire de votre côté.
2026-10-06 — Une page de statut publique sur /partners/status, vérifiée chaque minute. Rien à faire de votre côté.
2026-10-06 — Relevés mensuels pour les entreprises : GET /v1/settlements. Rien à faire de votre côté.
2026-10-06 — Postbacks : ajoutez ?sub_id= à un lien d'achat et nous vous le renvoyons avec la vente. Facultatif. Rien à faire de votre côté.
2026-10-06 — Offres liées à la carte pour les banques et les programmes de fidélité : GET /v1/offers. Facultatif. Rien à faire de votre côté.
2026-10-06 — Flux calendrier : /v1/feeds/events.ics pour Google Calendar, Apple Calendar et Outlook. Rien à faire.
2026-10-06 — Verrouillez une clé sur vos serveurs : listes d'IP autorisées dès maintenant, certificats client (mTLS) sur api.timtim.live. Facultatif. Rien à faire.
2026-10-06 — Identifiants client OAuth 2.0 pour les grandes intégrations : POST /v1/oauth/token et /v1/oauth/revoke. Les clés marchent toujours. Rien à faire de votre côté.
2026-10-06 — Extension WordPress 1.0.0 : un bloc, un code court et une page de réglages. Elle se met à jour toute seule depuis timtim.live. Rien à faire de votre côté.
2026-10-06 — Widget pour site web, flux JSON/RSS/XML/CSV et webhooks (event.changed, earnings.changed). Rien à faire de votre côté.
2026-10-06 — Partner API v1 : les événements, un événement, les gains et le bac à sable. Rien à faire de votre côté.