مرکز راهنما
انتقال و توسعه

API سایت: وصل کردن حسابداری، انبار و برنامه‌های دیگر به سیما

۱۴۰۵/۸/۲۹۴ دقیقه مطالعه۶ بازدید

اگر حسابداری، انبار، CRM یا یک ابزار اتوماسیون مثل n8n دارید، لازم نیست سفارش‌ها و موجودی را دستی بین آن‌ها و سایت جابه‌جا کنید. API سیما به برنامه‌های شما اجازه می‌دهد با یک کلید، داده‌های همین سایت را بخوانند و اگر اجازه داده باشید، تغییر بدهند. این راهنما برای مدیر سایت و برنامه‌نویسی است که اتصال را می‌سازد.

API جزو امکانات پلن است. اگر در پنل «تنظیمات ← کلیدهای API» را نمی‌بینید، پلن سایتتان آن را ندارد.

۱. ساختن کلید API

در پنل سایت به «تنظیمات ← کلیدهای API» بروید و «کلید تازه» را بزنید. یک نام بگذارید تا بعداً بدانید کدام برنامه از آن استفاده می‌کند، مثلاً «حسابداری». اگر برنامه باید چیزی را عوض کند (موجودی، قیمت، وضعیت سفارش یا انتشار مطلب)، «اجازهٔ تغییر» را روشن کنید؛ بدون آن، کلید فقط می‌خواند.

فرم ساختن کلید API تازه با نام کلید و اجازهٔ تغییر

بعد از «ساختن کلید»، کلید فقط همین یک بار نشان داده می‌شود. همان لحظه کپی‌اش کنید و در برنامهٔ مقصد بگذارید. سیما کلید را طوری نگه می‌دارد که خودش هم نمی‌تواند دوباره نشانش بدهد؛ اگر گمش کردید، کلید تازه بسازید و قبلی را باطل کنید.

۲. فهرست کلیدها و باطل کردن

در همین صفحه همهٔ کلیدها را با پیشوند، دسترسی (فقط خواندن یا خواندن و تغییر)، وضعیت و آخرین استفاده می‌بینید. «آخرین استفاده» کمک می‌کند کلیدهایی را که دیگر کسی استفاده نمی‌کند پیدا کنید. با آیکون سطل، کلید باطل می‌شود و از همان لحظه هر درخواستی با آن رد می‌شود.

فهرست کلیدهای API با پیشوند، دسترسی، وضعیت و آخرین استفاده

۳. وصل شدن برنامه

برنامه‌نویس شما کلید را در سرآیند Authorization می‌فرستد و نشانی پایه https://your-domain/api/v1 است:

curl -H "Authorization: Bearer sima_..." https://your-site.example/api/v1/orders

مستندات کامل API، با همهٔ نشانی‌ها و فیلدها، روی خود سایتتان در /docs/api است و فقط چیزهایی را نشان می‌دهد که سایت شما واقعاً دارد. چند نکته که برنامه‌نویس باید بداند:

  • هر کلید فقط برای همان سایت است که در آن ساخته شده.
  • فهرست‌ها صفحه‌بندی دارند (page و per_page تا ۱۰۰) و با updated_since فقط ردیف‌هایی که از آن لحظه عوض شده‌اند می‌آیند؛ این برای همگام‌سازی دوره‌ای بهترین راه است.
  • مبلغ‌ها در API به ریال‌اند (عدد صحیح)، نه تومان. برای نمایش به تومان، بر ۱۰ تقسیم کنید.
  • هر کلید در دقیقه ۱۲۰ درخواست می‌تواند بفرستد. بیشتر از آن پاسخ ۴۲۹ می‌گیرد و سرآیند Retry-After می‌گوید چقدر صبر کند.
  • خطاها JSON هستند با یک code ثابت، مثل forbidden برای کلید بدون اجازهٔ تغییر.

۴. چه چیزهایی در دسترس است

  • همهٔ سایت‌ها: سفارش‌ها (با اقلام، جمع، وضعیت و خریدار) و مشتری‌ها.
  • فروشگاه: محصولات و دسته‌ها؛ با اجازهٔ تغییر، قیمت و موجودی هر تنوع و وضعیت سفارش.
  • محتوا: نوشته‌ها، برگه‌ها و دسته‌ها و برچسب‌ها؛ با اجازهٔ تغییر، ساختن و ویرایش نوشته و برگه، بارگذاری تصویر، و نوشتن ترجمه به زبان‌های دیگر سایت. مطلبی که با کلید منتشر شود از همان ویرایشگر و قواعد پنل رد می‌شود و نویسنده ندارد.
  • بخش‌های دیگر مثل نوبت‌دهی، دوره‌ها، کتاب‌ها، منوی رستوران و آگهی‌های ملک، اگر سایتتان آن‌ها را داشته باشد.

۵. وب‌هوک: خبر گرفتن به‌جای پرسیدن مداوم

اگر می‌خواهید برنامه‌تان همان لحظه از یک اتفاق باخبر شود (مثلاً پرداخت یک سفارش)، به‌جای اینکه هر چند دقیقه API را بپرسد، وب‌هوک بگذارید:

  1. در «تنظیمات ← تنظیمات عمومی ← ارسال پیام»، بخش «وب‌هوک»، نشانی وب‌هوک (یک نشانی https روی اینترنت) و یک «کلید امضا» دست‌کم ۱۶ حرفی وارد و ذخیره کنید. با دکمهٔ آزمایش یک رویداد آزمایشی فرستاده می‌شود.
  2. در «تنظیمات ← قالب‌های پیام»، در قالب هر رویدادی که می‌خواهید (مثلاً پرداخت سفارش)، «وب‌هوک» را تیک بزنید.

هر رویداد یک درخواست POST با بدنهٔ JSON است و سرآیند X-Sima-Signature دارد: HMAC-SHA256 از timestamp.body با کلید امضای شما. برنامه‌تان باید امضا را بررسی کند تا مطمئن شود درخواست از سیما آمده. اگر برنامه پاسخ 2xx ندهد، سیما دوباره می‌فرستد.

نکته‌های امنیتی

  • برای هر برنامه یک کلید جدا بسازید تا اگر یکی لو رفت، فقط همان را باطل کنید.
  • به برنامه‌ای که فقط گزارش می‌گیرد اجازهٔ تغییر ندهید.
  • کلید را هرگز در کد سمت مرورگر، اپ موبایل یا مخزن عمومی کد نگذارید؛ فقط روی سرور برنامهٔ مقصد.

سؤال‌های رایج

برای استفاده از API باید برنامه‌نویس باشم؟

برای ساختن کلید نه. ولی وصل کردن برنامه‌ها کار برنامه‌نویس یا ابزارهایی مثل n8n است که درخواست HTTP می‌فرستند. خیلی از نرم‌افزارهای حسابداری و انبار هم این امکان را دارند.

کلید را گم کردم، می‌توانم دوباره ببینمش؟

نه، کلید فقط یک بار نشان داده می‌شود. یک کلید تازه بسازید، در برنامه بگذارید و کلید قبلی را باطل کنید.

اگر پلن سایتم API نداشته باشد، کلیدهایم چه می‌شوند؟

کلیدها و وب‌هوکی که ساخته‌اید پاک نمی‌شوند ولی کار نمی‌کنند، تا وقتی دوباره پلنی با API بگیرید.

دیدگاه‌ها

برای ثبت دیدگاه ابتدا وارد حساب کاربری خود شوید.

ورود به حساب

در حال بارگذاری…

اولین سایتت رو همین امروز بساز

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