احراز هویت و قواعد API
نشانی پایه، کلید API، دسترسی‌ها، محدودیت تعداد درخواست و قواعد کلی API حسابداری نمو.
API نمو یک API ساده با JSON روی HTTPS است. برنامه‌نویس سایت فقط «رویداد فروش» می‌فرستد — سفارش، پرداخت، برگشت — و نمو خودش فاکتور، رسید، سند و گردش انبار را می‌سازد. هیچ‌جا لازم نیست حساب یا سندی بشناسید.
نشانی پایه
https://panel.nemosystem.ir/api/v1همهٔ مسیرها با / تمام می‌شوند (مثلاً /api/v1/orders/).
کلید API
کلید را در پنل نمو، تنظیمات ← اتصال فروشگاه ← کلید جدید بسازید. کلید شکلی مثل nemo_live_… دارد و فقط یک بار نمایش داده می‌شود. نمو خود کلید را نگه نمی‌دارد؛ اگر گم شد، کلید تازه بسازید.
کلید را در سرآیند Authorization بفرستید:
Authorization: Bearer nemo_live_XXXXXXXXXXXXXXXXXXXXXXXXیا اگر سرور شما سرآیند Authorization را جابه‌جا می‌کند، در X-Nemo-Key:
X-Nemo-Key: nemo_live_XXXXXXXXXXXXXXXXXXXXXXXXکلید سازمان را مشخص می‌کند؛ شناسهٔ سازمان هیچ‌وقت در درخواست فرستاده نمی‌شود.
کلید فقط روی سرور سایت شما بماند. آن را در جاوااسکریپت صفحه، اپ موبایل یا مخزن کد نگذارید.
دسترسی‌ها (scope)
هنگام ساخت کلید مشخص می‌کنید چه کاری مجاز است:
| دسترسی | نام در پنل | مسیرها |
|---|---|---|
orders.write | ثبت سفارش، پرداخت و برگشت | سفارش‌ها، پرداخت، برگشت، وب‌هوک |
catalog.read | خواندن فهرست کالاها | GET /products/ |
مسیر GET /ping/ با هر کلید معتبری کار می‌کند.
محدود کردن به IP
اگر سرور سایت IP ثابت دارد، هنگام ساخت کلید آن را در «محدود به IP» بنویسید. درخواست با آن کلید از هر IP دیگری رد می‌شود (401).
آزمایش کلید
GET/api/v1/ping/
curl https://panel.nemosystem.ir/api/v1/ping/ \
-H "Authorization: Bearer $NEMO_KEY"{ "organization": "شرکت نمونه", "scopes": ["orders.write"] }قواعد کلی
- قالب: بدنهٔ درخواست و پاسخ JSON با UTF-8 است؛
Content-Type: application/jsonبفرستید. - مبلغ‌ها به ریال و عدد صحیح‌اند. اگر فروشگاه تومانی است، پیش از ارسال در ۱۰ ضرب کنید.
- تاریخ‌ها میلادی‌اند به شکل
YYYY-MM-DD(مثلاً2026-10-01). - محدودیت تعداد: ۱۲۰ درخواست در دقیقه برای هر کلید. بیشتر از آن پاسخ
429می‌گیرد؛ یک دقیقه بعد دوباره بفرستید. - اشتراک: اگر اشتراک سازمان تمام شده یا ماژول «اتصال فروشگاه آنلاین» فعال نیست، درخواست‌ها
403می‌گیرند. در مهلت پس از پایان اشتراک فقط خواندن (GET) کار می‌کند. - تکرار بی‌خطر: ارسال دوبارهٔ یک سفارش هیچ‌وقت فاکتور دوم نمی‌سازد؛ با خیال راحت در صورت قطعی یا timeout دوباره بفرستید. (بیشتر)
شناسهٔ منبع (source)
هر سفارش با دو مقدار شناخته می‌شود: source (کدام فروشگاه) و external_id (شمارهٔ سفارش در همان فروشگاه). اگر چند فروشگاه را به یک سازمان وصل می‌کنید، برای هر کدام source جدا بفرستید — مثلاً site:shop.example.com و app:android — تا شمارهٔ سفارش‌هایشان با هم قاطی نشود. اگر نفرستید، api در نظر گرفته می‌شود.