مستندات B2B

B2B API – دریافت خودکار اطلاعات سفارش و محصول

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

احراز هویت

همه درخواست‌های API به یک API-Key معتبر نیاز دارند که در HTTP-Header ارسال می‌شود. دسترسی API به حساب مشتری شما متصل است و اصولاً در اختیار حساب‌های مشتری قرار دارد.

info شما به درخواست B2B جداگانه‌ای نیاز ندارید: با حساب مشتری خود وارد شوید، تب API را باز کنید و API-Key خود را همان‌جا تولید کنید. به دسترسی API ←

قالب Header

HTTP Request Header
X-API-Key: YOUR_API_KEY_HERE
Content-Type: application/json
Accept: application/json

نمونه با cURL

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 زیر هستند:

Base URL
https://artumos.com/api/v1

همه پاسخ‌ها به‌صورت JSON بازگردانده می‌شوند (Content-Type: application/json).

Rate Limits

Planدرخواست / دقیقهدرخواست / روز
حساب مشتری605.000
محدودیت گسترش‌یافتهبنا به درخواستبنا به درخواست

در صورت تجاوز، HTTP 429 Too Many Requests بازگردانده می‌شود. هدر Retry-After شامل زمان انتظار بر حسب ثانیه است.

کدهای خطا

HTTP-Codeمعنی
200 OKدرخواست موفق
400 Bad Requestپارامترهای نامعتبر
401 UnauthorizedAPI-Key مفقود یا نامعتبر
403 Forbiddenبدون مجوز برای این منبع
404 Not Foundمنبع یافت نشد
429 Too Many RequestsRate Limit تجاوز شد
500 Internal Server Errorخطای سرور – لطفاً با پشتیبانی تماس بگیرید

قالب Fehler-Response

JSON
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

Endpoint: سفارش‌ها

GET /api/v1/orders همه سفارش‌های حساب
Parameterنوعتوضیحات
pageintegerصفحه (پیش‌فرض: 1)
per_pageintegerورودی به ازای هر صفحه (حداکثر 100)
statusstringpaid | pending | all
Beispiel-Response
{
  "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
    }
  }
}
GET /api/v1/orders/{order_id} دریافت یک سفارش منفرد

Endpoint: اطلاعات محصول و سفارش

GET /api/v1/orders/{order_id}/codes همه اطلاعات محصول یک سفارش
Beispiel-Response
{
  "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"
      }
    ]
  }
}
GET /api/v1/codes/{code_id} دریافت یک اطلاعات محصول منفرد
warning اطلاعات محصول و سفارش تنها در چارچوب سفارش مربوطه و اطلاعات فروشنده می‌تواند استفاده شود. انتقال سوءاستفاده‌گرانه ممکن است شرایط استفاده را نقض کند.

Endpoint: محصولات

GET /api/v1/products دریافت کاتالوگ محصولات
Parameterنوعتوضیحات
categorystringفیلتر بر اساس Slug دسته‌بندی
in_stockbooleanفقط محصولات موجود
pageintegerصفحه
Beispiel-Response
{
  "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

POST – Webhook-Endpoint شما
{
  "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)

پرسش‌های متداول

چه کسی می‌تواند از B2B API استفاده کند؟

هر مشتری دارای حساب مشتری می‌تواند از دسترسی API استفاده کند. در حساب مشتری خود وارد شوید و از API-Key مربوطه برای درخواست‌های احراز هویت‌شده استفاده کنید.

پاسخ‌ها چه قالبی دارند؟

همه پاسخ‌ها به‌صورت JSON بازگردانده می‌شوند. شیء Root همیشه شامل success: true/false و همچنین یا data یا error.

آیا می‌توانم سفارش‌ها را از طریق API ثبت کنم؟

در نسخه اول، API برای دریافت سفارش‌ها و اطلاعات سفارش و محصول است. Endpointهای نوشتاری سفارش به‌طور جداگانه به‌محض در دسترس بودن فعال می‌شوند.

آیا محیط Sandbox وجود دارد؟

بله. Sandbox را می‌توان در حساب مشتری در تب «دسترسی API» فعال کرد و مستقیماً به API-Key مربوطه متصل است.