TapTime REST API

Har bir soʻrovga Authorization: Bearer tt_live_… koʻrinishida kompaniya API kaliti (paneldagi Integratsiyalar → Webhooklar va API) kerak. Javoblar va xatolar JSON formatida.

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

Autentifikatsiya

Har bir soʻrov kompaniya API kalitini bearer token sifatida yuboradi. Kalitni paneldagi Integratsiyalar → Webhooklar va API → REST API kalitlari boʻlimida yarating: u faqat bir marta koʻrsatiladi va serverda faqat SHA-256 xeshi sifatida saqlanadi; yoʻqolgan kalit tiklanmaydi — u bekor qilinib, yangisi bilan almashtiriladi. Kompaniyada 10 tagacha faol kalit boʻlishi mumkin.

• Faqat oʻqish kalitlari barcha GET endpointlarini chaqira oladi, shuningdek webhooklarga obuna boʻlishi va obunani bekor qilishi mumkin — obuna kalit oʻzi oʻqiy olmaydigan hech narsani yubormaydi.
• Oʻqish-yozish kalitlari bundan tashqari bron holatini POST orqali oʻzgartira oladi; faqat oʻqish kaliti bu yoʻllarda 403 Forbidden javobini oladi.
• Kalit bitta kompaniyaga tegishli — har bir roʻyxat va soʻrov allaqachon shu kompaniya bilan cheklangan, companyId parametri yoʻq.

Soʻrovlar chegarasi

Har bir kalit uchun daqiqasiga 50 ta soʻrov, siljuvchi oyna boʻyicha, barcha endpointlar uchun umumiy. Chegaradan oshsa, 429 Too Many Requests qaytadi; tezroq soʻrash oʻrniga biroz kutib, qayta urinib koʻring — yoki webhookka obuna boʻlib, soʻrashni butunlay toʻxtating.

Endpointlar

Bron obyekti

Stol broni va qabul bitta umumiy shaklda qaytadi: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (filialning oʻz vaqt zonasi), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt — bundan tashqari stol broni uchun partySize va table, qabul uchun service va specialist. Bu aynan webhook yetkazadigan maʼlumot, shuning uchun bittasini qayta ishlaydigan qabul qiluvchi ikkalasini ham qayta ishlaydi.

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

Buyurtma obyekti

Buyurtma qayerda uchramasin — REST API, buyurtma webhooklari yoki hodisalar oqimi — bitta shaklda qaytadi: kind ("order"), id, number (xodimlar chaqiradigan chek raqami), status (open yoki paid), source (customer yoki staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (xodim aniqlagan boʻlsa, sodiqlik dasturi aʼzosi), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (choychaqasiz buyurtma qiymati — konversiyalarda yuboriladigan raqam), paymentMethod, servedBy, conversionId, createdAt, paidAt va attribution. Pul summalari doimo tiyinlarda (minor units) koʻrsatiladi.

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

Sodiqlik obyekti

Har bir sodiqlik hodisasi, kartasi va mukofoti bitta shaklga ega: kind ("loyalty"), id (karta), timezone, company, branch (hodisa sodir boʻlgan joy, agar boʻlsa), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (muhr uchun: source, issuedBy, createdAt) va reward (mukofot uchun: code, title, status, expiresAt, redeemedAt, redeemedBy), shuningdek conversionId — sodiqlikka qoʻshilish shu id bilan yuboriladi.

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

Hodisalar oqimi

Har bir qator: { id, cursor, type, createdAt, previousStatus, data }. data hodisa prefiksi nomlagan kalit ostida obyektni saqlaydi: data.booking, data.order yoki data.loyalty. Qayta ishlagan eng katta kursoringizni saqlang va uni after sifatida qaytaring — u hech qachon qatorni oʻtkazib yubormaydi yoki takrorlamaydi, shuning uchun nosozlikdan keyin xavfsiz davom ettirish mumkin. Qayta ishlamaydigan turlaringizni eʼtiborsiz qoldiring: yangilari qoʻshilishi mumkin.

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

Webhooklar

Integratsiyalar → Webhooklar va API boʻlimida endpoint yarating — yoki Integratsiyalar → Avtomatlashtirish boʻlimida Zapier, Make, n8n yoki Pipedream’ni ulang — shunda bron, buyurtma yoki sodiqlik kartasi oʻzgargan zahoti TapTime imzolangan JSON hodisasini POST qiladi. Hodisalarni har bir endpoint uchun alohida tanlaysiz. Kompaniyada jami 50 tagacha webhook, postback, chat va avtomatlashtirish ulanishi boʻlishi mumkin.

• Istalgan 2xx javob yetkazilgan deb hisoblanadi; 2xx boʻlmagan javob yoki timeout oraliqni oshirib (1 daq, 5 daq, 15 daq, 1 soat, 3 soat, 6 soat, 12 soat) 8 martagacha qayta yuboriladi — 410 qayta urinishlarni toʻxtatadi.
• Qayta yoʻnaltirishlarga amal qilinmaydi.
• Production muhitida URL HTTPS boʻlishi kerak va xususiy yoki loopback manzilga yoʻnaltirilmasligi kerak.
• Yetkazish kamida bir marta kafolatlanadi: imzoni doimo tekshiring va takrorlarni TapTime-Event-Id boʻyicha tozalang.

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

Avtomatlashtirish platformalari foydalanuvchidan URL qoʻyishni soʻrash oʻrniga trigger’larni API orqali yoqib-oʻchiradi («REST hooks»): platformaning oʻz URL manzilini kerakli hodisalar bilan POST qiling, qaytgan id’ni saqlang va trigger oʻchirilganda uni DELETE qiling. Obuna — oddiy imzolangan webhook: u panelda uni yaratgan kalit belgisi bilan koʻrinadi.

• Kalit faqat oʻzi yaratgan obunalarni koʻradi va oʻchiradi; kalit bekor qilinsa, ularning hammasi oʻchiriladi.
• hooks.zapier.com, make.com va pipedream.net manzillari taniladi va platforma nomi bilan koʻrsatiladi; boshqa har qanday https manzil oddiy webhook hisoblanadi.
• Imzo kaliti bir marta, POST javobida qaytariladi; egasi uni panelda yana koʻrishi mumkin.

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"]}'

Postbacklar

JSON webhooklar oʻrniga query-string postbacklar bilan ishlaydigan platformalar uchun trekeringizning oʻz URL manziliga makroslar toʻldirilgan GET yoki POST soʻrovi. Buyurtma uchun {value} — choychaqasiz buyurtma qiymati, {order_id} esa uning id’si.

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

Mavjud oʻzgaruvchilar

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

Xatolar

Har bir xato JSON koʻrinishida: { "error": "<code>", "message": "<human-readable>" }.