TapTime REST API

Әр сұрауға Authorization: Bearer tt_live_… түрінде компанияның API кілті (панельдегі Интеграциялар → Вебхуктар және API) қажет. Жауаптар мен қателер JSON пішімінде.

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

Аутентификация

Әр сұрау компанияның API кілтін bearer токен ретінде жібереді. Кілтті панельдегі Интеграциялар → Вебхуктар және API → REST API кілттері бөлімінде жасаңыз: ол тек бір рет көрсетіледі және серверде тек SHA-256 хэші ретінде сақталады; жоғалған кілт қалпына келтірілмейді — оның күші жойылып, жаңасымен ауыстырылады. Компанияда 10-ға дейін белсенді кілт болуы мүмкін.

• Тек оқуға арналған кілттер барлық GET эндпоинттарын шақыра алады, сондай-ақ вебхуктарға жазылып, жазылымнан шыға алады — жазылым кілт өзі оқи алмайтын ештеңені жібермейді.
• Оқу және жазу кілттері бұған қоса брондау күйін POST арқылы өзгерте алады; тек оқуға арналған кілт бұл маршруттарда 403 Forbidden жауабын алады.
• Кілт бір компанияға тиесілі — әр тізім мен сұрау сол компаниямен шектелген, companyId параметрі жоқ.

Сұрау шектері

Әр кілтке минутына 50 сұрау, сырғымалы терезе бойынша, барлық эндпоинттарға ортақ. Шектен асса, 429 Too Many Requests қайтарылады; жиірек сұраудың орнына біраз күтіп, қайталап көріңіз — немесе вебхукқа жазылып, сұрауды мүлде тоқтатыңыз.

Эндпоинттар

Брондау объектісі

Үстел брондауы мен жазылу бір ортақ пішінде қайтарылады: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (филиалдың өз уақыт белдеуі), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt — оған қоса үстел брондауында partySize және table, жазылуда service және specialist. Бұл дәл вебхук жеткізетін дерек, сондықтан біреуін өңдей алатын қабылдағыш екеуін де өңдейді.

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

Тапсырыс объектісі

Тапсырыс қай жерде кездессе де — REST API, тапсырыс вебхуктары немесе оқиғалар ағыны — бір пішінде қайтарылады: kind ("order"), id, number (қызметкерлер шақыратын чек нөмірі), status (open немесе paid), source (customer немесе staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (қызметкер анықтаса, адалдық бағдарламасының мүшесі), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (шайпұлсыз тапсырыс құны — конверсияларда жіберілетін сан), paymentMethod, servedBy, conversionId, createdAt, paidAt және attribution. Ақша сомалары әрдайым ұсақ бірліктермен (тиынмен) беріледі.

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

Адалдық объектісі

Әр адалдық оқиғасы, картасы және сыйақысы бір пішінге ие: kind ("loyalty"), id (карта), timezone, company, branch (оқиға болған жер, егер бар болса), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (мөр үшін: source, issuedBy, createdAt) және reward (сыйақы үшін: code, title, status, expiresAt, redeemedAt, redeemedBy), сондай-ақ conversionId — адалдыққа тіркелу осы 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…"
}

Оқиғалар ағыны

Әр жол: { id, cursor, type, createdAt, previousStatus, data }. data оқиға префиксі атаған кілттің астында нысанды сақтайды: data.booking, data.order немесе data.loyalty. Өңделген ең үлкен курсорыңызды сақтап, оны after ретінде қайтарыңыз — ол ешқашан жолды өткізіп жібермейді және қайталамайды, сондықтан іркілістен кейін қауіпсіз жалғастыруға болады. Өзіңіз өңдемейтін түрлерді елемеңіз: жаңалары қосылуы мүмкін.

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

Вебхуктар

Интеграциялар → Вебхуктар және API бөлімінде эндпоинт жасаңыз — немесе Интеграциялар → Автоматтандыру бөлімінде Zapier, Make, n8n не Pipedream қосыңыз — сонда брондау, тапсырыс немесе адалдық картасы өзгерген сәтте TapTime қолтаңбасы бар JSON оқиғасын POST етеді. Оқиғаларды әр эндпоинт үшін бөлек таңдайсыз. Компанияда барлығы 50-ге дейін вебхук, постбэк, чат және автоматтандыру қосылымы болуы мүмкін.

• Кез келген 2xx жауабы жеткізілді деп есептеледі; 2xx емес жауап немесе timeout аралықты ұлғайта отырып (1 мин, 5 мин, 15 мин, 1 сағ, 3 сағ, 6 сағ, 12 сағ) 8 ретке дейін қайталанады — 410 қайталауды тоқтатады.
• Қайта бағыттауларға өтпейді.
• Production ортасында URL HTTPS болуы тиіс және жеке немесе loopback мекенжайға бағытталмауы керек.
• Жеткізу кемінде бір рет кепілдендіріледі: қолтаңбаны әрқашан тексеріп, телнұсқаларды 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));

Вебхук жазылымдары

Автоматтандыру платформалары пайдаланушыдан URL қоюды сұраудың орнына триггерлерді API арқылы қосып-өшіреді («REST hooks»): платформаның өз URL мекенжайын қажетті оқиғалармен POST етіңіз, қайтарылған id-ді сақтаңыз және триггер өшірілгенде оны DELETE етіңіз. Жазылым — қолтаңбасы бар кәдімгі вебхук: ол панельде өзін жасаған кілттің белгісімен көрінеді.

• Кілт тек өзі жасаған жазылымдарды көріп, өшіре алады; кілттің күші жойылса, олардың бәрі өшіріледі.
• hooks.zapier.com, make.com және pipedream.net мекенжайлары танылады және платформа атауымен көрсетіледі; кез келген басқа https мекенжай кәдімгі вебхук болып саналады.
• Қолтаңба кілті POST жауабында бір рет қайтарылады; иесі оны панельде қайта көре алады.

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

Постбэктер

JSON вебхуктардың орнына query-string постбэктермен жұмыс істейтін платформалар үшін трекеріңіздің өз URL мекенжайына макростары толтырылған GET немесе POST сұрауы. Тапсырыс үшін {value} — шайпұлсыз тапсырыс құны, ал {order_id} — оның id-і.

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

Қолжетімді айнымалылар

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

Қателер

Әр қате JSON түрінде: { "error": "<code>", "message": "<human-readable>" }.