API پیشگامان پل ارتباط نرمافزار شما با وب و اپلیکیشن
کالا، قیمت، موجودی، مشتری و سفارش را بین نرمافزار پیشگامان و سامانههای دیگر تبادل کنید؛ با رابط برنامهنویسی مشخص و بدون ثبت دوباره اطلاعات در هر سیستم.
زیرسیستم API پیشگامان، مسیر دریافت و ارسال اطلاعات را برای فروشگاه اینترنتی، اپلیکیشن و سامانه اختصاصی فراهم میکند. پیشگامان پلاگین اختصاصی وردپرس و ووکامرس نیز دارد؛ برای بهروزرسانی کالاها و مشخصات آنها در فروشگاه اینترنتی و ارسال فاکتورهای فروش به سرور حسابداری پیشگامان.
یک جریان ارتباطی، چند کاربرد
نرمافزار پیشگامان و سامانه شما، از طریق یک رابط مشخص
قیمت و مشتری ↓
↑ سفارش و فروش
اطلاعات مجاز
ارتباط دیجیتال، در کنار نرمافزار اصلی پیشگامان
API یک زیرسیستم است، نه جایگزین نرمافزار اصلی. سامانه مقصد اطلاعات را از پیشگامان دریافت میکند و عملیات پشتیبانیشده را با قرارداد داده مشخص به سرویس آن میفرستد.
امکانات زیرسیستم API پیشگامان
مسیرهای دریافت و ثبت اطلاعات، برای اتصال عملیاتی سامانههای شما.
کالا، بارکد و گروهبندی
دریافت کد و نام کالا، بارکد، توضیحات، گروه و مسیر گروه کالا. امکان دریافت لیست کالا یا فیلتر بر اساس کد، گروه و ویژگیهای پشتیبانیشده برای استفاده در سایت و اپلیکیشن.
قیمت، تخفیف و موجودی
دریافت نرخ فروش، قیمت اصلی، درصد تخفیف و موجودی؛ همراه با موجودی کل انبارها در دادههای کالا. امکان انتخاب کالاهای دارای موجودی مثبت، برای هماهنگی نمایش اطلاعات فروش.
سایز، رنگ و تنوع کالا
دریافت فهرست سایزها و رنگها و ترکیب کالا/سایز/رنگ با بارکد ترکیبی، قیمت و موجودی. خروجی مناسب محصولات ساده و متغیر ووکامرس برای اتصال فروشگاههای دارای تنوع کالا.
تصاویر و اطلاعات تغییرکرده
دریافت تصاویر کالا بههمراه شناسه محتوای تصویر و دریافت کالاهای تغییرکرده. برداشت مرحلهای اطلاعات با تعیین نقطه شروع و تعداد رکورد، برای مدیریت حجم تبادل داده.
معرفی و ویرایش مشتری
دریافت مشتریان و اطلاعات تفصیلی با شناسه؛ همچنین ثبت مشتری جدید و ویرایش مشتری موجود شامل نام، شناسه، آدرس و اطلاعات تماس، مطابق مجوزهای سرویس پیشگامان.
مانده و وضعیت حساب مشتری
دریافت اطلاعات مشتریان رده انتخابشده در تنظیمات فروش اینترنتی، همراه مبلغ مانده و وضعیت بدهکار، بستانکار یا تسویه. امکان درخواست اطلاعات یک مشتری با کد تفصیلی.
اطلاعات مشترکان
دریافت لیست یا مشخصات یک مشترک، ایجاد اشتراک جدید و ویرایش اطلاعات موجود. انتقال نام و نام خانوادگی، اطلاعات تماس، آدرس و مشخصات پشتیبانیشده، برای یکپارچهسازی اطلاعات اشتراک.
ثبت سفارش یا فروش قطعی
ارسال اقلام شامل کد کالا یا بارکد، تعداد، قیمت، تخفیف و سایز/رنگ، همراه اطلاعات مشتری، هزینه ارسال و وضعیت پرداخت ثبتشده. امکان تعیین ثبت سفارش یا تحویل فروش قطعی و دریافت شماره سند از پیشگامان.
اطلاعات فروش و فاکتورهای مشترکان
دریافت جمع فروش، سربرگ و جزئیات فروش مشتریان و مشترکان از مسیرهای مربوط. دریافت فاکتورهای مشترکان با سربرگ و ردیفها و فیلتر مشترک، شماره فاکتور و نوع سند، در دوره مالی تنظیمشده اتصال.
بهروزرسانی منتخب از ووکامرس
مسیر بهروزرسانی کالای موجود در پیشگامان از اطلاعات ووکامرس: نام، نرخ فروش، قیمت اصلی، درصد تخفیف و تصویر. انتخاب فیلدهای قابل تغییر در درخواست انجام میشود؛ این مسیر برای ایجاد دلخواه همه اطلاعات کالا نیست.
احراز هویت و تنظیمات اتصال
دریافت توکن JWT و استفاده از آن در درخواستهای محافظتشده. پشتیبانی از شناسه اتصال برای انتخاب پیکربندی مشتری تعریفشده و استفاده از دوره، کاربر و تنظیمات سرویس مربوط.
مستندات و نتیجه عملیات
رابط HTTP با دادههای JSON، مستندات Swagger و نمونه درخواستهای Postman برای توسعهدهندگان. پاسخها وضعیت موفقیت، پیام عملیات و داده یا شماره سند را برای پیگیری نتیجه در اختیار سامانه مقصد میگذارند.
قابلیتهای قابل استفاده به نسخه API و سرویس اصلی، مجوزهای تنظیمشده و پیکربندی مجموعه بستگی دارد. API بهتنهایی رابط کاربری فروشگاه، درگاه پرداخت، زمانبند همگامسازی یا سامانه آفلاین ایجاد نمیکند؛ این بخشها در سامانه مقصد یا افزونه اتصال مدیریت میشوند.
پلاگین وردپرسی پیشگامان؛ بهروزرسانی کالا و ارسال فاکتور
پلاگین وردپرسی پیشگامان، فروشگاه ووکامرس شما را به سرور حسابداری پیشگامان متصل میکند. کالاها و مشخصات آنها، قیمت، تخفیف و موجودی از نرمافزار دریافت و در فروشگاه اینترنتی بهروزرسانی میشوند. اطلاعات سفارش و فاکتور فروش نیز همراه مشخصات مشتری و اقلام، از طریق API به سرور حسابداری ارسال میشود و شماره سند ثبتشده برای پیگیری در دسترس قرار میگیرد.
- دریافت و بهروزرسانی کالاها، نام و توضیحات، گروهبندی، قیمت، تخفیف و موجودی در ووکامرس.
- استفاده از تصاویر و ساختار سایز و رنگ برای محصول و تنوعهای آن.
- ارسال فاکتور فروش و اطلاعات سفارش، مشتری و ردیفهای کالا به سرور حسابداری پیشگامان و دریافت شماره سند ثبتشده.
- با امکانات افزونه اتصال، مشاهده وضعیت ارسال و پیگیری سفارشهای ناموفق.
جهت تبادل داده را مشخص انتخاب کنید
از پیشگامان به فروشگاه: اطلاعات کالا، قیمت و موجودی، دستهبندی، تصاویر و تنوعهای سایز و رنگ.
از فروشگاه به پیشگامان: سفارش یا فروش و اطلاعات مشتری در مسیرهای مربوط؛ همچنین فیلدهای منتخب کالای موجود، در صورت استفاده از مسیر بهروزرسانی.
پیش از راهاندازی، مرجع قیمت و موجودی، شناسه تطبیق کالا، فیلدهای مجاز بهروزرسانی و زمان اجرای تبادل تعیین میشوند تا اطلاعات دو طرف بدون تداخل مدیریت شود.
یک نمونه جریان سفارش از سایت تا پیشگامان
دریافت اطلاعات کالا
سامانه مقصد اطلاعات مورد نیاز کالا، قیمت، موجودی و تنوع را از API دریافت میکند.
ساخت سفارش در سامانه مقصد
مشتری در سایت یا اپلیکیشن سفارش میدهد؛ سامانه مقصد اقلام و اطلاعات لازم را آماده میکند.
ارسال به سرویس پیشگامان
درخواست ثبت با توکن معتبر و تعیین سفارش یا فروش قطعی، به API ارسال میشود.
کنترل نتیجه ثبت
سامانه مقصد نتیجه عملیات و شماره سند را بررسی و ذخیره میکند؛ در خطا، روند پیگیری خودش را اجرا میکند.
داکیومنت ارتباط با API پیشگامان
راهنمای فارسی اتصال و استفاده از API پیشگامان — نسخه 1.0.11
فایل PDF · ۴۲ صفحه · حدود ۲۵۲ کیلوبایت
قرارداد داده روشن، اتصال قابل بررسی
برای اتصال یک سامانه اختصاصی، از مسیرهای موجود API و مدلهای JSON استفاده میشود. مستندات فنی، نمونه درخواستها و ساختار خروجی پس از بررسی سناریوی اتصال در اختیار تیم توسعه قرار میگیرد.
- HTTP و JSON برای خواندن و ثبت اطلاعات.
- احراز هویت توکنی JWT برای مسیرهای محافظتشده.
- مستندات Swagger و مجموعه درخواستهای Postman در پروژه.
- پاسخ نتیجه عملیات با وضعیت موفقیت و پیام قابل پیگیری.
- دریافت مرحلهای کالا و تصویر برای کنترل حجم درخواستها.
وجود مسیر API به معنی اتصال آماده به هر سامانه نیست. برای سامانه اختصاصی، توسعه رابط، تطبیق مدل داده و آزمون تبادل لازم است. آدرس سرویس و اطلاعات دسترسی در زمان راهاندازی و بهصورت غیرعمومی ارائه میشوند.
نمونه مسیرهای قابل استفاده
این مسیرها صرفاً برای آشنایی با ساختار رابط هستند؛ آدرس سرویس فعال یا اطلاعات ورود در این صفحه منتشر نمیشود.
GET /api/Product/{FromCode}/{Count}GET /api/CustomerInfo?code={CustomerCode}POST /api/SubmitInvoiceGET /api/SubscriberSaleInvoices/{subscriberCode}
برای بررسی موفقیت، فقط کد HTTP کافی نیست؛ وضعیت موفقیت و پیام پاسخ API نیز باید خوانده شود.
پرداخت بانکی توسط سامانه مقصد انجام میشود؛ ارسال وضعیت پرداخت در API، بهمعنی پردازش تراکنش بانکی در این زیرسیستم نیست.
پرسشهای متداول زیرسیستم API
آیا API یک نرمافزار مستقل است؟
خیر. این زیرسیستم برای ارتباط سامانههای دیگر با نرمافزار و سرویس اصلی پیشگامان است و نیازمند نسخه و پیکربندی سازگار در مجموعه است.
آیا API فقط برای ووکامرس کاربرد دارد؟
خیر. ووکامرس یک سناریوی اتصال با افزونه مربوط است. سایت یا اپلیکیشن اختصاصی نیز میتواند با توسعه رابط مناسب، از مسیرهای پشتیبانیشده HTTP و JSON استفاده کند.
آیا همه اطلاعات در هر دو جهت قابل تغییر هستند؟
خیر. دریافت کالا و موجودی، ثبت مشتری و مشترک، ثبت سفارش یا فروش و بهروزرسانی منتخب کالای موجود هرکدام مسیر و محدودیت خود را دارند. امکان تغییر همه بخشهای نرمافزار یا ایجاد کالا از هر سامانه ادعا نمیشود.
آیا همگامسازی آنی و دائمی انجام میشود؟
API مسیر تبادل درخواست و پاسخ را فراهم میکند. زمان اجرا، تعداد رکورد و روش پیگیری خطا در سامانه مقصد یا افزونه اتصال تعیین میشود؛ همگامسازی خودکارِ لحظهای بهصورت عمومی تضمین نمیشود.
امکان دریافت مانده حساب و فاکتور مشتری وجود دارد؟
مسیر اطلاعات تفصیلی با مانده و وضعیت حساب، و مسیرهای اطلاعات فروش وجود دارند. برای مشترکان، فاکتور با سربرگ و ردیفها نیز قابل دریافت است. دسترسی و دوره مالی بر اساس تنظیمات سرویس تعیین میشود.
پیش از راهاندازی چه چیزهایی بررسی میشود؟
نسخه API و سرویس اصلی، دسترسی ارتباطی، مجوزهای عملیاتی، دوره و انبار، شناسههای تطبیق کالا و مشتری، جهت بهروزرسانی و روش پیگیری نتیجه بررسی میشوند. آزمون اتصال روی داده کنترلشده قبل از بهرهبرداری ضروری است.
سامانه شما، متصل به پیشگامان
برای بررسی نیاز اتصال سایت، اپلیکیشن یا سامانه اختصاصی، با پیشگامان در ارتباط باشید.