🔌 API دوطرفهٔ تیکت پشتیبانی آنی

برای شرکت‌ها و سازمان‌های بیرونی از پلتفرم. با یک API Key می‌توانید تیکت بسازید، بخوانید، پاسخ دهید و وضعیت را تغییر دهید. رویدادها هم با Webhook امضاشده به شما ارسال می‌شود.

۱) گرفتن کلید

مدیر پلتفرم از پنل تیکت پشتیبانی → تب «سازمان‌ها و API» یک اتصال می‌سازد. کلید فقط یک‌بار نمایش داده می‌شود.

X-API-Key: ani_sup_xxxxxxxxxxxxxxxxx

هر درخواست باید همین هدر را داشته باشد. برای هر سازمان می‌توان Scopes را به read یا read,write محدود کرد.

۲) Endpointها

متدمسیرکار
GET/api/support/external/pingتست کلید و مشاهده سازمان
POST/api/support/external/ticketsساخت تیکت جدید
GET/api/support/external/ticketsفهرست تیکت‌ها (فیلتر status/externalRef)
GET/api/support/external/tickets/{code}جزئیات و پیام‌ها
POST/api/support/external/tickets/{code}/messagesپاسخ سازمان به تیکت
PATCH/api/support/external/tickets/{code}تغییر status/priority

۳) ساخت تیکت

curl -X POST "https://aniii.ir/api/support/external/tickets" \
  -H "X-API-Key: ani_sup_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "خطا در حمل سفارش",
    "description": "سفارش 12345 به دست مشتری نرسید.",
    "priority": "high",
    "source": "company-crm",
    "requesterName": "شرکت داده‌پرداز",
    "requesterPhone": "02112345678",
    "externalRef": "CRM-9001",
    "metadata": { "orderId": 12345, "branch": "tehran-1" }
  }'

پاسخ:

{
  "ok": true,
  "ticket": {
    "id": 12,
    "code": "SUP-261025-A1B2C3",
    "status": "open",
    "priority": "high",
    "organization": "داده‌پرداز",
    "externalRef": "CRM-9001",
    "createdAt": "2026-10-25T19:00:00Z"
  }
}

۴) پاسخ و تغییر وضعیت

curl -X POST "https://aniii.ir/api/support/external/tickets/SUP-261025-A1B2C3/messages" \
  -H "X-API-Key: ani_sup_xxx" -H "Content-Type: application/json" \
  -d '{"body":"اطلاعات بیشتر: کد رهگیری 5678","authorName":"پشتیبانی داده‌پرداز"}'

curl -X PATCH "https://aniii.ir/api/support/external/tickets/SUP-261025-A1B2C3" \
  -H "X-API-Key: ani_sup_xxx" -H "Content-Type: application/json" \
  -d '{"status":"pending","priority":"urgent"}'

وضعیت‌های مجاز: open، pending، answered، closed — اولویت‌ها: low/normal/high/urgent.

۵) Webhook دوطرفه

با ثبت WebhookUrl در پنل مدیر، رویدادهای زیر به سرور شما POST می‌شوند:

هدرها:

X-Ani-Event: ticket.agent_replied
X-Ani-Delivery: 8f4...
X-Ani-Signature: sha256=<HMAC-SHA256(body, webhookSecret)>

برای تأیید اصالت، HMAC بدنهٔ خام را با WebhookSecret محاسبه و با هدر مقایسه کنید. پاسخ 2xx یعنی تحویل موفق. در غیر این صورت وضعیت در فیلد LastWebhookStatus ثبت می‌شود.

۶) نمونهٔ Webhook Payload

{
  "event": "ticket.agent_replied",
  "deliveryId": "8f4c...",
  "at": "2026-10-25T19:05:00Z",
  "ticket": {
    "id": 12, "code": "SUP-261025-A1B2C3",
    "source": "company-crm", "subject": "خطا در حمل سفارش",
    "status": "answered", "priority": "high",
    "organization": "داده‌پرداز", "externalRef": "CRM-9001",
    "metadata": { "orderId": 12345 }
  },
  "message": {
    "id": 34, "authorType": "agent", "authorName": "پشتیبانی آنی",
    "body": "در حال بررسی با انبار هستیم.", "isInternal": false,
    "createdAt": "2026-10-25T19:05:00Z"
  }
}

برای فعال‌سازی روی همهٔ سرویس‌ها، فقط source را برابر نام سرویس/برنامه بفرستید (ani-car، ani-food، ani-radio، ani-uc، franchise و…). همهٔ تیکت‌ها در یک صف واحد و پنل ادمین/پشتیبانی دیده می‌شوند.

→ ثبت تیکت کاربر · → پنل مدیر