Partner API — Inicio rápido

Tu primera integración cabe en una sola pantalla.

Pruébalo ahora — sin clave, sin registrarte

Abre esta dirección en tu navegador. Verás eventos de ejemplo enseguida.

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

1
Consigue una clave de prueba
Inicia sesión, dinos quién eres y pulsa Crear clave de prueba. Empieza por tt_test_ y solo ve eventos de ejemplo.

Busca eventos

Pide los eventos de una ciudad.

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

3
Muestra el evento
Cada evento tiene nombre, fecha, lugar, imagen, precio y textos listos para tu tarjeta.
4
Usa el buy_url
Usa el buy_url que te damos. Eso es todo. TimTim.Live se encarga de la atribución dentro de ese enlace.
5
Mira los resultados
Mira las personas enviadas, las entradas vendidas y las ganancias en tu panel, o pídelas.
GET https://api.timtim.live/v1/earnings

Conseguir mi clave de prueba Probar sin clave

Estado de TimTim.Live

Referencia

Dónde enviar las peticiones

https://api.timtim.live/v1

Tu clave de conexión

Envía tu clave en la cabecera Authorization. Las claves de prueba (tt_test_) solo ven eventos de ejemplo. Las claves de sitio web (tt_pk_live_) pueden ir en una página web y solo leen eventos. Las claves de servidor (tt_sk_live_) se quedan en tu servidor y también pueden leer ganancias. Mostramos cada clave una sola vez — guárdala 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;
}

Filtros

city: Eventos en esta ciudad.
country: Código de país de dos letras, por ejemplo US.
category: Por ejemplo música, festival o conferencia.
from: Eventos en esta fecha o después (2026-10-20).
to: Eventos en esta fecha o antes.
changed_since: Solo eventos que cambiaron después de este momento.
commissioned: true = solo eventos que dan una recompensa.
minimum_earnings: Solo eventos que pagan al menos esta cantidad por entrada.
near: Un lugar, por ejemplo near=Paris,FR.
limit: Cuántos eventos por página, de 1 a 100 (20 si no pones nada).

Dime solo lo que cambió

Guarda la hora de tu última sincronización y envíala como changed_since. Recibes solo los eventos que cambiaron — incluidas las cancelaciones y los eventos agotados. No necesitas webhook. Los eventos que debes dejar de mostrar llegan en la lista withdrawn.

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

Más de una página

Si la respuesta trae next, devuélvelo como cursor= para recibir la página siguiente. Cuando next está vacío, ya lo tienes todo.

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

Ganancias

Cada evento tiene earn. Si earn.eligible es false, el evento no tiene recompensa — aun así vale la pena mostrarlo. Si es true, earn.description dice lo que recibes, por ejemplo "$5 por entrada válida". Si la compra se reembolsa, la recompensa se anula.

Feeds masivos (todo en un archivo)

Guarda un feed masivo en tu panel y luego descarga todos sus eventos en un solo archivo comprimido: GET /v1/bulk/FEED_ID.ndjson.gz o .csv.gz, con tu clave de servidor. Añade ?changed_since= para recibir solo lo que cambió, incluidos los eventos retirados. Las claves de prueba ya pueden probarlo; el uso real necesita una revisión de TimTim.Live.

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

Vende entradas en tu propia app (comercio integrado)

Los socios grandes pueden mantener a los compradores en su propia app. Pide GET /v1/events/EVENT_ID/tickets para ver qué está a la venta y luego envía POST /v1/orders con la elección del comprador. Recibes un enlace de pago de TimTim.Live para abrirlo al comprador; la venta se acredita directamente a tu empresa. Las claves de prueba pueden probarlo ya. El uso real necesita una revisión de TimTim.Live y los pagos con tarjeta activados.

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

Ofertas vinculadas a tarjetas (bancos y programas de recompensas)

