رفتن به محتوا
HNROS مرکز راهنما
فارسی
رایگان شروع کنید
فهرست مطالبساخت اشتراکرویدادهامحتوای اعلانبررسی امضاتحویل، تلاش دوباره و پیام ناموفقگزارش تحویل و ارسال دوبارهکلید رمزگذاری سرورخلاصه نقاط پایانی OpenAPIدر تلفن

وب‌هوک و OpenAPI: اعلان رویداد به سامانه‌های دیگر

وقتی رویدادی در HNR رخ می‌دهد (ثبت فاکتور، حذف سفارش، حرکت محموله…) وب‌هوک یک اعلان HTTP امضاشده به نشانی تعیین‌شده می‌فرستد. اعلان فقط خلاصه سند و پیوند API آن را دارد و گیرنده رکورد کامل را با نشست خودش از API می‌خواند. این صفحه شرح یک قرارداد است، نه طرح‌واره رسمی.

ساخت اشتراک

تنظیمات › یکپارچه‌سازی و وب‌هوک‌ها فقط برای مدیر سامانه باز است. اشتراک تازه به نام، نشانی مقصد و دست‌کم یک رویداد نیاز دارد. نشانی باید با https آغاز شود؛ مقصدی در شبکه محلی یا روی همین رایانه (مثلاً 192.168.x.x یا localhost) فقط با علامت تأیید مدیر پذیرفته می‌شود. برای یک نشانی اشتراک دوم ساخته نمی‌شود.

پالایه‌های اختیاری: فقط برخی طرف‌حساب‌ها یا انبارها. اگر پالایه تعیین شده و سند آن فیلد را ندارد، اعلان فرستاده نمی‌شود. مبلغ و ارز سند فقط وقتی فرستاده می‌شود که «مبلغ و ارز سند را به اعلان اضافه کن» علامت خورده باشد.

هنگام ذخیره، کلید محرمانه امضا (با whsec_ آغاز می‌شود) فقط یک بار نمایش داده می‌شود؛ آن را در سامانه گیرنده نگه دارید. روی سرور رمزگذاری‌شده نگه داشته می‌شود و دوباره خوانده نمی‌شود. اگر گم شد با «تازه‌سازی کلید» کلید تازه بسازید؛ امضاهای کلید قدیمی دیگر معتبر نیستند.

رویدادها

فاکتور، سفارش، پیشنهاد قیمت (fatura، siparis، teklif): yazildi، degisti، silindi · حواله (irsaliye): yazildi، silindi · رسید (makbuz): yazildi، degisti، silindi · stok.hareket (انتقال بین انبارها ارسال، دریافت یا ضایعه؛ تأیید شمارش) · sevkiyat.durum (حرکت، تحویل در توقفگاه، اصلاح رسید تحویل) · onay.karar · dof.acildi · servis.bilet (باز شد، وضعیت) · uretim.teyit (تأیید یا لغو). کد رویداد در سرآیند X-HNR-Event و فیلد olay بدنه است؛ دکمه آزمایش test.ping می‌فرستد.

محتوای اعلان

POST https://alici.ornek.com/hnr
Content-Type: application/json; charset=utf-8
User-Agent: HNR-Webhook/1
X-HNR-Event: fatura.yazildi
X-HNR-Delivery: wh_2
X-HNR-Timestamp: 1791559000
X-HNR-Signature: t=1791559000,v1=5f1c…(64 hex)

{"surum":1,"id":"ev_3fa1…","olay":"fatura.yazildi","firma":"ornek","zaman":"2026-10-09T15:15:00.000Z",
 "belge":{"tur":"fatura","sira":9107041,"no":"SF2026000126","cari":"C001","depo":"MERKEZ","tarih":"2026-10-09","tutar":360},
 "baglanti":"/api/fatura/9107041"}

belge.no شماره قطعی سند است و رکورد کامل از طریق baglanti از API خوانده می‌شود. tutar و doviz فقط در اشتراک‌های شامل مبلغ می‌آیند؛ بدون doviz مبلغ به ارز محلی شرکت است. در رویداد حذف، خلاصه پیش از حذف سند خوانده می‌شود. surum نسخه قالب بار است: فیلد تازه ممکن است افزوده شود و فیلدهای موجود تغییر نمی‌کنند.

بررسی امضا

هر درخواست سرآیندهای X-HNR-Event، X-HNR-Delivery (شناسه تحویل)، X-HNR-Timestamp و X-HNR-Signature: t=…,v1=… را دارد. v1 مقدار HMAC-SHA256 (شانزده‌شانزدهی) متن t + "." + بدنه خام با کلید محرمانه است. گیرنده باید امضا را با مقایسه زمان‌ثابت بررسی کند، زمان قدیمی‌تر از ۵ دقیقه را رد کند و یک X-HNR-Delivery را دو بار پردازش نکند اما باز هم 2xx برگرداند (محافظت در برابر تکرار).

