مستندات API

نشانی پایه همه درخواست‌ها: https://endpoint.daryno.xyz/partner/v1. پاسخ‌ها JSON و با UTF-8 است.

احراز هویت

کلید را در داشبورد بسازید؛ فقط یک بار نشان داده می‌شود. آن را در یکی از این دو سرآیند بفرستید:

Authorization: Bearer drn_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Api-Key: drn_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

کلید را فقط در سرور نگه دارید، نه در اپ موبایل یا کد مرورگر. برای امنیت بیشتر، IPهای سرورتان را به کلید ببندید.

نقطه‌های پایانی

درخواست	کار
GET /prices	همه قیمت‌ها. با ?group=currency|gold|coin|metal فیلتر کنید.
GET /prices/{symbol}	یک نماد، مثل USD یا COIN_EMAMI.
GET /prices/{symbol}/history?days=30	قیمت بسته شدن روزانه، حداکثر ۹۰ روز.

فهرست نمادها (14)

نماد	نام	گروه	واحد
USD	دلار آمریکا	currency	IRT
EUR	یورو	currency	IRT
AED	درهم امارات	currency	IRT
GBP	پوند انگلیس	currency	IRT
TRY	لیر ترکیه	currency	IRT
CNY	یوان چین	currency	IRT
GOLD18	طلای ۱۸ عیار (هر گرم)	gold	IRT
MESGHAL	مثقال طلای ۱۸ عیار	gold	IRT
COIN_EMAMI	سکهٔ امامی	coin	IRT
COIN_BAHAR	سکهٔ بهار آزادی	coin	IRT
COIN_HALF	نیم‌سکه	coin	IRT
COIN_QUARTER	ربع‌سکه	coin	IRT
XAU	انس طلا	metal	USD
XAG	انس نقره	metal	USD

ساختار پاسخ

{
  "success": true,
  "data": {
    "item": {
      "symbol": "USD",          // stable identifier
      "name": "دلار آمریکا",
      "nameEn": "US Dollar",
      "group": "currency",      // currency | gold | coin | metal
      "unit": null,
      "currency": "IRT",        // prices are in toman unless USD
      "price": 101250,
      "buy": 101000, "sell": 101500,
      "changePct24h": 0.42,
      "computed": false,        // derived from other prices
      "stale": false,           // source hasn't updated recently
      "asOf": "2026-11-13T00:41:00Z"
    }
  }
}

محدودیت‌ها

هر پاسخ موفق این سرآیندها را دارد:

X-RateLimit-Limit / X-RateLimit-Remaining	درخواست مجاز در دقیقه، برای هر کلید
X-Quota-Limit / X-Quota-Remaining	سهم درخواست دوره اشتراک
X-Quota-Resets	پایان دوره (ISO 8601)

خطاها

{ "success": false, "error": { "code": "quota_exceeded", "message": "…" } }

HTTP	code	یعنی
401	missing_key, invalid_key	کلید نیامده یا درست نیست
401	key_revoked	کلید باطل شده
403	ip_not_allowed	IP درخواست در فهرست مجاز کلید نیست
403	account_suspended	حساب معلق است؛ با ما تماس بگیرید
402	subscription_expired	اشتراکی فعال نیست
429	rate_limited	بیش از حد مجاز در دقیقه؛ پس از Retry-After ثانیه دوباره
429	quota_exceeded	سهم دوره تمام شده؛ طرح را ارتقا دهید
404	unknown_symbol	چنین نمادی نیست

عامل‌های هوشمند

عامل را در داشبورد بسازید، زمینه بدهید، اعتبارسنجی و منتشر کنید. مشتری‌ها همیشه با نسخه منتشرشده صحبت می‌کنند؛ تغییر پیش‌نویس تا انتشار بعدی اثری ندارد. عامل‌ها طرح جداگانه خود را دارند، کنار طرح API قیمت: هر پاسخ عامل یک پیام از سهم طرح عامل کم می‌کند و سقف دقیقه‌ای آن هم جداست. خواندن گفتگو رایگان است. هر دو با همان کلید API صدا زده می‌شوند.

