> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-parschat.parstechai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-parschat.parstechai.com/_mcp/server.

# نسخه‌بندی و پایداری

> به چه چیزهایی متعهدیم، چه چیزهایی بدون اطلاع قبلی ممکن است تغییر کند، و بنر پیش‌انتشار چطور کار می‌کند.

> **Warning**
>
> **نسخه پیش‌انتشار `v1`، منتشرشده در ۲۰۲۶-۰۹-۱۴.** این صفحه به شکل API متعهد است، نه به تاریخ
> آن. دقیقاً همان چیزی را می‌سازیم که اینجا مستند شده است. شکل API تا
> **۲۰۲۶-۱۰-۱۴** هنوز ممکن است تغییر کند؛ پس از آن، تغییرات از [نسخه‌بندی و پایداری](/documentation/reference/versioning-stability) پیروی می‌کنند.
>
> این بنر صفحه‌به‌صفحه و هم‌زمان با فعال‌شدن هر مسیر برداشته می‌شود. تا وقتی بنر هست، بر اساس
> قرارداد پیاده‌سازی کنید و فرض کنید آن مسیر هنوز قابل فراخوانی نیست.

## نسخه در URL

```
https://api-chat.parstechai.com/v1
```

`v1` **فقط با تغییر ناسازگار** عوض می‌شود. برای افزودنی‌ها نسخه را بالا نمی‌بریم.

## چه چیزهایی تغییر ناسازگار نیستند

> **Warning**
>
> **فیلدهای جدید تغییر ناسازگار به حساب نمی‌آیند. یکپارچه‌سازی شما باید فیلدهایی را که نمی‌شناسد
> نادیده بگیرد.** همین قاعده است که به ما اجازه می‌دهد API را بهتر کنیم بی‌آنکه شما را مجبور به
> یکپارچه‌سازی دوباره کنیم. این همچنین رایج‌ترین دلیل از کار افتادن یکپارچه‌سازی یک شریک در به‌روزرسانی‌ای
> است که برای هیچ‌کس دیگری مشکلی ایجاد نکرده است.

| تغییر                        | ناسازگار است؟ |
| ---------------------------- | ------------- |
| فیلد جدید در پاسخ            | خیر           |
| فیلد اختیاری جدید در درخواست | خیر           |
| نوع رویداد جدید              | خیر           |
| مقدار جدید در یک enum موجود  | خیر           |
| اندپوینت جدید                | خیر           |
| حذف یا تغییر نام یک فیلد     | **بله**       |
| تغییر نوع یک فیلد            | **بله**       |
| حذف یک اندپوینت              | **بله**       |

پارسرهایتان را طوری بنویسید که مقدار جدید enum یا نوع رویداد جدید باعث خطا (exception) نشود. آن را لاگ کنید و ادامه دهید.

## نسخه‌بندی محتوای وب‌هوک

هر رویداد یک `schema_version` در قالب semver دارد:

```json
{ "schema_version": "1.0.0", "event": "message", "…": "…" }
```

فیلدها با افزایش نسخه **minor** اضافه می‌شوند. هیچ چیزی بدون افزایش نسخه **major** و اطلاع‌رسانی
قبلی حذف نمی‌شود یا کاربرد تازه پیدا نمی‌کند.

## بنر پیش‌انتشار

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

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

## دریافت اطلاع‌رسانی

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