// Node.js (express.raw ile ham gövde / raw body)
import { createHmac, timingSafeEqual } from 'node:crypto';
const seen = new Set();
export function verify(secret, headers, rawBody) {
  const p = Object.fromEntries(String(headers['x-hnr-signature']).split(',').map((x) => x.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return 'old';
  const expected = createHmac('sha256', secret).update(`${p.t}.${rawBody}`).digest();
  const got = Buffer.from(p.v1 || '', 'hex');
  if (got.length !== expected.length || !timingSafeEqual(got, expected)) return 'bad';
  const id = headers['x-hnr-delivery'];
  if (seen.has(id)) return 'duplicate';   // answer 2xx, do not process again
  seen.add(id); return 'ok';
}
# Python 3
import hmac, hashlib, time
def verify(secret: str, signature: str, raw_body: bytes) -> bool:
    p = dict(x.split('=', 1) for x in signature.split(','))
    if abs(time.time() - int(p['t'])) > 300:
        return False
    expected = hmac.new(secret.encode(), p['t'].encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, p.get('v1', ''))

تحویل، تلاش دوباره و پیام ناموفق

HNR به نشانی شما POST می‌فرستد و ۱۰ ثانیه منتظر می‌ماند؛ فقط پاسخ 2xx تحویل شمرده می‌شود و تغییر مسیرها دنبال نمی‌شوند. پس از تلاش ناموفق، انتظارها به ترتیب حدود ۱ دقیقه، ۳ دقیقه، ۱۱ دقیقه، ۳۸ دقیقه، ۲ ساعت، ۷ ساعت و ۲۴ ساعت است. اگر هر هشت تلاش ناموفق باشد، تحویل به پیام ناموفق تبدیل می‌شود. اعلان‌های یک اشتراک و یک سند به ترتیب می‌روند: تا تحویل قبلی تمام نشود بعدی فرستاده نمی‌شود. در هر شرکت حداکثر ۴ ارسال هم‌زمان.

بدون اشتراک سرور چیزی نمی‌فرستد. ارسال در شرکت خود سرور هر دقیقه و در شرکت‌های دیگر هر بار که عملیات تازه‌ای در آن شرکت انجام شود اجرا می‌شود. در اشتراک متوقف، اعلان‌های در انتظار می‌مانند و پس از فعال‌سازی دوباره فرستاده می‌شوند.

گزارش تحویل و ارسال دوباره

گزارش تحویل وضعیت هر اعلان (در انتظار، تحویل‌شده، ناموفق)، تعداد تلاش‌ها و آخرین کد HTTP را نشان می‌دهد؛ جزئیات شامل بدنه ارسال‌شده، ۱ کیلوبایت نخست پاسخ و هر تلاش است. «ارسال دوباره» اعلان را بی‌درنگ یک بار دیگر با همان شناسه تحویل می‌فرستد؛ اگر ناموفق باشد قاعده تلاش دوباره از نو آغاز می‌شود. رکوردها هرگز حذف نمی‌شوند. «ارسال آزمایشی» رویداد test.ping را به نشانی اشتراک می‌فرستد.

کلید رمزگذاری سرور

کلیدهای محرمانه امضا با AES-256-GCM و با همان کلید رمزگذاری سرور که اتصال زنده بانک به کار می‌برد (HNR_BANKA_KIMLIK_ANAHTARI) نگه داشته می‌شوند. اگر این کلید تعریف نشده باشد اشتراک ذخیره نمی‌شود. اگر کلید تغییر کند کلیدهای ذخیره‌شده رمزگشایی نمی‌شوند و هر اشتراک «تازه‌سازی کلید» لازم دارد.

خلاصه نقاط پایانی OpenAPI

GET /api/openapi.json (یا دکمه دانلود در بخش یکپارچه‌سازی) همه نقاط پایانی API باز سرور را با مسیر، روش و برچسب ماژول فهرست می‌کند. بدنه درخواست و پاسخ مستند نمی‌شود: این خلاصه نقاط پایانی است، نه طرح‌واره رسمی. احراز هویت: کلید API در Authorization: Bearer و X-Oturum-Token.

در تلفن

در تلفن اشتراک‌ها به‌صورت کارت نمایش داده می‌شوند؛ اشتراک تازه در سه گام ساخته می‌شود (نشانی، رویدادها، پالایه). گزارش تحویل فهرستی از کارت‌هاست و هر کارت دکمه‌های جزئیات و ارسال دوباره دارد.

راهنماهای مرتبط