API Documentation v1

مستندات API کاروانی

راهنمای جامع APIهای پلتفرم کاروانی برای توسعه‌دهندگان، شرکای تجاری و ادغام‌های شخص ثالث. تمامی endpointها از طریق HTTPS و با امضای HMAC در نشست عمل می‌کنند.

احراز هویت

• نشست‌ها از طریق کوکی HttpOnly با امضای HMAC-SHA256 و TTL ۳۰ روز مدیریت می‌شوند.

• برای endpointهای ادمین، نقش admin و احتمالا واحد سازمانی مشخص (super/finance/operations/…) لازم است.

• تمامی پاسخ‌ها در فرمت application/json با charset utf-8 برمی‌گردند.

• خطاها به‌صورت {error: string} با HTTP status مناسب (4xx/5xx) برمی‌گردند.

امضای Webhook

هر webhook با header X-Carvani-Signature: sha256=... امضا می‌شود. برای اعتبارسنجی، payload خام را با secret خود HMAC-SHA256 کنید و با signature مقایسه نمایید.

POST /your-webhook HTTP/1.1
Content-Type: application/json
X-Carvani-Event: order.created
X-Carvani-Signature: sha256=ab47c2...

{
  "event": "order.created",
  "timestamp": "2026-05-27T10:30:00.000Z",
  "data": { ... }
}

احراز هویت

5 endpoint

POST/api/auth/send-otpارسال کد OTPعمومی10/15min/IP
POST/api/auth/login-otpتأیید کد و ورودعمومی15/15min/IP
POST/api/auth/login-passwordورود با رمز عبورعمومی8/15min/IP
POST/api/auth/registerثبت‌نامعمومی5/hour/IP
POST/api/auth/logoutخروج و revoke نشستمشتری

کالاها و کاتالوگ

3 endpoint

GET/api/bannersبنرهای فعال صفحه‌ی اصلیعمومی
GET/api/product-questions/[slug]پرسش و پاسخ یک محصولعمومی
POST/api/product-questions/[slug]ثبت پرسش جدیدمشتری5/hour/IP

حساب مشتری

10 endpoint

GET/api/account/walletsموجودی کیف‌پول‌هامشتری
GET/api/account/addressesآدرس‌های ذخیره‌شدهمشتری
GET/api/account/orders/[code]جزئیات یک سفارشمشتری
GET/api/account/loyaltyامتیاز و سطح باشگاهمشتری
GET/api/account/sessionsنشست‌های فعالمشتری
DELETE/api/account/sessions?jti=…خروج از یک دستگاهمشتری
GET/api/account/notification-prefsتنظیمات اعلاناتمشتری
GET/api/account/exportخروجی کامل داده‌ها (GDPR)مشتری
POST/api/account/deleteحذف حساب (با OTP)مشتری
POST/api/account/ticketsایجاد تیکت پشتیبانیمشتری5/hour/IP

ادمین

8 endpoint

GET/api/admin/customersلیست مشتریانادمین
PATCH/api/admin/customers/[phone]block/unblock/notesادمین
GET/api/admin/adminsلیست ادمین‌ها (super-only)ادمین
GET/api/admin/ticketsصندوق ورودی تیکت‌هاادمین
GET/api/admin/refundsجست‌وجوی تراکنش‌ها (finance)ادمین
GET/api/admin/audit/csvخروجی CSV گزارش تغییراتادمین
GET/api/admin/newsletter/csvخروجی CSV مشترکین خبرنامهادمین
POST/api/admin/orders/[code]/tax-invoiceارسال به سامانه مودیانادمین

Webhooks

4 endpoint

GET/api/admin/webhooksلیست webhookها (super-only)ادمین
POST/api/admin/webhooksایجاد webhook جدیدادمین
PATCH/api/admin/webhooks/[id]enable/disableادمین
DELETE/api/admin/webhooks/[id]حذف webhookادمین

سیستم

2 endpoint

GET/api/healthوضعیت سلامت سیستم (DB/SMS/Email/Credit)عمومی
POST/api/newsletterثبت‌نام در خبرنامهعمومی5/hour/IP

برای پشتیبانی توسعه‌دهنده، با dev@carvani.ir تماس بگیرید.

در حال بارگذاری کاروان…

احراز هویت

• نشست‌ها از طریق کوکی HttpOnly با امضای HMAC-SHA256 و TTL ۳۰ روز مدیریت می‌شوند.

• برای endpointهای ادمین، نقش admin و احتمالا واحد سازمانی مشخص (super/finance/operations/…) لازم است.

• تمامی پاسخ‌ها در فرمت application/json با charset utf-8 برمی‌گردند.

• خطاها به‌صورت {error: string} با HTTP status مناسب (4xx/5xx) برمی‌گردند.

امضای Webhook

POST /your-webhook HTTP/1.1 Content-Type: application/json X-Carvani-Event: order.created X-Carvani-Signature: sha256=ab47c2... { "event": "order.created", "timestamp": "2026-05-27T10:30:00.000Z", "data": { ... } }