Partner API — Início rápido

Sua primeira integração cabe em uma tela só.

Teste agora — sem chave, sem cadastro

Abra este endereço no seu navegador. Você vai ver eventos de exemplo na hora.

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

1
Pegue uma chave de teste
Entre, conte quem você é e toque em Criar chave de teste. Ela começa com tt_test_ e só vê eventos de exemplo.

Encontre eventos

Peça os eventos de uma cidade.

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

3
Mostre o evento
Cada evento tem nome, data, lugar, imagem, preço e textos prontos para o seu card.
4
Use o buy_url
Use o buy_url que damos a você. Pronto. O TimTim.Live cuida da atribuição dentro desse link.
5
Veja os resultados
Veja pessoas enviadas, ingressos vendidos e ganhos no seu painel, ou peça esses dados.
GET https://api.timtim.live/v1/earnings

Pegar minha chave de teste Testar sem chave

Status do TimTim.Live

Referência

Para onde enviar os pedidos

https://api.timtim.live/v1

Sua chave de conexão

Envie sua chave no cabeçalho Authorization. Chaves de teste (tt_test_) só veem eventos de exemplo. Chaves de site (tt_pk_live_) podem ficar em uma página web e só leem eventos. Chaves de servidor (tt_sk_live_) ficam no seu servidor e também leem ganhos. Mostramos cada chave uma vez só — guarde bem.

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 nesta cidade.
country: Código do país com duas letras, por exemplo US.
category: Por exemplo música, festival ou conferência.
from: Eventos nesta data ou depois (2026-10-20).
to: Eventos nesta data ou antes.
changed_since: Só eventos que mudaram depois deste horário.
commissioned: true = só eventos que pagam recompensa.
minimum_earnings: Só eventos que pagam pelo menos este valor por ingresso.
near: Um lugar, por exemplo near=Paris,FR.
limit: Quantos eventos por página, de 1 a 100 (20 se você não informar).

Só me diga o que mudou

Guarde o horário da sua última sincronização e envie como changed_since. Você recebe só os eventos que mudaram — inclusive cancelamentos e shows esgotados. Não precisa de webhook. Os eventos que você deve parar de mostrar vêm na lista withdrawn.

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

Mais de uma página

Se a resposta tiver next, envie de volta como cursor= para pegar a próxima página. Quando next estiver vazio, você já tem tudo.

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

Ganhos

Cada evento tem earn. Se earn.eligible for false, o evento não tem recompensa — mesmo assim vale a pena mostrar. Se for true, earn.description diz o que você ganha, por exemplo "$5 por ingresso elegível". Se a compra for reembolsada, a recompensa é estornada.

Feeds completos (tudo em um arquivo)

Salve um feed completo no seu painel e depois baixe todos os eventos dele em um só arquivo compactado: GET /v1/bulk/FEED_ID.ndjson.gz ou .csv.gz, com sua chave de servidor. Adicione ?changed_since= para receber só o que mudou, incluindo eventos retirados. Chaves de teste já podem testar; o uso real precisa de uma análise da TimTim.Live.

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

Venda ingressos no seu próprio app (comércio integrado)

Parceiros grandes podem manter os compradores no próprio app. Peça GET /v1/events/EVENT_ID/tickets para ver o que está à venda e depois envie POST /v1/orders com a escolha do comprador. Você recebe um link de pagamento da TimTim.Live para abrir para o comprador; a venda é creditada direto à sua empresa. Chaves de teste já podem experimentar. O uso real precisa de uma revisão da TimTim.Live e de pagamentos com cartão ativados.

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 ao cartão (bancos e programas de recompensas)

GET /v1/offers entrega cada evento que paga uma recompensa como uma oferta: o organizador, as datas em que dá para comprar, o preço, o lugar e a recompensa. Seu cliente ativa a oferta pelo seu link rastreado, e a recompensa é paga à sua empresa por /v1/earnings. Chaves de teste veem ofertas de exemplo. Ofertas reais precisam de uma revisão do TimTim.Live. Ligar pagamentos com cartão diretamente precisa de um acordo com uma bandeira de cartão ou um banco, e não está conectado.

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

Status do evento e ingressos

status é scheduled, postponed, rescheduled, cancelled, sold_out ou completed. tickets.availability é available, limited, sold_out, not_on_sale ou ended. Quando um evento é cancelado, tire ele do ar.

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

Com que rapidez você pode pedir

Chaves de teste: 60 pedidos por minuto. Chaves reais: 120 por minuto. Mais rápido que isso, você recebe uma resposta 429 com Retry-After, o número de segundos para esperar.

Quais eventos você recebe

Os eventos que os organizadores do TimTim.Live criam e escolhem compartilhar. Eventos que importamos de outros sites de ingressos nunca entram, porque não temos o direito de compartilhá-los.

O que nunca enviamos

Nomes de compradores, e-mails, endereços residenciais, telefones e dados de cartão. A Partner API compartilha informações de eventos, não nossos membros.

Widget para sites

Uma só linha de HTML mostra eventos em qualquer site. Use uma chave de site (tt_pk_live_) e coloque seu site na lista de sites permitidos da chave. Sem chave, ele mostra eventos de exemplo.

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

Opções: data-city, data-country, data-category, data-limit (1–24), data-earn="true", data-lang e data-color.

OAuth 2.0 (integrações grandes)

Opcional. Crie um cliente OAuth no seu painel. Depois troque o ID do cliente e o segredo por um token de acesso de uma hora, e envie esse token no lugar de uma chave. O segredo nunca viaja com suas chamadas à API, e você pode pedir menos permissões (scopes) do que o cliente tem.

# 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 encerrar um token antes, envie-o por POST para /v1/oauth/revoke com o mesmo ID do cliente e segredo. Desligar o cliente no seu painel encerra todos os tokens dele de uma vez.

