TapTime REST API

Hər bir sorğu şirkətin API açarına (paneldə Integrasiyalar → Webhooks & API) Authorization: Bearer tt_live_…. kimi göndərilməlidir. Cavablar və xətalar JSON formatındadır.

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

Təsdiq

Hər bir sorğu şirkətin API açarını daşıyıcı token kimi daşıyır. Paneldən — Integrations → Webhooks & API → REST API açarları — bölməsində birini yaradın; orada açar yalnız bir dəfə göstərilir və yalnız server tərəfində SHA-256 həş kimi saxlanılır; itirilmiş açar ləğv edilir və əvəzlənir, bərpa edilmir. Bir şirkət maksimum 10 aktiv açar saxlaya bilər.

• Yalnız oxuma açarları bütün GET son nöqtələrini çağıra, həmçinin webhook-lara abunə ola və abunəliyi ləğv edə bilər — abunəlik açarın onsuz da oxuya bilmədiyi heç nəyi göndərmir.
• Oxuma-yazma açarları həmçinin rezervasiya statusunu POST ilə dəyişə bilər; yalnız oxuma açarı bu marşrutlarda 403 Forbidden alır.
• Açar bir şirkətə məxsusdur — hər siyahı və sorğu artıq həmin şirkətlə məhdudlaşır, companyId parametri yoxdur.

Sürət məhdudiyyətləri

Hər açar üçün dəqiqədə 50 sorğu, sürüşən pəncərə üzrə, bütün son nöqtələr üçün ümumi. Limiti aşdıqda 429 Too Many Requests qaytarılır; sorğuları sıxlaşdırmaq əvəzinə gözləyib yenidən cəhd edin — və ya webhook-a abunə olub sorğulamanı dayandırın.

Son nöqtələr

Rezervasiya obyekti

Sifariş və görüş eyni ortaq strukturda təqdim olunur: kind, id, status, source, guestInitiated, startsAt/endsAt/vaxt zonası (filialın öz zonası), valyuta, şirkət, filial, qonaq, atribut, conversionId, createdAt/updatedAt — üstəlik rezervasiya üçün partySize və cədvəl, görüş üçün xidmət və mütəxəssis. Bu, məhz bir webhook-un çatdırdığı məlumatdır, ona görə də birini qəbul edən alıcı hər ikisini qəbul edə bilir.

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

Sifariş obyekti

Sifariş harada rast gəlsəniz — REST API, sifariş webhook-ları, hadisə axını — bir formada gəlir: kind ("order"), id, number (əməkdaşların səsləndirdiyi çek nömrəsi), status (open və ya paid), source (customer və ya staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (əməkdaş müəyyən etdikdə loyallıq üzvü), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (sifarişin çaypulu olmadan dəyəri — konversiyaların bildirdiyi rəqəm), paymentMethod, servedBy, conversionId, createdAt, paidAt və attribution. Məbləğlər həmişə kiçik vahidlərlə (qəpiklə) göstərilir.

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

Loyallıq obyekti

Hər loyallıq hadisəsi, kartı və mükafatı eyni formadadır: kind ("loyalty"), id (kart), timezone, company, branch (hadisənin baş verdiyi filial, əgər varsa), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (möhür üçün: source, issuedBy, createdAt) və reward (mükafat üçün: code, title, status, expiresAt, redeemedAt, redeemedBy), üstəlik conversionId — loyallıq qeydiyyatının bildirildiyi ID.

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

Hadisə axını

Hər sətir { id, cursor, type, createdAt, previousStatus, data } formasındadır. data mövzunu hadisənin prefiksinin adlandırdığı açar altında saxlayır: data.booking, data.order və ya data.loyalty. Emal etdiyiniz ən böyük cursor-u saxlayın və onu after kimi geri ötürün — o heç vaxt sətri ötürüb keçmir və ya təkrarlamır, ona görə də çökmədən sonra davam etmək təhlükəsizdir. Emal etmədiyiniz növlərə məhəl qoymayın: yeniləri əlavə oluna bilər.

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

Webhook-lar

İnteqrasiyalar → Webhook və API bölməsində endpoint yaradın — və ya İnteqrasiyalar → Avtomatlaşdırma bölməsində Zapier, Make, n8n ya da Pipedream qoşun — ki, rezervasiya, sifariş və ya loyallıq kartı dəyişən anda TapTime imzalanmış JSON hadisəsini POST ilə göndərsin. Hadisələri hər endpoint üçün ayrıca seçirsiniz. Bir şirkətdə cəmi 50-yə qədər webhook, postback, çat və avtomatlaşdırma bağlantısı ola bilər.

• Hər hansı 2xx cavabı çatdırılmış sayılır; 2xx olmayan cavab və ya vaxt bitməsi geri çəkilmə intervalları (1 dəq, 5 dəq, 15 dəq, 1 saat, 3 saat, 6 saat, 12 saat) ilə 8 cəhdədək yenidən cəhd edilir — 410 xətası yenidən cəhd etməyi dayandırır.
• Yönləndirmələr izlənilmir.
• URL istehsalat mühitində HTTPS olmalıdır və şəxsi və ya loopback ünvana yönəlməməlidir.
• Çatdırılma ən azı bir dəfədir: həmişə imzoyu və TapTime-Event-Id üzrə təkrarları yoxlayı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 abunəlikləri

Avtomatlaşdırma platformaları istifadəçidən URL yapışdırmağı istəmək əvəzinə tətikləri API vasitəsilə yandırıb-söndürür (“REST hooks”): platformanın öz URL-ini istədiyi hadisələrlə POST edin, qaytarılan id-ni saxlayın və tətik söndürüləndə onu DELETE edin. Abunəlik adi imzalanmış webhook-dur — paneldə onu yaradan açarla işarələnmiş şəkildə görünür.

• Açar yalnız özünün yaratdığı abunəlikləri görür və silir; açar ləğv edildikdə hamısı silinir.
• hooks.zapier.com, make.com və pipedream.net ünvanları tanınır və platformanın adı ilə göstərilir; istənilən digər https ünvanı adi webhook-dur.
• İmza sirri bir dəfə, POST cavabında qaytarılır; sahib onu paneldə yenidən görə bilər.

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-lər

Makroları doldurulmuş şəkildə trekerinizin öz URL-inə GET və ya POST sorğusu — JSON webhook-lar əvəzinə sorğu sətri (query string) postback-ləri ilə işləyən platformalar üçün. Sifarişdə {value} sifarişin çaypulu olmadan dəyəri, {order_id} isə onun id-sidir.

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

Mövcud 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}

Səhvlər

Hər bir səhv JSON-dur: { "error": "<code>", "message": "<human-readable>" }.