وب‌هوک‌های فاکتور

مرجع ساختار داده و شرایط ارسال وب‌هوک‌های ایجاد و ویرایش فاکتور در دیدار

وب‌هوک‌های فاکتور

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

ساختار داده ارسالی

data · object

اطلاعات کامل فاکتوری است که وب‌هوک برای آن ارسال شده است. در وب‌هوک ایجاد، این Object وضعیت فاکتوری تازه ایجادشده را نشان می‌دهد و در وب‌هوک ویرایش، آخرین وضعیت همان فاکتور را پس از اعمال تغییرات در اختیار شما قرار می‌دهد.

Show property

data.Id · number

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

data.BizDomainId · string

شناسه بیزدامنه‌ای است که این فاکتور داخل آن صادر شده است و مشخص می‌کند سند متعلق به کدام حساب دیدار است.

data.DealId · string

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

data.FinalPrice · number

مبلغ نهایی قابل‌پرداخت این فاکتور پس از اعمال تخفیف‌ها و مالیات است.

data.CreatedOn · string

زمانی است که این فاکتور برای اولین بار در دیدار ایجاد و صادر شده است.

data.CreatorId · string

شناسه کاربری است که این فاکتور را در دیدار ایجاد کرده است.

data.IsCanceled · boolean

مشخص می‌کند فاکتور لغو شده است یا خیر. مقدار true یعنی سند لغو شده و مقدار false یعنی فاکتور همچنان معتبر و فعال است.

data.InvoiceFormattedNumber · string

شماره نمایشی و قالب‌بندی‌شده فاکتور است؛ همان شماره‌ای که کاربران روی سند و در فهرست فاکتورها مشاهده می‌کنند. این مقدار با شناسه فنی data.Id متفاوت است.

data.QuoteFormattedNumber · string

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

data.InvoiceType · string

کد نوع سند فروش است و مشخص می‌کند این فاکتور در ساختار مالی دیدار با چه نوعی ثبت شده است.

data.Description · string

توضیحات تکمیلی ثبت‌شده برای این فاکتور است و می‌تواند شرایط پرداخت، توضیح سفارش یا اطلاعاتی را داشته باشد که باید همراه سند نمایش داده شود.

data.TotalPrice · number

جمع قیمت اقلام این فاکتور پیش از کسر تخفیف و افزودن مالیات است.

data.TotalDiscount · number

مجموع مبلغ تخفیفی است که از اقلام یا کل این فاکتور کسر شده است.

data.TotalTaxPrice · number

مجموع مبلغ مالیات محاسبه‌شده برای اقلام این فاکتور است.

data.TotalFinalPrice · number

جمع نهایی این فاکتور پس از محاسبه قیمت اقلام، تخفیف‌ها و مالیات است.

data.QuoteExpirationDays · number

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

data.Items · array

فهرست اقلامی است که در این فاکتور قرار گرفته‌اند. هر عضو Array یک ردیف از سند را نشان می‌دهد و اطلاعات محصول، تعداد، قیمت، تخفیف، مالیات و مبلغ نهایی همان ردیف را نگهداری می‌کند.

Show property

data.Items[].ProductId · string

شناسه محصولی است که در این ردیف از فاکتور قرار گرفته است. با این مقدار می‌توانید ردیف سند را به محصول اصلی در دیدار متصل کنید.

data.Items[].ProductCode · string

کد محصول درج‌شده در این ردیف است و برای تطبیق کالا با کد محصول در سیستم‌های فروش یا حسابداری استفاده می‌شود.

data.Items[].VariantId · string

شناسه زیرمحصول یا تنوعی است که در این ردیف فاکتور انتخاب شده است؛ برای مثال یک رنگ، اندازه یا مدل مشخص از محصول اصلی.

data.Items[].VariantCode · string

کد زیرمحصول یا تنوع انتخاب‌شده در این ردیف است و برای تطبیق نسخه دقیق محصول با سیستم حسابداری یا انبار استفاده می‌شود.

data.Items[].Title · string

عنوان محصول یا خدمتی است که در این ردیف از سند نمایش داده می‌شود.

data.Items[].VariantTitle · string

عنوان زیرمحصول یا تنوع انتخاب‌شده در این ردیف است و مشخص می‌کند دقیقاً کدام نسخه از محصول روی فاکتور فروخته شده است.

data.Items[].Description · string

توضیح اختصاصی همین ردیف از سند است و می‌تواند جزئیات محصول، خدمت یا شرایط مربوط به آن قلم را نگهداری کند.

