اتصال به سامانه زاگما با وب سرویس
به طور کلی روال کار با API به دو بخش ارسال اطلاعات خریدار و فروشگاه دار (عضویت فروشگاه دار در سامانه الزامی می باشد) به سامانه زاگما و دریافت و نمایش اطلاعات مورد نیاز به فروشگاه دار و خریدار تقسیم می شود.
(ورژن 1.2.5)
تغییرات جدید در 1.2.5 : دریافت فاکتور و تائید سفارشات از طریق وب سرویس

ورژن 1.2
پارامتر | شرح |
username | نام کاربری (نام کاربری نمونه test) |
password | رمز ورود به سامانه (رمز برای نام کاربری نمونه 654321) |
shopkod | کد فروشگاه (در پنل سامانه زاگما، مدیریت فروشگاه » مشخصات فروشگاه » کد قرمز رنگ با نام کد فروشگاه) |
*وزن و قیمت استفاده شده به عنوان ورودی و همچنین پارامترهای خروجی مرتبط با آنها، به ترتیب بر حسب گرم و تومان می باشد.
استعلام وضعیت سفارشات ثبت شده به صورت جیسون
http://api.zagma.ir/orderstatus
http://api.zagma.org/orderstatus (لینک کمکی)
پارامتر | مقدار | وضعیت |
code | بارکد مرسوله مورد نظر | الزامی |
{
"barcod":null,"timeit":0,"vazit":0,"vaz":"false"
}
میباشد، در این حالت مقدار vaz که نشان دهنده وضعیت عملکرد میباشد برابر false است. در صورت درست اجرا شدن، مقدار vaz برابر true شده و پارامترهای زیر ایجاد میشوند: ( در فایل نمونه checkvaziat )
پارامتر (پارامتر خروجی در صورت موفق بودن درخواست) | شرح |
barcode | بارکد ارسالی مرسوله در زاگما |
barcodepost | بارکد پستی مرسوله در شرکت حمل نقل (برای پیگیری) |
vaziat | شرح وضعیت مرسوله به صورت فارسی |
zagma | کد وضعیت مرسوله در زاگما |
post | کد وضعیت مرسوله در شرکت حمل |
tarikh | تاریخ آخرین وضعیت مرسوله |
vaz | بررسی درست یا نادرست بودن نتیجه استعلام |
استعلام هزینه خدمات، ارسال دیتا به صورت جیسون
http://api.zagma.ir/requestpricepostnew (استعلام قیمت برای ثبت در پست)
http://api.zagma.org/requestpricepostnew (لینک کمکی)
http://api.zagma.ir/requestpricenedexnew (استعلام قیمت برای ثبت در ندکس)
http://api.zagma.org/requestpricenedexnew (لینک کمکی)
http://api.zagma.ir/requestpricetipaxnew (استعلام قیمت برای ثبت در تیپاکس)
http://api.zagma.org/requestpricetipaxnew (لینک کمکی)
پارامتر | مقدار | وضعیت |
shopkod | کد فروشگاه ثبت شده در زاگما | الزامی |
weight | وزن کالا به گرم | الزامی |
ostan | کد استان (طبق لیست پیوست STATE_CODE ) | الزامی |
city | کد شهرستان (طبق لیست پیوست CODE ) | الزامی |
noehazine | نوع محاسبه هزینه :
| الزامی |
pricepost | قیمت برای کرایه ثابت [کرایه وارد شده] پستی(تومان) | الزامی در صورتی که noehazine برابر 4 باشد |
price | قیمت کل سبد خرید به تومان | الزامی |
خروجی این متد در صورت نادرست بودن به صورت جیسون :
{
","code":12,"vaz":"falseفروشگاه انتخابی غیر مجاز میباشد":"
}
میباشد، در این حالت مقدار vaz که نشان دهنده وضعیت عملکرد میباشد برابر false است. در صورت درست اجرا شدن، مقدار vaz برابر true شده و پارامترهای زیر ایجاد میشوند: ( در فایل نمونه reqprice )
پارامتر (پارامتر خروجی در صورت موفق بودن درخواست) | شرح |
sefareshipmahal | هزینه خدمات برای ارسال سفارشی پرداخت در محل |
pishtazpmahal | هزینه خدمات برای ارسال پیشتاز پرداخت در محل |
sefareshionline | هزینه خدمات برای ارسال سفارشی پرداخت شده |
pishtazonline | هزینه خدمات برای ارسال پیشتاز پرداخت شده |
vaz | بررسی درست یا نادرست بودن نتیجه استعلام |
*مقدار این پارامترها در صورت درست بودن، به صورت یک عدد (برای مثال 7134.4) خواهد بود، در غیر این صورت مقدار آنها برابر با ‘نامعتبر‘ می باشد. (برای مثال استان هرمزگان»کیش که تنها به صورت ارسال پیشتاز آنلاین {پرداخت شده} قابل ارسال است، همچنین در صورتی که نوع هزینه گزینه یک {ثابت} قرار داده شود، خروجی پارامترها کلمه ‘رایگان‘ می باشد.)
*فروشگاه هایی که به صورت مارکت پلیس(market place) یا چند فروشگاهی فعالیت می کنند و چندین فروشگاه در سراسر ایران دارند، می توانند با ارسال تنها کد استان فروشگاه ارسال کننده در پارامتر ostansender به علاوه پارامترهای ذکر شده در جدول استعلام هزینه خدمات (بدون ارسال کد هر فروشگاه) هزینه ارسال را دریافت نمایند، لطفا توجه داشته باشید که این قابلیت تنها برای استعلام هزینه خدمات بوده و برای ثبت سفارش حتما می بایست کد فروشگاه درست ارسال گردد.
*در صورتی که پارامترهای ارسالی درست باشد ولی به دلیل بروز اشکال فنی در ارتباط با شرکت های حمل و نقل، سیستم نتواند هزینه پستی را تخمین بزند، هزینه آنلاین به صورت “نامعتبر” اعلام می گردد ولی هزینه پرداخت در محل به صورت “بعد از ارسال” اعلام می گردد.
ثبت سفارش (به صورت سبد خرید) ارتباط از طریق جیسون با لینک
http://api.zagma.ir/orderwitharray
http://api.zagma.org/orderwitharray (لینک کمکی)
پارامتر | مقدار | وضعیت | ||||||||||
username | نام کاربری صاحب فروشگاه در زاگما | الزامی | ||||||||||
password | رمز عبور اکانت زاگما | الزامی | ||||||||||
shopkod | کد فروشگاه ثبت شده در زاگما | الزامی | ||||||||||
mobile | شماره تماس خریدار | الزامی | ||||||||||
phone | شماره ثابت خریدار | میتواند خالی باشد | ||||||||||
weight | *وزن کل سبد خرید به گرم (*این وزن با جمع وزن سبد ارسالی مقایسه شده و بیشترین وزن اعمال می گردد) | الزامی | ||||||||||
pay | نوع پرداخت هزینه :
| الزامی | ||||||||||
noersal | *نوع ارسال :
(*برای روشهای دیگر عدد یک را انتخاب نمایید) | الزامی | ||||||||||
ostan | کد استان (طبق لیست پیوست STATE_CODE ) | الزامی | ||||||||||
city | کد شهرستان (طبق لیست پیوست CODE ) | الزامی | ||||||||||
price | *قیمت کل سبد خرید به تومان (*این قیمت با جمع قیمت سبد ارسالی مقایسه شده و بیشترین قیمت اعمال می گردد) | الزامی | ||||||||||
buyer | نام خریدار | الزامی | ||||||||||
adress | آدرس خریدار | الزامی | ||||||||||
codepos | کد پستی خریدار | الزامی | ||||||||||
آدرس ایمیل خریدار | میتواند خالی باشد | |||||||||||
cart | *سبد خرید آرایه ای به صورت جیسون ارسال میگردد، در صورتی که تمام کالای سبد خرید در زاگما در قسمت انبارداری و یا در فراگما ثبت شده اند، به منظور انبارداری و مدیریت کالاهایتان لطفا قیمت و وزن و کد موجود در زاگما را ارسال نمایید. (*کد کالاهای انبار در قسمت مدیریت انبار»لیست کالاهای موجود در انبار به صورت رنگ قرمز مشخص شده است) (*کد کالاهای فراگما در قسمت مدیریت کالاهای فروشگاه»لیست کالاهای ثبت شده به صورت رنگ قرمز مشخص شده است)
| الزامی | ||||||||||
noehazine | نوع محاسبه هزینه :
| الزامی | ||||||||||
pricepost | قیمت برای کرایه ثابت [هزینه ارسال دلخواه] پستی(تومان) | الزامی در صورتی که noehazine برابر 4 باشد | ||||||||||
id | کد سبد خرید ثبت شده در فروشگاه مربوطه | میتواند ارسال نشود |
خروجی این متد در صورت نادرست بودن به صورت جیسون :
{
","code":11,"vaz":"falseنام کاربری یا رمز عبور نادرست میباشد":""dali
}
میباشد، در این حالت مقدار vaz که نشان دهنده وضعیت عملکرد میباشد برابر false است. در صورت درست اجرا شدن، مقدار vaz برابر true شده و پارامترهای زیر ایجاد میشوند: ( در فایل نمونه sabsefaresharray )
پارامتر (پارامتر خروجی در صورت موفق بودن درخواست) | شرح |
barcod | بارکد سفارش ثبت شده |
vaz | بررسی درست یا نادرست بودن نتیجه استعلام |
در حالت عادی قیمت کل سبد خرید به عنوان قیمت نهایی مرسوله در نظر گرفته می شود، ولی با ارسال پارامتر exceptions جمع قیمت مرسولات موجود در سبد خرید به عنوان قیمت نهایی در نظر گرفته می شود.
در صورتی که کالاهای موجود در انبارهای زاگما و یا در فراگما ثبت شده بودند، لطفا در کنار اطلاعات بالا عبارت زیر را هم برای انبارداری kalaja را برابر a و برای کالاهای موجود در فراگما kalaja را برابر f قرار دهید.
kalaja | برای انبارداری a و برای فراگما f | الزامی در صورتی که کالا در انبار زاگما و یا فراگما موجود باشد |
default | اگر برابر no باشد برای ثبت سفارش وزن و قیمت و نام ارسالی در نظر گرفته می شود (برای کالاهای موجود در انبار همواره وزن از انبار خوانده شده )، در غیر این صورت وزن و قیمت و نام موجود در انبار/فراگما در نظر گرفته می شود | اختیاری |
اعمال هزینه بسته بندی بر روی مرسولات ارسالی :
- در پنل مدیریت زاگما وارد قسمت مدیرت فراگما » تنظیمات فراگما شده و هزینه بسته بندی مورد نظرتان را برای تمام مرسولات ثبتی اعمال نمایید.
- در وب سرویس هنگام ثبت سفارش مقدار هزینه بسته بندی را به تومان توسط پارامتر packaging اعمال نمایید.
همچنین میتوانید در قسمت مدیرت فراگما » تنظیمات فراگما عبارت “هزینه بستهبندی” که بر روی فاکتورهای پرینت شده، نمایش داده می شود را تغییر دهید.
پنهان کردن نام مرسولات ارسالی (افزایش امنیت مرسولات ارسالی) :
- در پنل مدیریت زاگما وارد قسمت مدیریت فراگما » تنظیمات فراگما شده و نام جدید را برای تمام مرسولات ثبتی وارد نمایید.
- در وب سرویس هنگام ثبت سفارش نام جدید کالا را توسط پارامتر newkalaname اعمال نمایید.
کد وضعیت در شرکت حمل (به تفضیل) :
کد وضعیت | شرح کد |
1 | معلق در فروشگاه |
2 | آماده قبول |
3 | اشتباه در اعلام آماده ارسال |
4 | عدم حضور مدیر فروشگاه |
5 | قبول شده |
6 | غیرقابل توزیع |
7 | توزیع شده |
8 | باجه معطله |
9 | غیرقابل توزیع |
10 | پیش برگشتی مرسوله |
11 | ثبت نهایی برگشتی |
12 | مرسوله خسارتی |
13 | مرسوله غرامتی |
70 | تایید شده مدیر مالی |
71 | تسویه شده مدیر مالی |
کد وضعیت در زاگما (به تفضیل) :
کد وضعیت | شرح کد |
1 | تسویه با بازاریاب |
2 | تسویه با فروشگاه |
3 | *قابل پرداخت |
4 | مردود |
5 | نیازمند تائید سفارش توسط فروشگاه دار |
6 | نیازمند تائید سفارش توسط منشی |
7 | نیازمند تائید سفارش توسط همکار |
8 | نیازمند تائید سفارش توسط همکار کامل |
9 | نیازمند تائید سفارش توسط بازاریاب |
10 | نیازمند تائید سفارش توسط فروشگاه دار به عنوان بازاریاب |
11 | نیازمند تائید انباردار برای ارسال |
12 | تائید سفارش توسط خریدار |
13 | نیازمند تائید فروشنده برای ارسال |
14 | نیازمند تائید فروشگاه دار برای ارسال |
15 | نیازمند تائید تأمینکننده برای ارسال |
16 | *معلق در فروشگاه |
17 | آماده قبول |
18 | اشتباه در اعلام آماده ارسال |
19 | عدم حضور مدیر فروشگاه |
20 | دریافت شده آماده توزیع |
21 | در حال توزیع*(توقیف شده) |
22 | در حال توزیع با پیک موتوری |
23 | توزیع شده |
24 | توزیع شده باپیک موتوری |
25 | *باجه معطله |
26 | غیرقابل توزیع |
27 | پیش برگشتی مرسوله |
28 | ثبت نهایی برگشتی |
29 | ثبت نهایی برگشتی بازگشت کالا به فروشگاه |
30 | مرسوله خسارتی |
31 | مرسوله غرامتی |
32 | *تائید وجه دریافتی توسط پست |
33 | *بررسی برای پرداخت توسط پست |
34 | *تائید شده درانتظار مأمور پست |
35 | *تائید شده توسط خریدار |
36 | *انصراف خریدار |
باجه معطله : در این حالت در صورتی که خریدار مرسوله در مقصد مورد نظر نباشد و مرسوله 2-3 روز در شعبه شرکت حمل و نقل در شهر مقصد می ماند در این حالت پستچی 1-2 بار دیگر به مقصد مورد نظر برای تحویل کالا مراجعت می کند و در صورت عدم پاسخگویی مجدد مرسوله برگشت می خورد.(خریدار مرسوله با مراجعه به شعبه شرکت حمل و نقل می تواند به صورت دستی مرسوله را دریافت کند.)
انصراف خریدار/تائید شده توسط خریدار : در این حالت در هنگامی که از خریدار تائید پیامکی برای ارسال مرسوله گرفته می شود، خریدار درخواست خود را اعلام می کند.
معلق : در این حالت فروشگاه دار مرسوله رو به صورت معلق در آورده و آن را اسال نکرده است.
تائید شده در انتظار مامور پست : در این حالت مرسوله توسط فروشگاه دار اماده تحویل به پستچی می باشد.
تائید وجه دریافتی توسط پست/تائید شده درانتظار مأمور پست/بررسی برای پرداخت توسط پست : در این حالتها شرکت حمل و نقل مربوطه در حال بررسی پرداخت پول به زاگما می باشد.
قابل پرداخت : در این حالت پست به زاگما مبلغ مرسوله مورد نظر را پرداخت کرده است و زاگما می تواند با فروشگاه دار تسویه کند.
کد وضعیت در زاگما (به صورت خلاصه دسته بندی شده یک) :
گروه کد وضعیت | شرح خلاصه کد |
17-20-22 | درحال توزیع |
1-2-3-23-24-32-33 | توزیع شده |
27-28-29 | برگشتی |
18-19-21-26-30-31 | مرسولات غیر قابل توزیع |
25 | باجه معطله |
4-36 | انصرافی |
5 تا 16 | معلق |
34 | تایید شده در انتظار مامور پست |
کد وضعیت در زاگما (به صورت خلاصه دسته بندی شده دو) :
گروه کد وضعیت | شرح خلاصه کد |
1-2-3-23-24-32-33 | قبول شده |
27-28-29 | رد شده |
17-20-22 | درحال توزیع |
25 | باجه معطله |
18-19-21-26-30-31 | غیر قابل پذیرش |
4 تا 16 – 36 | نیازمند تائید فروشگاه دار |
34 | تایید شده در انتظار مامور پست |
توجه : لطفا توجه داشته باشید که محدودیت برای ثبت سفارشات با کمک API هر 25 ثانیه می باشد، برای رفع این محدودیت می توانید در قسمت مدیریت فروشگاه، مشخصات فروشگاه آی پی فروشگاهتان را در قسمت IP خاص برای استفاده از وب سرویس وارد نمایید، تا دیگر این محدودیت برای شما ایجاد نشود.
توجه : در ارسال کالا از طریق وب سرویس(API) مرسولات از طریق id (کد سبد خرید ثبت شده در فروشگاه مربوطه) تفکیک می شوند، از این رو لطفا در نظر داشته باشید که برای مرسولات کد id متمایز انتخاب نمایید(و یا این پارامتر را خالی بگذارید)، در غیر این صورت مرسولات تکراری در نظر گرفته می شوند.
توجه : لطفا توجه داشته باشید که برای حذف محدودیت وزن مرسولات سفارشی/پیشتاز بیشتر از 30 کیلوگرم که توسط پست ایجاد شده است(به منظور ارسال بدون محدودیت وزنی)، حتما در قسمت مدیریت فروشگاه»تنظیمات فروشگاه تیک تفکیک مرسولات سنگین به مرسولات سبکتر را بزنید.
توجه : همچنین برای رند کردن هزینه فاکتور تیک گرد کردن (رند کردن) مبلغ نهایی را در قسمت مدیریت فروشگاه»تنظیمات فروشگاه تیک را فعال نمایید.
توجه : لازم به ذکر است برای تعیین هزینه بسته بندی تیک اعمال هزینه بستهبندی را در قسمت مدیریت فروشگاه»تنظیمات فروشگاه را فعال نمایید.
اسکریپت نمایش وضعیت مرسوله ارسالی/پیگیری سفارش ارسالی :
<style>.h_iframe-zagma_embed_frame{position:relative;}.h_iframe-zagma_embed_frame .ratio{display:block;width:100%;height:auto;}.h_iframe-zagma_embed_frame iframe{position:absolute;top:0;left:0;width:100%;height:100%;}</style><div class=”h_iframe-zagma_embed_frame”><span style=”display: block;padding-top: 57%”></span><iframe src=”https://www.zagma.ir/order-tracking-iframe.html” allowFullScreen=”true” webkitallowfullscreen=”true” mozallowfullscreen=”true”></iframe></div>
پیش نمایش :
دریافت لیست شهرها :
لیست شهرهای تحت پوشش زاگما هر چند وقت آپدیت شده و وسعت بیشتری میگیرد، به این منظور میتوانید لیست شهرها را در هر لجظه بر حسب استان ارسالی دریافت نمایید.
در این حالت مقدار state که کد استان مورد نظر می باشد به لینک :
http://api.zagma.ir/cityfromstate
http://api.zagma.org/cityfromstate(لینک کمکی)
ارسال می گردد و در پاسخ شهرهای آن استان (name) به همراه کد آن شهر (code) دریافت می گردد.
تائید سفارشات :
http://api.zagma.ir/changestatusorder
http://api.zagma.org/changestatusorder(لینک کمکی)
پارامتر | مقدار | وضعیت |
username | نام کاربری صاحب فروشگاه در زاگما | الزامی |
password | رمز عبور اکانت زاگما | الزامی |
shopkod | کد فروشگاه ثبت شده در زاگما | الزامی |
code | بارکد مرسوله مورد نظر | الزامی |
function | عملیات مورد نظر بر روی مرسوله r = معلق کردن سفارش s = آماده ارسال | الزامی |
خروجی این متد در صورت نادرست بودن به صورت جیسون :
{ ","code":12,"vaz":"falseفروشگاه انتخابی غیر مجاز میباشد":" }
میباشد، در این حالت مقدار vaz که نشان دهنده وضعیت عملکرد میباشد برابر false است. در صورت درست اجرا شدن، مقدار vaz برابر true شده و سیستم بر حسب اینکه مرسوله را فعال یا غیر فعال کرده باشید پیغام :
[dalil] => سفارش مورد نظر به درستی معلق شد [vaz] => true
[dalil] => سفارش مورد نظر به درستی به آمده ارسال تغییر وضعیت داد [vaz] => true
دریافت فاکتور :
در وب سرویس جدید با ارسال بارکد مرسوله میتوانید
http://api.zagma.ir/showinvoice?code=barcode
http://api.zagma.org/showinvoice?code=barcode(لینک کمکی)
فاکتور مرسوله مورد نظر را دریافت نمایید. در صورتی که می خواهید فاکتور مورد نظر با راهنمای پرینت قابل دسترس باشد کافیست عبارت &help=yes در انتهای لینک مربوطه قرار دهید.