TapTime REST API

Ар бир сурам компаниянын API ачкычын (панелдеги Интеграциялар → Webhooks & API) Authorization: Bearer tt_live_…. катары жөнөтүүсү керек. Жооптор жана каталар JSON форматында болот.

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

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

Ар бир сурам компаниянын API ачкычын bearer токени катары камтыйт. Панелден — Интеграциялар → Webhooks & API → REST API ачкычтары — бөлүмүнөн ачкыч түзүңүз; ал бир гана жолу көрсөтүлүп, сервер тарапта гана SHA-256 хэши түрүндө сакталат; жоголгон ачкыч жокко чыгарылып, жаңысы менен алмаштырылат, калыбына келтирилбейт. Компания 10го чейин активдүү ачкычтарды кармап тура алат.

• Окуу үчүн гана ачкычтар бардык GET эндпоинттерин чакырып, вебхуктарга жазылып жана жазылууну жокко чыгара алат — жазылуу ачкыч мурунтан эле окуй албаган эч нерсени жөнөтпөйт.
• Окуу-жазуу ачкычтары брондоонун абалын POST аркылуу да өзгөртө алат; окуу үчүн гана ачкыч ал маршруттарда 403 Forbidden алат.
• Ачкыч бир компанияга таандык — ар бир тизме жана издөө ага мурунтан эле чектелген, companyId параметри жок.

Квота чектөөлөрү

Ар бир ачкычка мүнөтүнө 50 сурам, жылма терезе менен, бардык эндпоинттерге жалпы. Чектен ашканда 429 Too Many Requests кайтарылат; тезирээк сурабай, бир аз күтүп кайра аракет кылыңыз — же вебхукка жазылып, сурамжылоону таптакыр токтотуңуз.

Аяк чекиттери

Брондоо объектиси

Брондоо жана жолугушуу бирдиктүү жалпы форматта көрсөтүлөт: type, id, status, source, guestInitiated, startsAt/endsAt/убакыт зонасы (бөлүмдүн өзүнүн зонасы), валюта, компания, бөлүм, конок, attribution, conversionId, createdAt/updatedAt — ошондой эле резервация үчүн partySize жана таблица, ал эми жолугушуу үчүн кызмат жана адис. Бул так webhook жеткирген нерсе, ошондуктан бирин иштете алган кабыл алуучу экөөнү тең иштете алат.

{
  "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. Иштетилген эң чоң cursor маанисин сактап, аны after катары кайра өткөрүңүз — ал эч качан сапты өткөрүп жибербейт жана кайталабайт, ошондуктан бузулуудан кийин улантуу коопсуз. Иштетпеген түрлөрдү этибарга албаңыз: жаңылары кошулушу мүмкүн.

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

Вебхуктар

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

• Ар бир 2xx жооп жеткирилген деп эсептелет; 2xx эмес жооп же убакыт аягы (timeout) болгондо интервалды узартып (1 мүнөт, 5 мүнөт, 15 мүнөт, 1 саат, 3 саат, 6 саат, 12 саат) 8 жолу кайра аракет кылынат — 410 статусунда кайра аракеттенүү токтойт.
• Жөнөтүүлөр ээрчитилбейт.
• Өндүрүш чөйрөсүндө 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"]}'

Постбэктер

Макростор толтурулган трекериңиздин өз URL дарегине GET же POST сурамы — JSON вебхуктардын ордуна query-string постбэктерин колдонгон платформалар үчүн. Буйрутма үчүн {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>" }.