Trave uma chave nos seus servidores

Opcional. No seu painel, abra "Travar nos meus servidores" embaixo de uma chave de servidor, chave de teste ou cliente OAuth e escreva os endereços públicos dos seus servidores. Chamadas — e pedidos de token — de qualquer outro lugar são recusados com ip_not_allowed, mesmo com a chave certa.

Certificados de cliente (mTLS): ligue seu certificado de cliente TLS a uma chave e depois chame https://api.timtim.live com ele. Toda chamada precisa mostrar esse certificado; o handshake TLS prova que você tem a chave privada dele.

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

Usa WordPress? Instale o TimTim.Live Events: um bloco e um shortcode que mostram eventos com seus próprios links de ingressos do TimTim.Live. Ele é feito pelo TimTim.Live, só fala com o timtim.live e só se atualiza pelo timtim.live.

Envie o arquivo em Plugins → Adicionar novo → Enviar plugin. Cole sua chave de site em Configurações → TimTim.Live Events e clique em Test Connection. Depois adicione o bloco TimTim.Live Events a qualquer página.

Baixar o plugin para WordPress

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

Feeds

Os mesmos eventos em JSON Feed, RSS, XML, CSV ou em um calendário (.ics) que o Google Calendar, o Apple Calendar e o Outlook podem assinar. Leitores de feed não conseguem enviar cabeçalhos, então coloque uma chave de site ou uma chave de teste em ?key=. Nunca coloque uma chave de servidor em um link.

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

Coloque um endereço no seu painel e enviamos uma mensagem para ele quando algo muda: event.changed ou earnings.changed. Webhooks são opcionais — changed_since dá a mesma informação.

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

Confira cada mensagem: ela é assinada com o seu segredo. Recuse tudo que tiver mais de cinco minutos e ignore um TimTim-Delivery-Id que você já tratou.

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

Responda com qualquer 2xx em até 10 segundos. Se não, tentamos de novo depois de 1 minuto, 5 minutos, 30 minutos, depois 2, 6, 12 e 24 horas, e então paramos. Nunca seguimos redirecionamentos.

O sandbox

Chaves de teste recebem eventos de exemplo marcados EVENTO DE TESTE — SEM DINHEIRO DE VERDADE. Abra um buy_url, toque em Comprar ingresso de teste e depois peça seus ganhos. Simule um reembolso e veja o estorno.

Quando algo dá errado

Os erros se explicam com palavras simples, com um título e o que fazer em seguida. Toda resposta traz um TimTim-Request-Id. Envie para nós e conseguimos achar seu pedido.

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.

O contrato

A descrição completa de cada campo, no formato OpenAPI que suas ferramentas conseguem ler.

Baixar openapi.yaml

Como as chaves live são liberadas

Sua chave de teste funciona na hora. Para chaves live, uma pessoa do TimTim.Live olha o nome da sua empresa, o seu site e como você vai mostrar os eventos. Você vê a resposta no seu painel.

Novidades da API TimTim.Live

A versão 1 só cresce. Adicionamos coisas novas. Não removemos nem renomeamos o que já existe.

2026-10-08 — As respostas de eventos agora trazem um ETag. Envie-o de volta em If-None-Match para receber um 304 rápido quando nada mudou. Opcional.
2026-10-08 — As chaves de site agora contam cada visitante separadamente, para que sites com muito acesso continuem funcionando. Nenhuma ação necessária.
2026-10-07 — Certificados de cliente (mTLS) estão liberados: vincule seu certificado a uma chave no seu painel. Opcional. Nenhuma ação necessária.
2026-10-07 — Feeds completos: todos os eventos que você pode mostrar, em um só arquivo, em GET /v1/bulk. Opcional. Nenhuma ação necessária.
2026-10-07 — A API tem seu próprio endereço: https://api.timtim.live/v1. https://timtim.live/v1 continua funcionando. Nenhuma ação necessária.
2026-10-06 — Sua própria página de pagamento com a sua marca em timtim.live/checkout. Opcional. Nenhuma ação necessária.
2026-10-06 — Venda ingressos no seu próprio app: GET /v1/events/EVENT_ID/tickets e POST /v1/orders. Opcional. Nenhuma ação necessária.
2026-10-06 — Uma página de status pública em /partners/status, verificada a cada minuto. Nenhuma ação necessária.
2026-10-06 — Extratos mensais para empresas: GET /v1/settlements. Nenhuma ação necessária.
2026-10-06 — Postbacks: adicione ?sub_id= a um link de compra e devolvemos esse valor para você junto com a venda. Opcional. Nenhuma ação necessária.
2026-10-06 — Ofertas ligadas ao cartão para bancos e programas de recompensas: GET /v1/offers. Opcional. Nenhuma ação necessária.
2026-10-06 — Feed de calendário: /v1/feeds/events.ics para Google Calendar, Apple Calendar e Outlook. Nada a fazer.
2026-10-06 — Trave uma chave nos seus servidores: listas de IP permitidos já, certificados de cliente (mTLS) no api.timtim.live. Opcional. Nada a fazer.
2026-10-06 — Credenciais de cliente OAuth 2.0 para integrações grandes: POST /v1/oauth/token e /v1/oauth/revoke. As chaves continuam funcionando. Você não precisa fazer nada.
2026-10-06 — Plugin para WordPress 1.0.0: um bloco, um shortcode e uma página de configurações. Ele se atualiza sozinho pelo timtim.live. Você não precisa fazer nada.
2026-10-06 — Widget para sites, feeds JSON/RSS/XML/CSV e webhooks (event.changed, earnings.changed). Você não precisa fazer nada.
2026-10-06 — Partner API v1: eventos, um evento, ganhos e o sandbox. Você não precisa fazer nada.