GET /v1/offers da cada evento que paga una recompensa como una oferta: el organizador, las fechas en que se puede comprar, el precio, el lugar y la recompensa. Tu cliente la activa con tu enlace con seguimiento, y la recompensa se paga a tu empresa a través de /v1/earnings. Las claves de prueba ven ofertas de muestra. Las ofertas reales necesitan una revisión de TimTim.Live. Emparejar pagos con tarjeta directamente necesita un acuerdo con una red de tarjetas o un banco, y no está conectado.

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

Estado del evento y entradas

status es scheduled, postponed, rescheduled, cancelled, sold_out o completed. tickets.availability es available, limited, sold_out, not_on_sale o ended. Cuando un evento se cancela, quítalo.

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

Qué tan rápido puedes pedir

Claves de prueba: 60 peticiones por minuto. Claves reales: 120 por minuto. Si vas más rápido, recibes una respuesta 429 con Retry-After, los segundos que debes esperar.

Qué eventos recibes

Los eventos que los organizadores de TimTim.Live crean y deciden compartir. Los eventos que importamos de otros sitios de entradas nunca se incluyen, porque no tenemos derecho a compartirlos.

Lo que nunca enviamos

Nombres de compradores, correos electrónicos, direcciones de casa, números de teléfono y datos de tarjeta. La Partner API comparte información de eventos, no a nuestros miembros.

Widget para sitios web

Una sola línea de HTML muestra eventos en cualquier sitio web. Usa una clave de sitio web (tt_pk_live_) y añade tu sitio a la lista de sitios permitidos de la clave. Sin clave, muestra eventos de ejemplo.

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

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

OAuth 2.0 (integraciones grandes)

Opcional. Crea un cliente OAuth en tu panel. Luego cambia su ID de cliente y su secreto por un token de acceso de una hora, y envía ese token en lugar de una clave. El secreto nunca viaja con tus llamadas a la API, y puedes pedir menos permisos (scopes) de los que tiene el cliente.

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

Para terminar un token antes, envíalo por POST a /v1/oauth/revoke con el mismo ID de cliente y secreto. Si apagas el cliente en tu panel, todos sus tokens terminan a la vez.

Bloquea una clave a tus servidores

Opcional. En tu panel, abre "Bloquear a mis servidores" debajo de una clave de servidor, clave de prueba o cliente OAuth y escribe las direcciones públicas de tus servidores. Las llamadas — y las solicitudes de token — desde cualquier otro lugar se rechazan con ip_not_allowed, incluso con la clave correcta.

Certificados de cliente (mTLS): vincula tu certificado de cliente TLS a una clave y luego llama a https://api.timtim.live con él. Cada llamada debe mostrar ese certificado; el handshake TLS demuestra que tienes su clave privada.

# 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 de WordPress

¿Usas WordPress? Instala TimTim.Live Events: un bloque y un shortcode que muestran eventos con tus propios enlaces de entradas de TimTim.Live. Lo hace TimTim.Live, solo habla con timtim.live y solo se actualiza desde timtim.live.

Sube el archivo en Plugins → Añadir nuevo → Subir plugin. Pega tu clave de sitio web en Ajustes → TimTim.Live Events y pulsa Test Connection. Después añade el bloque TimTim.Live Events a cualquier página.

Descargar el plugin de WordPress

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

Feeds

Los mismos eventos en JSON Feed, RSS, XML, CSV o un calendario (.ics) al que se pueden suscribir Google Calendar, Apple Calendar y Outlook. Los lectores de feeds no pueden enviar cabeceras, así que pon una clave de sitio web o una clave de prueba en ?key=. Nunca pongas una clave de servidor en un enlace.

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

Añade una dirección en tu panel y le enviamos un mensaje cuando algo cambia: event.changed o earnings.changed. Los webhooks son opcionales — changed_since te da la misma información.

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

Revisa cada mensaje: está firmado con tu secreto. Rechaza todo lo que tenga más de cinco minutos e ignora un TimTim-Delivery-Id que ya hayas procesado.

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