data.Items[].Unit · string

واحد فروش قلم است؛ برای مثال عدد، بسته، متر یا ساعت. مقدار Quantity براساس همین واحد تفسیر می‌شود.

data.Items[].UnitPrice · number

قیمت هر واحد از محصول یا خدمت در این ردیف، پیش از محاسبه تعداد، تخفیف و مالیات است.

data.Items[].Quantity · number

تعداد یا مقدار محصول و خدمت ثبت‌شده در این ردیف است.

data.Items[].Index · number

ترتیب نمایش این ردیف در است. از این مقدار می‌توانید برای حفظ ترتیب اقلام هنگام نمایش یا چاپ سند استفاده کنید.

data.Items[].Discount · number

مبلغ تخفیف اعمال‌شده روی همین ردیف است.

data.Items[].DiscountPercent · number

درصد تخفیف اعمال‌شده روی همین ردیف است.

data.Items[].Price · number

مبلغ این ردیف پیش از مالیات و پس از محاسبه قیمت واحد، تعداد و تخفیف است.

data.Items[].TaxPrice · number

مبلغ مالیات محاسبه‌شده برای همین ردیف است.

data.Items[].FinalPrice · number

مبلغ نهایی همین ردیف پس از محاسبه تعداد، تخفیف و مالیات است.

data.DiscountRows · string

اطلاعات ردیف‌های تخفیف مستقلی است که روی این فاکتور ثبت شده‌اند. این بخش تخفیف‌هایی را نگهداری می‌کند که ممکن است به‌صورت یک ردیف جدا از اقلام محصول اعمال شده باشند.

data.BuyerInfo · string

اطلاعات خریدار ثبت‌شده روی این فاکتور است. این داده‌ها برای نمایش مشخصات مشتری روی سند فروش و ارسال آن به سیستم‌های مالی استفاده می‌شوند.

data.SellerInfo · string

اطلاعات فروشنده ثبت‌شده روی این فاکتور است. این داده‌ها مشخصات کسب‌وکار صادرکننده سند را برای نمایش یا چاپ نگهداری می‌کنند.

changes · array

تغییراتی که باعث ارسال وب‌هوک ویرایش فاکتور شده‌اند در این Array قرار می‌گیرند. در وب‌هوک ایجاد، changes خالی است؛ چون فاکتور تازه ساخته شده و نسخه قبلی‌ای برای مقایسه وجود ندارد. در وب‌هوک ویرایش، هر عضو مشخص می‌کند کدام فیلد تغییر کرده، مقدار آن پیش از ویرایش چه بوده و پس از ویرایش به چه مقداری تبدیل شده است. Object data وضعیت نهایی فاکتور را نشان می‌دهد و changes فقط تغییرات همان عملیات را گزارش می‌کند.

Show property

changes[].propertyName · string

نام فیلدی از فاکتور است که در این عملیات ویرایش تغییر کرده است. این مقدار مشخص می‌کند before و after مربوط به کدام بخش از اطلاعات فاکتور هستند.

changes[].before · number

مقدار فیلد پیش از انجام این ویرایش است. با مقایسه آن با changes[].after می‌توانید دقیقاً تشخیص دهید اطلاعات فاکتور از چه مقداری تغییر کرده است. نوع مقدار به فیلد نوشته‌شده در propertyName بستگی دارد و می‌تواند رشته، عدد، Boolean، Object، Array یا null باشد.

changes[].after · number

مقدار فیلد پس از انجام و ذخیره ویرایش است. این مقدار نتیجه نهایی همان تغییر را نشان می‌دهد و باید با مقدار متناظر آن در Object data هم‌خوان باشد.

meta · object

اطلاعات فنی مربوط به خود رویداد وب‌هوک است، نه اطلاعات فاکتور. این Object مشخص می‌کند چه عملیاتی انجام شده، رویداد متعلق به کدام بیزدامنه و فاکتور است، چه کاربری آن را ایجاد کرده، تغییر از چه منبعی آمده و Payload توسط کدام تنظیم وب‌هوک و در چندمین تلاش ارسال شده است.

Show property

meta.actionType · number

کد عددی نوع عملیاتی است که باعث ارسال این وب‌هوک شده است. براساس نمونه‌ها، مقدار 1 یعنی فاکتور ایجاد شده و مقدار 2 یعنی فاکتور ویرایش شده است.

meta.actionTypeTitle · string

