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 გასაღებს, როგორც მფლობელის ტოკენს. შექმენით ერთი პანელიდან — ინტეგრაციები → ვებჰუკები და 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 და ცხრილი დაჯავშნისთვის, სერვისი და სპეციალისტი ვიზიტისთვის. ეს ზუსტად ისაა, რასაც 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 პასუხი ან დროის ამოწურვა ხელახლა განიხილება გაზრდილი ინტერვალებით (1 წთ, 5 წთ, 15 წთ, 1 სთ, 3 სთ, 6 სთ, 12 სთ) 8 მცდელობამდე — 410-ის შემთხვევაში ხელახალი მცდელობა შეწყდება.
• გადამისამართებები არ სრულდება.
• პროდუქციაში URL მისამართი უნდა იყოს HTTPS და არ უნდა მიუთითებდეს კერძო ან ლუპბექ მისამართზე.
• მიწოდება სულ მცირე ერთხელ ხდება: ყოველთვის შეამოწმეთ ხელმოწერა და გააუქმეთ 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));

ვებჰუკების გამოწერები

ავტომატიზაციის პლატფორმები ტრიგერებს API-ით რთავენ და თიშავენ, ნაცვლად იმისა, რომ მომხმარებელს URL-ის ჩასმა სთხოვონ („REST hooks“): გააგზავნეთ POST-ით პლატფორმის საკუთარი URL სასურველ მოვლენებთან ერთად, შეინახეთ დაბრუნებული 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"]}'

პოსტბექები

GET ან POST მოთხოვნა თქვენი ტრეკერის საკუთარ URL-ზე შევსებული მაკროებით — იმ პლატფორმებისთვის, რომლებიც 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>" }.