Responde con cualquier 2xx en menos de 10 segundos. Si no, lo intentamos de nuevo después de 1 minuto, 5 minutos, 30 minutos, luego 2, 6, 12 y 24 horas, y después paramos. Nunca seguimos redirecciones.

El sandbox

Las claves de prueba reciben eventos de ejemplo marcados EVENTO DE PRUEBA — SIN DINERO REAL. Abre un buy_url, pulsa Comprar entrada de prueba y luego pide tus ganancias. Simula un reembolso y mira cómo se anula.

Cuando algo sale mal

Los errores se explican con palabras sencillas, con un título y qué hacer después. Cada respuesta lleva un TimTim-Request-Id. Envíanoslo y podremos encontrar tu petición.

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.

El contrato

La descripción completa de cada campo, en el formato OpenAPI que tus herramientas pueden leer.

Descargar openapi.yaml

Cómo se abren las claves reales

Tu clave de prueba funciona enseguida. Para las claves reales, una persona de TimTim.Live revisa el nombre de tu empresa, tu sitio web y cómo vas a mostrar los eventos. Ves la respuesta en tu panel.

Novedades de la API de TimTim.Live

La versión 1 solo crece. Añadimos cosas nuevas. No quitamos ni cambiamos el nombre de lo que ya existe.

2026-10-08 — Las respuestas de eventos ahora llevan un ETag. Devuélvelo en If-None-Match para recibir un 304 rápido cuando nada haya cambiado. Opcional.
2026-10-08 — Las claves de sitio web ahora cuentan a cada visitante por separado, para que los sitios con mucho tráfico sigan funcionando. No tienes que hacer nada.
2026-10-07 — Los certificados de cliente (mTLS) ya están abiertos: vincula tu certificado a una clave en tu panel. Opcional. No tienes que hacer nada.
2026-10-07 — Feeds masivos: todos los eventos que puedes mostrar, en un solo archivo, en GET /v1/bulk. Opcional. No tienes que hacer nada.
2026-10-07 — La API tiene su propia dirección: https://api.timtim.live/v1. https://timtim.live/v1 sigue funcionando. No hace falta hacer nada.
2026-10-06 — Tu propia página de pago con tu marca en timtim.live/checkout. Opcional. No tienes que hacer nada.
2026-10-06 — Vende entradas en tu propia app: GET /v1/events/EVENT_ID/tickets y POST /v1/orders. Opcional. No tienes que hacer nada.
2026-10-06 — Una página de estado pública en /partners/status, revisada cada minuto. No tienes que hacer nada.
2026-10-06 — Estados de cuenta mensuales para empresas: GET /v1/settlements. No tienes que hacer nada.
2026-10-06 — Postbacks: añade ?sub_id= a un enlace de compra y te lo devolvemos junto con la venta. Opcional. No tienes que hacer nada.
2026-10-06 — Ofertas vinculadas a tarjetas para bancos y programas de recompensas: GET /v1/offers. Opcional. No tienes que hacer nada.
2026-10-06 — Feed de calendario: /v1/feeds/events.ics para Google Calendar, Apple Calendar y Outlook. No tienes que hacer nada.
2026-10-06 — Bloquea una clave a tus servidores: listas de IP permitidas ya, certificados de cliente (mTLS) en api.timtim.live. Opcional. No tienes que hacer nada.
2026-10-06 — Credenciales de cliente OAuth 2.0 para integraciones grandes: POST /v1/oauth/token y /v1/oauth/revoke. Las claves siguen funcionando. No tienes que hacer nada.
2026-10-06 — Plugin de WordPress 1.0.0: un bloque, un shortcode y una página de ajustes. Se actualiza solo desde timtim.live. No tienes que hacer nada.
2026-10-06 — Widget para sitios web, feeds JSON/RSS/XML/CSV y webhooks (event.changed, earnings.changed). No tienes que hacer nada.
2026-10-06 — Partner API v1: eventos, un evento, ganancias y el sandbox. No tienes que hacer nada.