mirror of
https://git.meshkee.com/Meshkee/backend.git
synced 2026-08-11 22:30:59 +04:30
Alireza HassaniandCursor
f4295e780c
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>
86 lines
2.5 KiB
Markdown
86 lines
2.5 KiB
Markdown
# 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.
|