# Mekante Developer Documentation

> Mekante ("Müdavimi olduğun Mekânlar şimdi Mekante'de") is a multi-tenant loyalty platform for cafes, restaurants, salons, and retail businesses. The Mekante Public Till API (`https://app.mekante.com/api/v1/public`) lets point-of-sale (POS) systems scan a customer's 30-second QR code, award points or stamps, redeem rewards, and void mistaken entries. Outbound webhooks notify your server in real time when members join, earn points, redeem rewards, or have entries voided.

## Key Facts for LLMs & Integrations

- **Base URL:** `https://app.mekante.com/api/v1/public`
- **Authentication:** `Authorization: Bearer sk_live_<key>` on every request. Each key acts as a hidden cashier bound to a single business location.
- **Idempotency:** `POST /earn` and `POST /redeem` require an `Idempotency-Key` header (8–100 chars, e.g. `pos-2026-000123`). Retries with the same key return `200 OK` with `"replayed": true`.
- **Currency:** Monetary amounts (`amount`) are integer **kuruş** (minor units of TRY: `15000` = 150 TL).
- **Timestamps:** ISO 8601 UTC (`2026-10-23T09:57:08.246Z`).
- **Program Types:** `points` (earn points from `amount`), `stamps` (earn `stamps` count per visit, default 1), or `hybrid` (both `stamps` and optional `amount`).
- **QR & Scan Windows:** Customer QR tokens expire in **30 seconds** and are single-use. `POST /scan` returns a `scanId` valid for **5 minutes**. Cashiers/API keys can void their own entries within **15 minutes** (`POST /ledger/:id/void`).
- **Rate Limits:** 120 requests/minute per API key (`429 RATE_LIMITED`), 1 MB max body size (`413 PAYLOAD_TOO_LARGE`).
- **Webhooks:** Signed with `X-Mekante-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256(whsec_secret, "t.rawBody")>`, `X-Mekante-Event` header, `User-Agent: Mekante-Webhooks/1`, 5-second timeout, 6 attempts with exponential backoff.

## Public Till API Endpoints

- `GET /me`: Inspect the business, loyalty program, and location bound to the API key.
- `POST /scan`: Verify and consume a customer's 30-second QR token; returns `scanId`, `intent` (`earn` | `redeem`), `member`, `program`, `reward`, and `rewards`.
- `GET /scans/:id`: Re-read an active, unconsumed 5-minute scan.
- `POST /earn/preview`: Calculate points, stamps, multipliers, and bonuses for a visit without writing to the ledger.
- `POST /earn`: Award points and/or stamps for a `scanId` (requires `Idempotency-Key`).
- `POST /redeem`: Redeem a reward for a `scanId` (requires `Idempotency-Key`).
- `POST /ledger/:id/void`: Reverse an `earn` or `redeem` ledger entry within 15 minutes.
- `GET /ledger/recent`: List the last 20 transactions made by this API key.
- `GET /ledger/mine`: Cursor-paginated list of transactions made by this API key (`limit`, `cursor`).

## Webhook Events

- `member.joined`: A customer joined the business's loyalty program (`joinedVia`: `"join_code"` | `"till"`).
- `points.earned`: Points or stamps were awarded (`POST /earn`).
- `reward.redeemed`: A reward was redeemed (`POST /redeem`).
- `entry.voided`: A ledger entry was reversed (`POST /ledger/:id/void`).
- `ping`: Test delivery triggered from the dashboard.

## Documentation (English)

- [Overview](https://docs.mekante.com/en/): Introduction, page index, and API conventions.
- [Getting started](https://docs.mekante.com/en/baslangic.html): Creating an `sk_live_` API key and calling `GET /me`.
- [Authentication](https://docs.mekante.com/en/kimlik-dogrulama.html): Bearer token header, `401` errors, revoking keys, and cashier scope.
- [Till flow](https://docs.mekante.com/en/kasa-akisi.html): QR scanning, earning points/stamps, redeeming rewards, `Idempotency-Key`, and voiding entries.
- [Endpoints](https://docs.mekante.com/en/uc-noktalar.html): Full reference for all 9 `/api/v1/public/*` routes with request/response JSON examples.
- [Errors](https://docs.mekante.com/en/hatalar.html): Error envelope (`{ error, code, message }`), HTTP statuses, and all machine-readable error codes.
- [Limits](https://docs.mekante.com/en/limitler.html): Rate limits, payload limits, program guardrails, and QR/scan/void time windows.
- [Webhooks](https://docs.mekante.com/en/webhooklar.html): Endpoint setup, event envelopes, delivery rules, and retry backoff schedule.
- [Signature verification](https://docs.mekante.com/en/imza-dogrulama.html): Verifying `X-Mekante-Signature` HMAC-SHA256 in Node.js, Python, and PHP.

## Dokümantasyon (Türkçe)

- [Genel Bakış](https://docs.mekante.com/): Giriş, sayfa dizini ve temel kurallar.
- [Başlangıç](https://docs.mekante.com/baslangic.html): API anahtarı oluşturma ve `GET /me` ile ilk istek.
- [Kimlik doğrulama](https://docs.mekante.com/kimlik-dogrulama.html): `Authorization: Bearer` başlığı, anahtar iptali ve yetkiler.
- [Kasa akışı](https://docs.mekante.com/kasa-akisi.html): QR okutma, puan/damga yazma, ödül düşme, `Idempotency-Key` ve geri alma.
- [Uç noktalar](https://docs.mekante.com/uc-noktalar.html): Tüm `/api/v1/public/*` uç noktalarının istek ve yanıt örnekleri.
- [Hatalar](https://docs.mekante.com/hatalar.html): Hata biçimi, HTTP durumları ve kararlı hata kodları.
- [Limitler](https://docs.mekante.com/limitler.html): İstek sınırları, program kuralları ve QR/okutma süreleri.
- [Webhook'lar](https://docs.mekante.com/webhooklar.html): Olay türleri, gövde zarfı ve yeniden deneme takvimi.
- [İmza doğrulama](https://docs.mekante.com/imza-dogrulama.html): `X-Mekante-Signature` başlığını Node.js, Python ve PHP ile doğrulama.

## Full Single-File Context

- [Complete Developer Reference (llms-full.txt)](https://docs.mekante.com/llms-full.txt): Self-contained English & Turkish API and Webhook specification in a single file for LLM context windows.