REST API TapTime

Setiap permintaan memerlukan kunci API perusahaan (Integrasi → Webhook & API di panel) yang dikirim sebagai Authorization: Bearer tt_live_…. Respons dan kesalahan berbentuk JSON.

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

Autentikasi

Setiap permintaan membawa kunci API perusahaan sebagai token bearer. Buat satu dari panel — Integrasi → Webhook & API → Kunci REST API — di sana kunci ditampilkan sekali dan disimpan di server hanya sebagai hash SHA-256; kunci yang hilang dicabut dan diganti, bukan dipulihkan. Satu perusahaan bisa memegang hingga 10 kunci aktif.

• Kunci baca-saja bisa memanggil setiap endpoint GET, serta berlangganan dan berhenti berlangganan webhook — sebuah langganan tidak mendorong apa pun yang tidak bisa dibaca kunci itu.
• Kunci baca-tulis juga bisa mem-POST perubahan status pemesanan; kunci baca-saja akan mendapat 403 Forbidden pada rute tersebut.
• Satu kunci milik satu perusahaan — setiap daftar dan pencarian sudah dibatasi padanya, tidak ada parameter companyId.

Batas laju

50 permintaan per menit per kunci, pada jendela geser, dipakai bersama oleh setiap endpoint. Melebihinya mengembalikan 429 Too Many Requests; mundur lalu coba lagi alih-alih menjajaki lebih cepat — atau langganan webhook dan berhenti menjajaki.

Endpoint

Objek pemesanan

Reservasi dan janji temu keluar dalam satu bentuk bersama: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (zona cabangnya sendiri), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt — ditambah partySize dan table untuk reservasi, service dan specialist untuk janji temu. Persis itulah yang dikirim sebuah webhook, sehingga penerima yang menangani salah satunya menangani keduanya.

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

Objek pesanan

Sebuah pesanan keluar dalam satu bentuk di mana pun Anda menemuinya — REST API, webhook pesanan, umpan peristiwa: kind ("order"), id, number (nomor tiket yang diteriakkan staf), status (open atau paid), source (customer atau staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (anggota loyalitas, bila staf mengenalinya), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (nilai pesanan tanpa tip — angka yang dilaporkan konversi), paymentMethod, servedBy, conversionId, createdAt, paidAt dan attribution. Uang selalu dalam satuan terkecil.

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

Objek loyalitas

Setiap peristiwa, kartu dan hadiah loyalitas berbagi satu bentuk: kind ("loyalty"), id (kartunya), timezone, company, branch (tempat kejadiannya, bila ada), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (untuk stempel: source, issuedBy, createdAt) dan reward (untuk hadiah: code, title, status, expiresAt, redeemedAt, redeemedBy), ditambah conversionId, id yang dipakai melaporkan pendaftaran loyalitas.

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

Umpan peristiwa

Setiap baris berupa { id, cursor, type, createdAt, previousStatus, data }. data memuat subjeknya di bawah kunci yang dinamai awalan peristiwanya: data.booking, data.order atau data.loyalty. Simpan kursor tertinggi yang sudah Anda proses lalu kirim kembali sebagai after — kursor itu tidak pernah melewati atau mengulang baris, jadi aman untuk melanjutkan setelah kegagalan. Abaikan jenis yang tidak Anda tangani: jenis baru bisa ditambahkan.

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

Webhook

Buat sebuah endpoint di Integrasi → Webhook & API — atau hubungkan Zapier, Make, n8n atau Pipedream di Integrasi → Otomatisasi — agar TapTime mem-POST peristiwa JSON bertanda tangan begitu sebuah pemesanan, pesanan atau kartu loyalitas berubah. Anda memilih peristiwanya per endpoint. Satu perusahaan bisa punya hingga 50 webhook, postback, obrolan dan koneksi otomatisasi secara keseluruhan.

• Respons 2xx apa pun dianggap terkirim; respons non-2xx atau kehabisan waktu dicoba ulang dengan penundaan bertahap (1m, 5m, 15m, 1j, 3j, 6j, 12j) hingga 8 upaya — 410 menghentikan percobaan ulang.
• Pengalihan tidak diikuti.
• URL-nya harus HTTPS di produksi dan tidak boleh mengarah ke alamat privat atau loopback.
• Pengiriman bersifat minimal sekali: selalu verifikasi tanda tangannya dan hapus duplikat berdasarkan TapTime-Event-Id.

{
  "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));

Langganan webhook

Platform otomatisasi mengaktifkan dan mematikan pemicu lewat API alih-alih meminta pengguna menempel URL (“REST hooks”): POST URL milik platform itu beserta peristiwa yang diinginkannya, simpan id yang dikembalikan, lalu DELETE saat pemicunya dimatikan. Sebuah langganan adalah webhook bertanda tangan biasa — tampil di panel, ditandai dengan kunci yang membuatnya.

• Sebuah kunci hanya melihat dan menghapus langganan yang dibuatnya sendiri; mencabut kuncinya menghapus semuanya.
• Alamat di hooks.zapier.com, make.com dan pipedream.net dikenali dan ditampilkan dengan nama platformnya; alamat https lain menjadi webhook biasa.
• Rahasia penanda tangan dikembalikan sekali, dalam respons POST; pemiliknya bisa menampilkannya lagi di panel.

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

Sebuah GET atau POST ke URL pelacak Anda sendiri dengan makro yang sudah diisi, untuk platform yang memakai postback query-string alih-alih webhook JSON. Untuk sebuah pesanan, {value} adalah nilai pesanan tanpa tip dan {order_id} adalah id-nya.

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

Placeholder yang tersedia

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

Kesalahan

Setiap kesalahan berupa JSON: { "error": "<kode>", "message": "<terbaca manusia>" }.