عنوان متنی همان عملیاتی است که در meta.actionType به‌صورت عددی مشخص شده است. در نمونه ایجاد مقدار Add و در نمونه ویرایش مقدار Change ارسال می‌شود.

meta.bizDomainId · string

شناسه بیزدامنه‌ای است که فاکتور در آن ایجاد یا ویرایش شده است. این مقدار مشخص می‌کند رویداد وب‌هوک متعلق به کدام حساب یا فضای کاری دیدار است.

meta.entityId · string

شناسه فاکتوری است که رویداد وب‌هوک برای آن ثبت شده است. این مقدار باید به همان رکوردی اشاره کند که اطلاعات کامل آن داخل data قرار گرفته و معمولاً با data.Id یکسان است.

meta.entity · number

کد عددی داخلی نوع موجودیتی است که رویداد برای آن ثبت شده است. در Payload این صفحه، این کد به موجودیت فاکتور اشاره می‌کند.

meta.entityTitle · string

عنوان فنی موجودیتی است که این وب‌هوک به آن مربوط می‌شود و نشان می‌دهد رکورد داخل data از نوع فاکتور است.

meta.id · number

شناسه رویدادی است که پس از ایجاد یا ویرایش فاکتور در سیستم ثبت شده و این Payload براساس آن ساخته شده است. این شناسه مربوط به خود رویداد است، نه شناسه فاکتور.

meta.isBulkEdit · boolean

مشخص می‌کند تغییر فاکتور در قالب یک عملیات گروهی انجام شده است یا خیر. مقدار true یعنی این رویداد نتیجه ویرایش گروهی بوده و مقدار false یعنی فاکتور به‌صورت تکی ایجاد یا ویرایش شده است.

meta.timeStamp · string

زمانی است که رویداد ایجاد یا ویرایش فاکتور در دیدار ثبت شده و Payload وب‌هوک براساس آن تولید شده است. این زمان لزوماً با تاریخ‌های داخل خود فاکتور یکسان نیست.

meta.userId · string

شناسه کاربری است که عملیات منجر به ارسال این وب‌هوک را انجام داده است. در رویداد ایجاد، کاربری را نشان می‌دهد که فاکتور را ساخته و در رویداد ویرایش، کاربری را مشخص می‌کند که تغییر را انجام داده است.

meta.webhookId · number

شناسه تنظیم وب‌هوکی است که این Payload را به آدرس مقصد ارسال کرده است. این مقدار برای تشخیص وب‌هوک تعریف‌شده‌ای که رویداد از طریق آن ارسال شده کاربرد دارد.

meta.changeSource · number

کد عددی منبعی است که عملیات ایجاد یا ویرایش از طریق آن انجام شده است. عنوان قابل‌خواندن همین منبع در meta.changeSourceTitle قرار می‌گیرد.

meta.changeSourceTitle · string

عنوان متنی منبعی است که فاکتور از طریق آن ایجاد یا ویرایش شده است. برای مثال مقدار Api یعنی عملیات از طریق API انجام شده است.

meta.attempt · number

شماره تلاش برای ارسال همین رویداد وب‌هوک به آدرس مقصد است. مقدار 1 یعنی Payload در اولین تلاش ارسال شده است.

وب‌هوک ایجاد فاکتور چه زمانی ارسال می‌شود؟

وب‌هوک ایجاد فاکتور زمانی ارسال می‌شود که یک فاکتور جدید با موفقیت در دیدار ثبت شود. آبجکت data شامل اطلاعات فاکتور تازه ایجادشده است و آرایه changes خالی ارسال می‌شود، چون پیش از این عملیات رکوردی وجود نداشته که فیلدی از آن تغییر کرده باشد.

وب‌هوک ویرایش فاکتور چه زمانی ارسال می‌شود؟

وب‌هوک ویرایش فاکتور زمانی ارسال می‌شود که حداقل یکی از اطلاعات موجود در data تغییر کند. فیلدهایی که تغییر آن‌ها می‌تواند باعث ارسال این وب‌هوک شود عبارت‌اند از:

• data.Id
• data.BizDomainId
• data.DealId
• data.FinalPrice
• data.CreatedOn
• data.CreatorId
• data.IsCanceled
• data.InvoiceFormattedNumber
• data.QuoteFormattedNumber
• data.InvoiceType
• data.Description
• data.TotalPrice
• data.TotalDiscount
• data.TotalTaxPrice
• data.TotalFinalPrice
• data.QuoteExpirationDays
• data.Items[].ProductId
• data.Items[].ProductCode
• data.Items[].VariantId
• data.Items[].VariantCode
• data.Items[].Title
• data.Items[].VariantTitle
• data.Items[].Description
• data.Items[].Unit
• data.Items[].UnitPrice
• data.Items[].Quantity
• data.Items[].Index
• data.Items[].Discount
• data.Items[].DiscountPercent
• data.Items[].Price
• data.Items[].TaxPrice
• data.Items[].FinalPrice
• data.DiscountRows
• data.BuyerInfo
• data.SellerInfo

