Add partner SMS gateway via Gama SendQuick and document it.

Expose POST /public/sms/send with API key + domain allowlist for external backends like Balout, wire Meshkee OTP/message sends to Gama, and publish Partner SMS docs on /docs/website. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 06:40:58 +04:30 · 2026-08-04 11:09:21 +03:30
parent 267a218c26
commit f4295e780c
22 changed files with 803 additions and 16 deletions
@@ -0,0 +1,85 @@
+# Partner SMS gateway
+
+Server-to-server SMS via Meshkee → Gama (گاما). Use this when a **non-Meshkee** (or partner) backend needs to send SMS through the shared Meshkee account.
+
+**Not for browser/storefront JavaScript.** Never put the API key in frontend code.
+
+Hub: https://api.meshkee.com/docs/website  
+Endpoint docs also in OpenAPI / Postman under **Partner SMS**.
+
+---
+
+## Endpoint
+
+```http
+POST https://api.meshkee.com/api/v1/public/sms/send
+Content-Type: application/json
+X-Api-Key: <partner-secret>
+```
+
+### Body
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `domain` | yes | Allowlisted partner apex, e.g. `baloutpastry.com` (`www.` is stripped) |
+| `to` | yes | Mobile: `09…`, `9…`, `+989…`, or `989…` |
+| `message` | yes | Free text, max 700 characters |
+
+### Example (Balout)
+
+```bash
+curl -sS -X POST 'https://api.meshkee.com/api/v1/public/sms/send' \
+  -H 'Content-Type: application/json' \
+  -H 'X-Api-Key: <YOUR_PARTNER_KEY>' \
+  -d '{
+    "domain": "baloutpastry.com",
+    "to": "09127004945",
+    "message": "سفارش شما به شماره ی ۱۲۱۱۳۲۲ اماده می باشد."
+  }'
+```
+
+### Success (200)
+
+```json
+{
+  "success": true,
+  "serverId": "1136923081051406337"
+}
+```
+
+`serverId` is the Gama message id (delivery tracking).
+
+### Errors
+
+| HTTP | Meaning |
+|------|---------|
+| 400 | Invalid phone or empty/too-long message |
+| 401 | Missing/invalid `X-Api-Key` or domain not allowlisted |
+| 429 | Rate limit: **30**/partner/minute or **5**/destination/minute |
+| 503 | SMS disabled, missing provider config, or Gama unreachable |
+
+---
+
+## Auth model
+
+1. Meshkee configures `SMS_PARTNERS=domain:apiKey,...` on the API server.
+2. Partner backend sends `X-Api-Key` + matching `domain` in the JSON body.
+3. Key must match that domain (timing-safe compare). `www.baloutpastry.com` normalizes to `baloutpastry.com`.
+
+First allowlisted partner: **baloutpastry.com**.
+
+---
+
+## Sender line (v1)
+
+Uses the **service** shortcode only (`SendQuick`). Advertising / bulk / OTP pattern APIs are not exposed yet.
+
+---
+
+## Rules for partner backends
+
+1. Call from your **server** only (Balout API → Meshkee API).
+2. Keep the API key in server env / secrets — never in the website frontend.
+3. Prefer short transactional messages (order ready, OTP-style text, etc.).
+4. Respect rate limits; backoff on `429`.
+5. Meshkee websites that already use customer auth OTP go through Meshkee’s own auth/SMS path — they do **not** need this partner endpoint.