TapTime REST API

Çdo kërkesë ka nevojë për një çelës API të kompanisë (Integrime → Webhooks & API në panel) të dërguar si Autorizim: Bearer tt_live_….. Përgjigjet dhe gabimet janë në JSON.

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

Autentifikimi

Çdo kërkesë mban një çelës API të kompanisë si token bartës. Krijoni një nga paneli — Integrime → Webhooks & API → Çelësa REST API — ku ai shfaqet një herë dhe ruhet vetëm në anën e serverit si një hash SHA-256; një çelës i humbur revokohet dhe zëvendësohet, jo rikuperohet. Një kompani mund të ketë deri në 10 çelësa aktivë.

• Çelësat vetëm-lexim mund të thërrasin çdo pikë përfundimtare GET dhe mund të krijojnë ose anulojnë abonime webhook — një abonim nuk dërgon asgjë që çelësi nuk mund ta lexonte tashmë.
• Çelësat lexim-shkrim mund të dërgojnë edhe me POST një ndryshim statusi të rezervimit; një çelës vetëm-lexim merr 403 Forbidden në ato rrugë.
• Një çelës i përket një kompanie — çdo listë dhe kërkim janë tashmë të kufizuara tek ajo, nuk ka parametër companyId.

Kufijtë e kërkesave

50 kërkesa në minutë për çelës, në një dritare rrëshqitëse, të përbashkëta për të gjitha pikat përfundimtare. Tejkalimi kthen 429 Too Many Requests; prisni dhe provoni përsëri në vend që të pyesni më shpesh — ose abononi një webhook dhe mos pyesni më.

Pikat përfundimtare

Objekti i rezervimit

Një rezervim dhe një takim paraqiten në një formë të përbashkët: kind, id, status, source, guestInitiated, startsAt/endsAt/zonë kohore (zona e degës), monedhë, kompani, degë, mysafir, atribut, conversionId, createdAt/updatedAt — plus partySize dhe tavolina për një rezervim, shërbimi dhe specialisti për një takim. Është pikërisht ajo që ofron një webhook, kështu që një marrës që trajton njërën, trajton të dyja.

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

Objekti i porosisë

Një porosi ka të njëjtën formë kudo që e hasni — në REST API, në webhooks e porosive dhe në rrjedhën e ngjarjeve: kind ("order"), id, number (numri që thërret stafi), status (open ose paid), source (customer ose staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (anëtari i besnikërisë, kur stafi e ka identifikuar), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (sa vlen porosia pa bakshishin — numri që raportojnë konvertimet), paymentMethod, servedBy, conversionId, createdAt, paidAt dhe attribution. Shumat janë gjithmonë në njësitë më të vogla të monedhës.

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

Objekti i besnikërisë

Çdo ngjarje, kartë dhe shpërblim besnikërie ka të njëjtën formë: kind ("loyalty"), id (karta), timezone, company, branch (ku ndodhi, kur ka një të tillë), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (për një vulë: source, issuedBy, createdAt) dhe reward (për një shpërblim: code, title, status, expiresAt, redeemedAt, redeemedBy), plus conversionId, id-ja me të cilën raportohet një regjistrim në besnikëri.

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

Rrjedha e ngjarjeve

Çdo rresht është { id, cursor, type, createdAt, previousStatus, data }. data mban subjektin nën çelësin që emërton prefiksi i ngjarjes: data.booking, data.order ose data.loyalty. Ruani kursorin më të lartë që keni përpunuar dhe kthejeni si after — nuk kapërcen dhe nuk përsërit asnjëherë një rresht, kështu që është e sigurt të vazhdoni pas një rrëzimi. Injoroni llojet që nuk i trajtoni: mund të shtohen të reja.

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

Webhooks

Krijoni një pikë përfundimtare te Integrime → Webhooks & API — ose lidhni Zapier, Make, n8n ose Pipedream te Integrime → Automatizimi — që TapTime të dërgojë me POST një ngjarje JSON të nënshkruar sapo ndryshon një rezervim, një porosi ose një kartë besnikërie. Ngjarjet i zgjidhni për çdo pikë përfundimtare. Një kompani mund të ketë gjithsej deri në 50 webhooks, postbacks, chat-e dhe lidhje automatizimi.

• Çdo përgjigje 2xx trajtohet si e dorëzuar; çdo përgjigje jo-2xx ose tejkalimi i kohës së pritjes riprovohet me intervale të shtuar (1 min, 5 min, 15 min, 1 orë, 3 orë, 6 orë, 12 orë) deri në 8 përpjekje — një përgjigje 410 ndalon riprovimet.
• Riaadresimet nuk ndiqen.
• URL-ja duhet të jetë HTTPS në prodhim dhe nuk mund të tregojë në një adresë private ose loopback.
• Dorëzimi është të paktën një herë: gjithmonë verifikoni nënshkrimin dhe hiqni përsëritjet në 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));

Abonimet e webhooks

Platformat e automatizimit i ndezin dhe i fikin aktivizuesit përmes API-së në vend që t’i kërkojnë përdoruesit të ngjitë një URL („REST hooks“): dërgoni me POST URL-në e platformës me ngjarjet që do, ruani id-në e kthyer dhe fshijeni me DELETE kur aktivizuesi fiket. Një abonim është një webhook i zakonshëm i nënshkruar — shfaqet në panel, i shënuar me çelësin që e krijoi.

• Një çelës sheh dhe heq vetëm abonimet që ka krijuar vetë; revokimi i çelësit i heq të gjitha.
• Adresat në hooks.zapier.com, make.com dhe pipedream.net njihen dhe shfaqen me emrin e platformës; çdo adresë tjetër https është një webhook i thjeshtë.
• Sekreti i nënshkrimit kthehet një herë, në përgjigjen e POST-it; pronari mund ta shfaqë përsëri në panel.

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

Postbacks

Një GET ose POST te URL-ja e gjurmuesit tuaj me makrot e plotësuara, për platformat që përdorin postbacks me parametra në URL në vend të webhooks JSON. Për një porosi, {value} është vlera e porosisë pa bakshishin dhe {order_id} id-ja e saj.

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

Vendmbajtësit e disponueshëm

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

Gabimet

Çdo gabim është JSON: { "error": "<code>", "message": "<human-readable>" }.