اگر هیچ‌کدام از فیلدهای موجود در data تغییر نکنند، وب‌هوک ویرایش فاکتور ارسال نمی‌شود. آرایه changes عامل Trigger نیست؛ این آرایه نتیجه تغییرات انجام‌شده را گزارش می‌کند و data آخرین وضعیت فاکتور را پس از ویرایش نشان می‌دهد.

نمونه داده ارسالی

وب‌هوک ایجاد فاکتور

{
  "data": {
    "Id": 2230752,
    "BizDomainId": "b8233b92-7a57-42a3-8f3e-59fdbbb6c833",
    "DealId": "fb2fb2ad-34b1-458d-86a5-ddb68ec3176f",
    "FinalPrice": 550000,
    "CreatedOn": "2026-08-02T15:42:46.6670221+00:00",
    "CreatorId": "58f610e7-061a-4efc-9a87-af7b31bde808",
    "IsCanceled": false,
    "InvoiceFormattedNumber": "I-4",
    "QuoteFormattedNumber": null,
    "InvoiceType": "Invoice",
    "Description": "",
    "TotalPrice": 500000,
    "TotalDiscount": 0,
    "TotalTaxPrice": 50000,
    "TotalFinalPrice": 550000,
    "QuoteExpirationDays": 0,
    "Items": [
      {
        "ProductId": "6a76de58-b3ab-456a-8e0b-635a620f1599",
        "ProductCode": "101",
        "VariantId": null,
        "VariantCode": null,
        "Title": "product2",
        "VariantTitle": null,
        "Description": "",
        "Unit": "عدد",
        "UnitPrice": 500000,
        "Quantity": 1,
        "Index": 0,
        "Discount": 0,
        "DiscountPercent": 0,
        "Price": 500000,
        "TaxPrice": 50000,
        "FinalPrice": 550000
      }
    ],
    "DiscountRows": "[]",
    "BuyerInfo": "{\"BuyerType\":\"Person\",\"BuyerTitle\":\"\",\"BuyerName\":\"test\",\"BuyerEconomicCode\":\"\",\"BuyerNationalCode\":\"\",\"BuyerNationalID\":\"\",\"BuyerRegistrationNumber\":\"\",\"BuyerProvince\":\"\",\"BuyerGrandCity\":\"\",\"BuyerCity\":\"\",\"BuyerPostalCode\":\"\",\"BuyerMobilePhone\":\"09101111212\",\"BuyerFaxNumber\":\"\",\"BuyerAddress\":{\"KeyValues\":[{\"Key\":\"سایر\",\"Title\":\"سایر\",\"Value\":\"\"}],\"FilledKeyValues\":[]},\"BuyerPhone\":\"\",\"BuyerEmail\":\"\"}",
    "SellerInfo": "{\"SellerName\":\"زیما\",\"BizDomainId\":\"b8233b92-7a57-42a3-8f3e-59fdbbb6c833\",\"QuoteExpirationDays\":3,\"SellerEconomicCode\":\"\",\"SellerNationalCode\":\"\",\"SellerPostalCode\":\"\",\"SellerProvince\":\"\",\"SellerGrandCity\":\"\",\"SellerCity\":\"\",\"SellerAddress\":\"\",\"SellerPhone\":\"\",\"InvoiceConditions\":\"\",\"QuoteConditions\":\"\"}"
  },
  "changes": null,
  "meta": {
    "actionType": 1,
    "actionTypeTitle": "Add",
    "bizDomainId": "b8233b92-7a57-42a3-8f3e-59fdbbb6c833",
    "entityId": "2230752",
    "entity": 3,
    "entityTitle": "Invoice",
    "id": 639212821666887273,
    "isBulkEdit": false,
    "timeStamp": "2026-08-02T15:42:46.6887273Z",
    "userId": "58f610e7-061a-4efc-9a87-af7b31bde808",
    "webhookId": 32502,
    "changeSource": 1,
    "changeSourceTitle": "Api",
    "attempt": 1
  }
}