B2B API – دریافت خودکار اطلاعات سفارش و محصول
REST-API ما در اختیار هر مشتری دارای حساب مشتری قرار دارد و امکان دریافت خودکار اطلاعات سفارش و محصول و یکپارچهسازی آنها در سیستمهای خودتان را فراهم میکند.
احراز هویت
همه درخواستهای API به یک API-Key معتبر نیاز دارند که در HTTP-Header ارسال میشود. دسترسی API به حساب مشتری شما متصل است و اصولاً در اختیار حسابهای مشتری قرار دارد.
قالب Header
X-API-Key: YOUR_API_KEY_HERE Content-Type: application/json Accept: application/json
نمونه با cURL
curl -X GET "https://artumos.com/api/v1/orders" \ -H "X-API-Key: YOUR_API_KEY_HERE" \ -H "Accept: application/json"
Base URL
همه Endpointها نسبت به Base URL زیر هستند:
https://artumos.com/api/v1
همه پاسخها بهصورت JSON بازگردانده میشوند (Content-Type: application/json).
Rate Limits
| Plan | درخواست / دقیقه | درخواست / روز |
|---|---|---|
| حساب مشتری | 60 | 5.000 |
| محدودیت گسترشیافته | بنا به درخواست | بنا به درخواست |
در صورت تجاوز، HTTP 429 Too Many Requests بازگردانده میشود. هدر Retry-After شامل زمان انتظار بر حسب ثانیه است.
کدهای خطا
| HTTP-Code | معنی |
|---|---|
200 OK | درخواست موفق |
400 Bad Request | پارامترهای نامعتبر |
401 Unauthorized | API-Key مفقود یا نامعتبر |
403 Forbidden | بدون مجوز برای این منبع |
404 Not Found | منبع یافت نشد |
429 Too Many Requests | Rate Limit تجاوز شد |
500 Internal Server Error | خطای سرور – لطفاً با پشتیبانی تماس بگیرید |
قالب Fehler-Response
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key."
}
}
Endpoint: سفارشها
/api/v1/orders
همه سفارشهای حساب
| Parameter | نوع | توضیحات |
|---|---|---|
page | integer | صفحه (پیشفرض: 1) |
per_page | integer | ورودی به ازای هر صفحه (حداکثر 100) |
status | string | paid | pending | all |
{
"success": true,
"data": {
"orders": [
{
"id": "ORD-12345",
"status": "paid",
"total": 49.99,
"currency": "EUR",
"created_at": "2026-01-15T10:30:00Z",
"items_count": 2
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 42
}
}
}
/api/v1/orders/{order_id}
دریافت یک سفارش منفرد
Endpoint: اطلاعات محصول و سفارش
/api/v1/orders/{order_id}/codes
همه اطلاعات محصول یک سفارش
{
"success": true,
"data": {
"order_id": "ORD-12345",
"codes": [
{
"id": "CODE-789",
"product_name": "Beispielprodukt vom Marktplatz",
"product_sku": "ART-PRODUCT-001",
"product_info": "Hinweise laut Verkäuferangaben",
"delivery_url": "https://...",
"delivered_at": "2026-01-15T10:31:00Z",
"status": "active"
}
]
}
}
/api/v1/codes/{code_id}
دریافت یک اطلاعات محصول منفرد
Endpoint: محصولات
/api/v1/products
دریافت کاتالوگ محصولات
| Parameter | نوع | توضیحات |
|---|---|---|
category | string | فیلتر بر اساس Slug دستهبندی |
in_stock | boolean | فقط محصولات موجود |
page | integer | صفحه |
{
"success": true,
"data": {
"products": [
{
"id": 42,
"sku": "ART-PRODUCT-001",
"name": "Beispielprodukt vom Marktplatz",
"price": 49.99,
"currency": "EUR",
"in_stock": true,
"category": "handmade"
}
]
}
}
Webhooks
Webhookها امکان دریافت اعلانهای بلادرنگ را هنگام ارائه سفارشها یا کدها فراهم میکنند. Webhook-URLها را میتوان در حساب مشتری ثبت کرد.
رویدادهای در دسترس
| Event | توضیحات |
|---|---|
order.paid | سفارش پرداخت شد |
codes.delivered | کدها ارائه شدند |
order.refunded | سفارش بازپرداخت شد |
Webhook Payload
{
"event": "codes.delivered",
"timestamp": "2026-01-15T10:31:05Z",
"data": {
"order_id": "ORD-12345",
"codes_count": 2
},
"signature": "sha256=..."
}
امضا را با Webhook-Secret خود تأیید کنید: HMAC-SHA256(payload, webhook_secret)
پرسشهای متداول
هر مشتری دارای حساب مشتری میتواند از دسترسی API استفاده کند. در حساب مشتری خود وارد شوید و از API-Key مربوطه برای درخواستهای احراز هویتشده استفاده کنید.
همه پاسخها بهصورت JSON بازگردانده میشوند. شیء Root همیشه شامل success: true/false و همچنین یا data یا error.
در نسخه اول، API برای دریافت سفارشها و اطلاعات سفارش و محصول است. Endpointهای نوشتاری سفارش بهطور جداگانه بهمحض در دسترس بودن فعال میشوند.
بله. Sandbox را میتوان در حساب مشتری در تب «دسترسی API» فعال کرد و مستقیماً به API-Key مربوطه متصل است.