# توکن‌های API | Procurize.AI

**ایجاد، مدیریت و استفاده از توکن‌های API برای دسترسی برنامه‌نویسی امن به فضای کاری Procurize.AI خود.**

> **قابل اعمال در:** داشبورد Procurize.AI → تنظیمات → توکن‌ها  
> **دسترس‌پذیر در:** طرح‌های Business و Enterprise  
> **نقش مورد نیاز:** Admin یا Maintainer

## مرور کلی

توکن‌های API امکان دسترسی امن و برنامه‌نویسی به پلتفرم Procurize.AI را فراهم می‌کنند. می‌توانید از توکن‌ها برای یکپارچه‌سازی Procurize.AI با سیستم‌های داخلی، خودکارسازی جریان‌های کاری یا ساخت برنامه‌های سفارشی بر پایه این پلتفرم استفاده کنید.

**ویژگی‌های کلیدی:**

- توکن‌ها تمام **مجوزهای** کاربری که آن‌ها را ایجاد کرده است را به ارث می‌برند  
- توکن‌ها **به‌صورت سازمانی scoped** هستند – نیازی به مشخص کردن `org` در درخواست‌های API نیست  
- می‌توان تعداد **نامحدودی** توکن ایجاد کرد  
- توکن‌ها می‌توانند **تاریخ انقضا** داشته باشند یا برای همیشه معتبر بمانند  
-  توکن‌ها می‌توانند **غیرفعال** شوند و در صورت نیاز **دوباره فعال** شوند  

> 🔒 **نکته امنیتی:** Procurize.AI مقدار توکن را **ذخیره** نمی‌کند – فقط هش آن را نگه می‌دارد. بلافاصله پس از ایجاد توکن باید آن را کپی و ذخیره کنید. توکن دوباره نشان داده نخواهد شد.

## دسترسی به پنل مدیریت توکن‌ها

1. به تب **Dashboard** → **Settings** → **Tokens** بروید.  
2. پنل مدیریت توکن‌ها توکن‌های شخصی شما را که به سازمان جاری متصل هستند، نمایش می‌دهد.

![پنل توکن‌های API](/images/docs/api-tokens-panel.png)

> **مجوز مورد نیاز:** تنها کاربران با نقش **Admin** یا **Maintainer** می‌توانند به این پنل دسترسی داشته باشند. برای جزئیات نقش‌ها، بخش [نمای کلی مجوزها](/what-user-permissions-does-procurize-have/) را ببینید.

## ایجاد توکن جدید

1. یک **نام** برای شناسایی هدف توکن وارد کنید.  
2. یک **دوره انقضا** انتخاب کنید:  
   - 1 ماه  
   - 3 ماه  
   - 1 سال  
   - **بدون انقضا** (اعتبار نامحدود)  

3. روی **«Generate»** کلیک کنید.

### مهم – بلافاصله توکن را کپی کنید

پس از ایجاد، مقدار توکن **یک بار** نمایش داده می‌شود – آن را کپی کنید و به‌صورت ایمن (مثلاً در یک مدیریت رمز عبور یا متغیر محیطی) ذخیره کنید.

![توکن API جدید](/images/docs/new-api-token.png)

> ⚠️ **بعد از این مرحله نمی‌توانید دوباره مقدار توکن را ببینید.** Procurize.AI فقط یک هش امن برای اعتبارسنجی ذخیره می‌کند. اگر توکن را گم کنید، باید آن را لغو کنید و توکن جدیدی بسازید.

## مدیریت توکن‌های موجود

پنل توکن‌ها لیستی از تمام توکن‌های ایجاد شده را همراه با:

- نام
- پسوند
- تاریخ ایجاد
- تاریخ انقضا (یا «‑»)
- وضعیت: **Active** یا **Inactive**

### غیرفعال‌سازی / فعال‌سازی مجدد توکن

- **Deactivate** – توکن را به‌صورت موقت غیرفعال می‌کند. می‌توانید در زمان نیاز دوباره فعالش کنید.  
- **Reactivate** – توکن غیرفعال‌شده را به وضعیت فعال بازمی‌گرداند.

> 💡 غیرفعال‌سازی برای تعلیق موقت یکپارچه‌سازی‌ها بدون حذف توکن مفید است.

### لغو توکن

- **Revoke** – توکن را به‌طور دائم حذف می‌کند. این عمل قابل بازگشت نیست.  
- اگر توکن را گم کرده‌اید، بلافاصله آن را لغو کنید و توکن جدیدی بسازید.

## استفاده از یک توکن API

### URL پایه و احراز هویت

| پارامتر | مقدار |
|-----------|-------|
| **Base URL** | `https://api.procurize.com` |
| **روش احراز هویت** | کلید API از طریق هدر |
| **هدر** | `X-API-Key: <YOUR_API_TOKEN>` |

### نمونه درخواست (cURL)

```bash
curl -X GET "https://api.procurize.com/v1/documents" \
  -H "X-API-Key: YOUR_API_TOKEN"
```

> 🧠 **نیاز به شناسه سازمان نیست** – توکن به سازمان شما وابسته است، بنابراین API به‌صورت خودکار زمینه را تشخیص می‌دهد.

## قوانین مهم امنیتی و استفاده

| قانون | توضیح |
|------|-------|
| **مجوزهای توکن** | توکن دقیقاً همان مجوزهایی را دارد که کاربری که آن را ساخته دارد. در صورت تغییر نقش کاربر، مجوزهای توکن نیز به‌صورت خودکار به‌روز می‌شوند. |
| **اتصال به سازمان** | توکن‌ها به سازمان سازنده متصل هستند. نمی‌توانید یک توکن را برای چندین سازمان استفاده کنید. |
| **قابلیت مشاهده توکن** | مقدار توکن **فقط یک بار** نشان داده می‌شود. بلافاصله آن را ذخیره کنید. Procurize.AI فقط یک هش ذخیره می‌کند. |
| **توکن‌های منقضی‌شده** | توکن‌های منقضی‌شده به‌صورت خودکار غیرفعال می‌شوند و قابل استفاده نیستند. در صورت نیاز، توکن جدیدی تولید کنید. |

## عیب‌یابی

| مشکل | راه‌حل |
|-------|----------|
| **خطای «Invalid API key»** | بررسی کنید که توکن به‌درستی کپی شده (بدون فاصله‌های اضافه). اطمینان حاصل کنید توکن هنوز فعال و منقضی نشده است. |
| **توکن پس از تغییر نقش کاربر کار نمی‌کند** | مجوزهای توکن به نقش فعلی کاربر به‌روزرسانی می‌شود. اگر کاربر مجوزهایش را از دست داده، توکن نیز همان مورد را تجربه می‌کند. |
| **گم کردن توکن** | توکن گم‌شده را لغو کنید و توکن جدیدی بسازید. |
| **محدودیت نرخ (Rate limiting)** | محدودیت‌های نرخ API بسته به طرح شما اعمال می‌شود. هدرهای `X-RateLimit-*` در پاسخ بررسی کنید. |

## مباحث مرتبط

- [نمای کلی مجوزها](/what-user-permissions-does-procurize-have/) – تعریف دقیق نقش‌ها  
- [طرح‌های قیمت‌گذاری](https://www.procurize.ai/pricing/) – کدام طرح‌ها دسترسی به API را شامل می‌شوند  
- [مرجع REST API](/rest-api-reference/) – جزئیات مستندات نقطه‌پایان‌ها  

{{<article-feedback>}}