TapTime REST API

Her istek için bir şirket API anahtarı (paneldeki Entegrasyonlar → Webhook'lar ve API) “Authorization: Bearer tt_live_….” biçiminde gönderilmelidir. Yanıtlar ve hata mesajları JSON biçimindedir.

curl "https://api.tapti.me/v1/company/reservations?status=confirmed&updatedSince=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer tt_live_…"

Kimlik Doğrulama

Her istek, taşıyıcı belirteci olarak bir şirket API anahtarı içerir. Panelden bir tane oluşturun — Entegrasyonlar → Webhook’lar ve API → REST API anahtarları — burada anahtar yalnızca bir kez gösterilir ve sunucu tarafında sadece SHA-256 şeklinde bir hash olarak saklanır; kaybolan bir anahtar geri alınmaz, iptal edilir ve yenisiyle değiştirilir. Bir şirket en fazla 10 aktif anahtar bulundurabilir.

• Salt okunur anahtarlar tüm GET uç noktalarını çağırabilir, ayrıca webhook abonelikleri oluşturup kaldırabilir — bir abonelik, anahtarın zaten okuyamayacağı hiçbir şeyi göndermez.
• Okuma-yazma anahtarları ayrıca POST ile rezervasyon durumunu değiştirebilir; salt okunur bir anahtar bu yollarda 403 Forbidden alır.
• Bir anahtar tek bir şirkete aittir — her liste ve sorgu zaten o şirketle sınırlıdır; companyId parametresi yoktur.

Hız sınırları

Anahtar başına dakikada 50 istek, kayan pencereyle ve tüm uç noktalar için ortak. Sınır aşılırsa 429 Too Many Requests döner; daha sık sorgulamak yerine bekleyip yeniden deneyin — ya da bir webhook aboneliği oluşturup sorgulamayı bırakın.

Uç Noktalar

Rezervasyon nesnesi

Bir rezervasyon ve bir randevu, tek bir ortak formda gösterilir: tür, kimlik, durum, kaynak, guestInitiated, startsAt/endsAt/zaman dilimi (şubenin kendi zaman dilimi), para birimi, şirket, şube, misafir, atıf, conversionId, createdAt/updatedAt — ayrıca rezervasyon için partySize ve tablo; randevu için ise hizmet ve uzman bilgileri. Bu, bir webhook'un ilettiği verilerle tam olarak aynıdır; dolayısıyla bunlardan birini işleyen bir alıcı, her ikisini de işleyebilir.

{
  "data": {
    "kind": "reservation",
    "id": 4821,
    "status": "confirmed",
    "source": "online",
    "guestInitiated": true,
    "startsAt": "2026-09-12T20:00:00+03:00",
    "endsAt": "2026-09-12T21:30:00+03:00",
    "timezone": "Asia/Baku",
    "currency": "AZN",
    "company": { "id": 12, "name": "Cafe Aroma", "slug": "cafe-aroma", "country": "AZ" },
    "branch": { "id": 3, "name": "Nizami st." },
    "partySize": 4,
    "table": { "id": 9, "label": "T3" },
    "guest": { "name": "Maria K.", "phone": "…", "email": "…" },
    "locale": "en",
    "note": null,
    "conversionId": "tt3f9c…",
    "createdAt": "2026-09-10T08:12:04+00:00",
    "updatedAt": "2026-09-12T20:00:03+00:00",
    "attribution": { "channel": "widget", "utmSource": "instagram", "gclid": null, "fbclid": "IwAR2…" }
  }
}

Sipariş nesnesi

Bir sipariş, nerede karşınıza çıkarsa çıksın — REST API, sipariş webhook’ları, etkinlik akışı — tek bir biçimde gelir: kind ("order"), id, number (personelin seslendiği fiş numarası), status (open veya paid), source (customer veya staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (personel tanımladıysa sadakat üyesi), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (siparişin bahşiş hariç değeri — dönüşümlerin raporladığı sayı), paymentMethod, servedBy, conversionId, createdAt, paidAt ve attribution. Tutarlar her zaman küçük birim cinsindendir (kuruş).

{
  "data": {
    "kind": "order",
    "id": 9170,
    "number": 42,
    "status": "paid",
    "source": "customer",
    "guestInitiated": true,
    "fulfilment": "takeaway",
    "table": null,
    "label": "Ana",
    "currency": "EUR",
    "branch": { "id": 3, "name": "Vitosha Blvd" },
    "customer": { "id": 311, "name": "Ana", "phone": "…" },
    "items": [
      { "menuItemId": 88, "name": "Flat white", "variant": "Large",
        "quantity": 2, "unitPriceCents": 450, "subtotalCents": 900 }
    ],
    "itemCount": 2,
    "subtotalCents": 900,
    "discountCents": 0,
    "deliveryFeeCents": 0,
    "tipCents": 100,
    "totalCents": 1000,
    "valueCents": 900,
    "paymentMethod": "online",
    "conversionId": "tt81ad…",
    "createdAt": "2026-09-12T12:04:10+03:00",
    "paidAt": "2026-09-12T12:05:02+03:00",
    "attribution": { "channel": "web", "utmSource": "google", "gclid": "Cj0K…" }
  }
}

Sadakat nesnesi

Her sadakat etkinliği, kartı ve ödülü aynı biçimi paylaşır: kind ("loyalty"), id (kart), timezone, company, branch (varsa gerçekleştiği şube), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (damga için: source, issuedBy, createdAt) ve reward (ödül için: code, title, status, expiresAt, redeemedAt, redeemedBy), ayrıca conversionId — sadakat kaydının raporlandığı kimlik.

{
  "kind": "loyalty",
  "id": 5120,
  "program": { "id": 4, "name": "Coffee card", "stampsRequired": 8, "rewardTitle": "Free coffee" },
  "customer": { "id": 311, "name": "Ana", "phone": "…", "locale": "bg" },
  "card": { "id": 5120, "status": "active", "stampsCount": 5,
            "stampsRequired": 8, "stampsToReward": 3 },
  "branch": { "id": 3, "name": "Vitosha Blvd" },
  "stamp": { "source": "qr_scan", "issuedBy": "Ivan", "createdAt": "…" },
  "reward": null,
  "conversionId": "tt5c02…"
}

Etkinlik akışı

Her satır { id, cursor, type, createdAt, previousStatus, data } biçimindedir. data, konuyu etkinliğin önekinin adlandırdığı anahtar altında taşır: data.booking, data.order veya data.loyalty. İşlediğiniz en yüksek cursor değerini saklayın ve after olarak geri gönderin — hiçbir satırı atlamaz veya tekrarlamaz, bu yüzden bir çökmeden sonra kaldığınız yerden devam etmek güvenlidir. İşlemediğiniz türleri yok sayın: yenileri eklenebilir.

curl "https://api.tapti.me/v1/company/events?after=998&limit=100" \
  -H "Authorization: Bearer tt_live_…"

Webhook'lar

Entegrasyonlar → Webhook’lar ve API altında bir uç nokta oluşturun — ya da Entegrasyonlar → Otomasyon altında Zapier, Make, n8n veya Pipedream bağlayın — böylece bir rezervasyon, sipariş veya sadakat kartı değiştiği anda TapTime imzalı bir JSON etkinliğini POST ile göndersin. Etkinlikleri her uç nokta için ayrı seçersiniz. Bir şirketin toplamda en fazla 50 webhook, postback, sohbet ve otomasyon bağlantısı olabilir.

• 2xx serisi yanıtlar, isteklerin ulaştığı kabul edilir; 2xx serisi dışındaki yanıtlar veya zaman aşımı durumlarında, geri çekilme aralıkları (1 dk, 5 dk, 15 dk, 1 saat, 3 saat, 6 saat, 12 saat) uygulanarak en fazla 8 deneme yapılır — 410 yanıtı geldiğinde denemeler durdurulur.
• Yönlendirmeler takip edilmez.
• Üretim ortamında URL’nin HTTPS olması gerekir ve özel bir adrese ya da döngü gerisi adresine yönlendirilmemelidir.
• Teslimat en az bir kez yapılır: her zaman imzayı doğrulayın ve TapTime-Event-Id değerinde yinelenenleri ayıklayın.

{
  "id": "evt_9f3c2a7e1b",
  "type": "booking.confirmed",
  "createdAt": "2026-09-12T19:02:11+03:00",
  "test": false,
  "data": { "booking": { "kind": "reservation", "id": 4821, "status": "confirmed", "…": "…" } }
}

const [t, v1] = req.headers["taptime-signature"]
  .split(",").map(part => part.split("=")[1]);
const expected = crypto
  .createHmac("sha256", process.env.TAPTIME_WEBHOOK_SECRET)
  .update(`${t}.${rawBody}`)
  .digest("hex");
const valid = crypto.timingSafeEqual(
  Buffer.from(expected), Buffer.from(v1));

Webhook abonelikleri

Otomasyon platformları, kullanıcıdan URL yapıştırmasını istemek yerine tetikleyicileri API üzerinden açıp kapatır (“REST hooks”): platformun kendi URL’sini istediği etkinliklerle POST edin, dönen id’yi saklayın ve tetikleyici kapatıldığında DELETE ile silin. Abonelik sıradan bir imzalı webhook’tur — panelde, onu oluşturan anahtarla işaretlenmiş olarak görünür.

• Bir anahtar yalnızca kendi oluşturduğu abonelikleri görür ve kaldırır; anahtar iptal edilirse hepsi kaldırılır.
• hooks.zapier.com, make.com ve pipedream.net adresleri tanınır ve platformun adıyla gösterilir; diğer tüm https adresleri sıradan webhook’lardır.
• İmzalama anahtarı bir kez, POST yanıtında döndürülür; hesap sahibi onu panelde yeniden görüntüleyebilir.

curl -X POST "https://api.tapti.me/v1/company/webhooks" \
  -H "Authorization: Bearer tt_live_…" -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.zapier.com/hooks/catch/123/abc/", "events": ["order.placed"]}'

Postback'ler

JSON webhook’lar yerine sorgu dizesi (query string) postback’leri kullanan platformlar için, makroları doldurulmuş olarak takip aracınızın kendi URL’sine bir GET veya POST isteği. Bir siparişte {value} siparişin bahşiş hariç değeri, {order_id} ise kimliğidir.

https://tracker.example/postback
  ?cid={click_id}&event={event}&status={status}
  &payout={value}&cur={currency}

Kullanılabilir yer tutucular

• {event}
• {event_id}
• {status}
• {booking_id}
• {booking_type}
• {order_id}
• {customer_id}
• {conversion_id}
• {value}
• {currency}
• {party_size}
• {branch_id}
• {timestamp}
• {utm_source}
• {utm_medium}
• {utm_campaign}
• {utm_term}
• {utm_content}
• {gclid}
• {fbclid}
• {msclkid}
• {ttclid}
• {click_id}

Hatalar

Her hata JSON biçimindedir: { "error": "<code>", "message": "<human-readable>" }.