درخواست	کار
POST /agents/{agentId}/chat	یک پیام مشتری و پاسخ عامل. بدنه: message (حداکثر ۲٬۰۰۰ نویسه)، conversationId (اختیاری، شناسه خودتان؛ نباشد ساخته می‌شود)، customerRef (اختیاری).
GET /agents/{agentId}/conversations/{conversationId}	پیام‌های گفتگو، از جمله پاسخ‌های شما به تیکت.

{
  "success": true,
  "data": {
    "conversationId": "order-1234",
    "reply": "این سؤال را برای همکارانمان فرستادم؛ به‌زودی پاسخ می‌دهند.",
    "handedOff": true,                       // not in the context, or a person was asked for
    "ticket": { "id": "6af…", "status": "open" }
  }
}

وب‌هوک تیکت

رویدادهای ticket.created و ticket.answered به نشانی وب‌هوک عامل POST می‌شوند. پاسخ 2xx بدهید؛ وگرنه پس از ۱، ۵، ۳۰، ۱۲۰ و ۶۰۰ دقیقه دوباره می‌فرستیم.

X-Daryno-Event: ticket.answered
X-Daryno-Signature: t=1794531178,v1=5f0c…

{ "event": "ticket.answered",
  "ticket": { "id": "…", "status": "answered", "reason": "no_answer",
              "subject": "…", "reply": "…", "createdAt": "…", "answeredAt": "…" },
  "agent": { "id": "…", "name": "…" },
  "conversation": { "id": "order-1234", "customerRef": "user-42" },
  "sentAt": "2026-11-13T01:20:00Z" }

امضا را با رمز وب‌هوک عامل بررسی کنید: HMAC-SHA256 از t + "." + body، و درخواست‌های قدیمی‌تر از ۵ دقیقه را رد کنید.

// Node
const [t, v1] = req.get('X-Daryno-Signature').split(',').map(p => p.split('=')[1])
const expected = crypto.createHmac('sha256', process.env.DARYNO_WEBHOOK_SECRET)
  .update(`${t}.${rawBody}`).digest('hex')
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300
if (!fresh || !crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) return res.sendStatus(400)

HTTP	code	یعنی
402	agents_not_in_plan	طرح عامل هوشمند ندارید (جدا از طرح API قیمت)
404	agent_not_found	عامل نیست یا مال حساب این کلید نیست
409	agent_not_published, agent_paused	عامل منتشر نشده یا متوقف است
429	quota_exceeded	پیام‌های این دوره تمام شده
503	agent_busy, agent_unavailable	سرویس هوش مصنوعی در دسترس نیست؛ پس از Retry-After دوباره. پیامی کم نمی‌شود.

نمونه کد

cURL

curl "https://endpoint.daryno.xyz/partner/v1/prices?group=gold" -H "Authorization: Bearer $DARYNO_KEY"

JavaScript (Node 18+)

const res = await fetch('https://endpoint.daryno.xyz/partner/v1/prices/USD', {
  headers: { Authorization: `Bearer ${process.env.DARYNO_KEY}` },
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log(body.data.item.price)

Python

import os, requests

r = requests.get(
    "https://endpoint.daryno.xyz/partner/v1/prices/USD/history",
    params={"days": 30},
    headers={"Authorization": f"Bearer {os.environ['DARYNO_KEY']}"},
    timeout=10,
)
r.raise_for_status()
for point in r.json()["data"]["points"]:
    print(point["day"], point["close"])

PHP

$ch = curl_init('https://endpoint.daryno.xyz/partner/v1/prices/USD');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('DARYNO_KEY')],
    CURLOPT_RETURNTRANSFER => true,
]);
$item = json_decode(curl_exec($ch), true)['data']['item'];