مفاهیم اولیه
معرفی REST API

همان طور که شاید تا به حال شنیده باشید API مخفف عبارت Application Programming Interface می باشد که به برنامه نویسان امکان رد و بدل کردن اطلاعات مابین پلتفرم های مختلف را از طریق ارسال یک درخواست HTTP(S) ساده و فراخوانی متد های مورد نظر می دهد. در واقع REST یکی روش ساده و انعطاف پذیری برای استفاده از API است و البته محبوب ترین و پر کاربرد ترین که می توان توسط این ساختار از هر کلاینت و پلتفرمی درخواست ساده HTTP)S) را ارسال و پاسخ آن را دریافت نمود. حال فرض کنید در خواست مورد نظر اطلاعات مربوط به ارسال یک مرسوله باشد و جواب آن نتیجه و وضعیت مرسوله ارسالی باشد.

نکته : اگر با JSON آشنائی ندارید می توانید با مراجعه به سایت json.org هم از ساختار فرمت آن مطلع شوید و هم درایور مربوط به زبان برنامه نویسی مورد نظر خود را دریافت نمائید.

فهرست

ویرایش ها و تغییرات

ردیف تاریخ ورژن توضیحات
۱ ۱۳۹۷/۱۱/۱۱ -۳۱-January ۱٫۰٫۰ ارائه سرویس api  ورژن ۱

شروع

دریافت توکن 

ابتدا از پنل کاربری خود توکن گرفته و در قسمت header در request خود ست کنید:

Authorization : jwt eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiMjE0Mm

تذکر : در صورتی که توکن خود را در قسمت هدر ست نکرده باشید در صورت کلیک بر روی لینک های زیر با پیفام “Authentication credentials were not provided.” مواجه می شوید.

توجه : برای دریافت توکن در پنل پستی خود از قسمت توکن اقدام نمایید.   برای ورود به پنل اینجا کلیک کنید.

توجه : فیلد هایی که null آنها True میباشند، اجباری نیستند و شما میتوانید این فیلد ها را null ارسال کنید

۱گرفتن لیست استان ها :

http://api.tapin.com/api/v1/webservice/location/provinces/ آدرس
GET متد

نمونه دیتای خروجی با فرمت JSON :

{
    "status": {
        "code": 0,
        "message": "عملیات موفق"
    },
    "entries": {
        "provinces": [
            {
                "code": 1,
                "title": "تهران"
            },
            {
                "code": 2,
                "title": "گیلان"
            }
        ],
        "page": 1,
        "count": 2,
        "total_count": 31
    }
نام فیلد نوع Null توضیحات
code String False کد استان
title String False نام استان

۲گرفتن لیست شهر های یک استان:

<province_code>/ آدرس
GET متد

مثال : برای گرفتن لیست شهر های استان تهران باید در  url به جای <province_code> کد استان تهران ( ۱ )  را وارد نمایید .

             http://api.tapin.com/api/v1/webservice/location/cities/1/

نمونه دیتای خروجی با فرمت JSON :

{
    "status": {
        "code": 0,
        "message": "عملیات موفق"
    },
    "entries": {
        "cities": [
            {
                "code": 1,
                "title": "تهران"
            },
            {
                "code": 331,
                "title": "اسلام شهر"
            }
        ],
        "page": 1,
        "count": 2
        "total_count": 115
    }
}
توضیحات Null نوع نام فیلد
کد شهر False String code
نام شهر False String title

۳گرفتن لیست محصولات ثبت شده

توجه : استفاده از این قسمت اجباری نیست و میتوانید هنگام ثبت سفارش اطلاعات محصولات خود را ارسال نمایید.

http://api.tapin.com/api/v1/webservice/product/list/ آدرس
POST متد

پارامتر های مورد نیاز:

توضیحات null نوع نام فیلد
شماره صفحه مورد نظر False Integer page
تعداد محصولات جهت نمایش در یک صفحه False Integer count
شناسه فروشگاه False Integer shop_id

نمونه دیتای ورودی با فرمت JSON :

{
	"shop_id":"e957fc3f-f27b-416c-b312-d3d4f3dc35db",
	"page": 1,
	"count":10
}

نمونه دیتای خروجی با فرمت JSON :

{
"status": {
"code": 0,
"message": "عملیات موفق"
},
"entries": [
{
"product_id": 1036,
"product_category_id": "3421e307-1b61-4130-a3ed-7e52d8f6260f",
"title": "کتاب بوستان سعدی",
"price": 900000,
"weight": 400,
"description": null,
"is_active": true
}
]
}
توضیحات null نوع نام فیلد
شناسه محصول False Integer product_id
شناسه گروه محصول False String product_category_id
نام محصول False String title
مبلغ محصول False Integer price
وزن محصول False Integer weight
توضیحات محصول False String description
وضعیت محصول (فعال، غیر فعال) False Boolean is_active

۴ استعلام قیمت:

http://api.tapin.com/api/v1/webservice/order/check-price/  آدرس
 POST  متد

پارامتر های مورد نیاز:

نام فیلد ها نوع null حداکثر کارکتر مجاز توضیحات
shop_id String False کد فروشگاه که هنگام گرفتن توکن ارسال شده است
address String False ۳۰۰ ادرس گیرنده
city Integer False کد شهر گیرنده
province Integer False کد استان گیرنده
description String True ۲۵۰ توضیحات
email String True ۵۰ ایمیل گیرنده
first_name String False ۳۰ نام گیرنده
last_name String False ۴۰ نام خانوادگی گیرنده
mobile String False ۱۱ شماره همراه گیرنده
phone String True ۱۱ شماره تلفن گیرنده
postal_code String False ۱۰ کد پستی گیرنده
pay_type Integer False نحوه پرداخت
send_type Integer False نحوه ارسال
product List False محصولات

* فیلد product یک لیست از جیسون ها میباشد که شامل فیلد های زیر میباشد:

تذکر : در هنگام ارسال اطلاعات محصول ( product ) میتوانید از دو روش زیر استفاده نماید.

توجه پیشنهاد میشود از روش دوم برای ارسال اطلاعات محصولات موجود در سفارش استفاده شود.

۱- در صورتی که لیست محصولات خود را از قبل در پنل ثبت کرده باشید.

توضیحات null نوع حداکثر کارکتر مجاز نام فیلد ها
کد محصول False Integer product_id
تعداد محصول False Integer count
تخفیف به ازای هر محصول False Integer discount_per
مبلغ به ازای هر محصول True Integer price_per
نام محصول True Integer ۵۰ title
وزن به ازای هر محصول True integer weight_per

۲- در صورتی که لیست محصولات خود را از قبل در پنل ثبت نکرده باشید.

توضیحات null نوع حداکثر کارکتر مجاز نام فیلد ها
کد محصول True Integer product_id
تعداد محصول False Integer count
تخفیف به ازای هر محصول False Integer discount_per
مبلغ به ازای هر محصول False Integer price_per
نام محصول False Integer ۵۰ title
وزن به ازای هر محصول False integer weight_per

نکات :

– فیلد هایی که null آنها True میباشند، اجباری نیستند و شما میتوانید این فیلد ها را null ارسال کنید

– فیلد نحوه پرداخت شامل گزینه های زیر میباشد

کد نوع پرداخت
۰ پرداخت در محل
۱ پرداخت آنلاین (با اعتبار پنل)
۲ پس کرایه
۳ ارسال رایگان

-فیلد نحوه ارسال شامل گزینه های زیر میباشد:

کد نوع ارسال
۰ سفارشی
۱ پیشتاز

نمونه دیتای ورودی با فرمت JSON :

{
	"shop_id":"e957fc3f-f27b-416c-b382-d3d4f3dc35d8",
	"address":"آدرس گیرنده",
	"city": 41,
	"province": 2,
	"description": null,
	"email": null,
	"first_name":"نام",
	"last_name":"نام خانوادگی",
	"mobile":"09122222222",
	"phone": null,
	"postal_code": "1254785244",
	"pay_type":0,
	"send_type": 0,
	"product": [
		{
		"count":2,
		"discount_per": 100,
		"price_per":500,
		"title": "محصول شماره ۱",
		"weight_per": 2000,
		"product_id": null
		},
		{
		"count":1,
		"discount_per": 100,
		"price_per":null,
		"title": null,
		"weight_per": null,
		"product_id": 1010
		}
	]
}

۱- خط ۱۶ تا ۲۳ ==> روش دوم

۲- خط ۲۴ تا ۳۱ ==> روش اول

نمونه دیتای خروجی با فرمت JSON :

{
    "status": {
        "code": 0,
        "message": "عملیات موفق"
    },
    "entries": {
        "send_price": 80988,
        "tax": 7289,
        "service_price": 13952,
        "total_product_price": 500,
        "total_product_discount": 2,
        "total": 103227
    }
}
نام فیلد توضیحات
send_price هزینه ارسال
tax مالیات هزینه ارسال
service_price حق ثبت +‌هزینه خدمات + ۹٪ مالیات
total_product_price جمع هزینه کالا – جمع هزینه تخفیف کالاها
total_product_discount جمع هزینه تخفیف کالاها
total جمع کل

۵ثبت سفارش:

 

http://api.tapin.com/api/v1/webservice/order/register/ آدرس
POST متد

پارامتر های مورد نیاز و نمونه دیتای ورودی همانند پارامتر های استعلام قیمت میباشد.

نمونه دیتای خروجی با فرمت JSON :

{
    "status": {
        "code": 0,
        "message": "عملیات موفق"
    },
    "entries": {
        "id": "1c9067c6-79af-4222-83b7-5a3ed04ee915"
    }
}
نام فیلد توضیحات
id شناسه فروشگاه ثبت شده

۶دریافت لیست سفارشات:

 

http://api.tapin.com/api/v1/webservice/order/list/ آدرس
POST متد

 

پارامتر های مورد نیاز:

توضیحات null نوع نام فیلد
شماره صفحه مورد نظر False Integer page
تعداد سفارشات جهت نمایش در یک صفحه False Integer count
شناسه فروشگاه False Integer shop_id
وضعیت سفارش True Integer status

نکات

فیلد status میتواند null باشد، در این صورت همه ی سفارشات با هر وضعیتی نشان داده میشوند

جدول وضعیت ها در صفحه آخر میباشد

نمونه دیتای ورودی با فرمت JSON :

{
	"shop_id":"e957fc3f-f27b-416c-b382-d3d4f3dc35ab",
	"page":1,
	"count":10,
	"status": null
}

نمونه دیتای خروجی با فرمت JSON :

{
    "status": {
        "code": 0,
        "message": "عملیات موفق"
    },
    "entries": {
        "orders": [
            {
                "id": "1c9067c6-79af-4222-83b7-5a3ed04es915",
                "status": 1,
                "province": 2,
                "city": 41,
                "barcode": "1221458631245678964531254",
                "customer_full_name": "نام و نام خانوادگی گیرنده",
                "create_at": "۱۳۹۷-۱۱-۹ ۱۱:۶:۷",
                "total_price": 103227,
                "error": null
            },
            {
                "id": "1f20eb3f-304e-4421-8540-f2f811e8398e",
                "status": 0,
                "province": 2,
                "city": 41,
                "barcode": null,
                "customer_full_name": "نام و نام خانوادگی گیرنده",
                "create_at": "۱۳۹۷-۱۱-۸ ۱۶:۱۹:۳۴",
                "total_price": 61485,
                "error": null
            }
        ],
        "page": 1,
        "count": 2,
        "total_count": 11
    }
}
نام فیلد توضیحات
id شناسه سفارش
status وضعیت سفارش
province کد استان سفارش
city کد شهر سفارش
barcode در صورتی که سفارش بارکد گرفته باشد اینجا نمایش داده میشود در غیر این صورت این فیلد null میباشد
customer_full_name نام و نام خانوادگی گیرنده
create_at تاریخ ثبت سفارش
total_price جمع کل مبلغ سفارش
error در صورتی که سفارش مشکل داشته باشه باید این فیلد پر میشود در غیر این صورت این فیلد null میباشد
page صفحه فعلی
count تعداد سفارشات در صفحه فعلی
total_count تعداد کل مرسولات

۷تغییر وضعیت سفارش:

آدرس http://api.tapin.com/api/v1/webservice/order/change-status/
متد POST

پارامتر های مورد نیاز:

توضیحات null نوع نام فیلد
کد وضعیتی که میخواد به آن تغییر وضعیت دهید False Integer status
یک لیست از شناسه های سفارشات که میخواهید تغییر وضعیت بدهید False List orders
شناسه فروشگاه False String shop_id

* یک object از فیلد orders شامل فیلد های زیر میباشد:

توضیحات null نوع نام فیلد
شناسه سفارشی که میخواهید آن را تغیید وضعیت دهید False String id

نکات:

سفارشی که در وضعیت ۱۰۰ (منتظر استعلام) هستند رو فقط میتوانید به وضعیت ۸۰ (حذف شده) تغییر وضعیت دهید.

سفارشاتی که در وضعیت ۰ (معلق) هستند رو میتواند به وضعیت۸۰ (حذف شده) و ۱ (آماده به پرینت) تغییر وضعیت دهید.

سفارشاتی که در وضعیت ۱ (آماده به پرینت) هستند رو میتوانید به وضعیت ۸۰ (حذف شده) و ۲(آماده به ارسال) تغییر وضعیت دهید

سفارشاتی که در وضعیت ۲ ( آماده به ارسال) میباشند رو فقط میتوانید به وضعیت ۱ (معلق) تغییر وضعیت دهید

نمونه دیتای ورودی با فرمت JSON :

{
	"shop_id":"e957fc3f-f27b-416c-d322-d3d4f3dc35db",
	"status": 1,
	"orders":[
          		{
			"id":"1f20eb3f-304e-4421-8540-b2f811e3241e"
		},
          		{
			"id":"320eb3f-303e-4321-8540-b2f811e8398s"
		}
            ]
}

نمونه دیتای خروجی با فرمت JSON :

{
    "status": {
        "code": 0,
        "message": "عملیات موفق"
    },
    "entries": [
        {
            "id": "1f20eb3f-304e-4421-8540-b2f811e3241e",
            "status": 2,
            "code": 0,
            "message": "عملیات با موفقیت انجام شد",
            "barcode": "21292000411900009359"
        },
        {
            "id": "320eb3f-303e-4321-8540-b2f811e8398s",
            "status": 2,
            "code": 111,
            "message": "امکان تغییر وضعیت این سفارش وجود ندارد",
            "barcode": null
        }
    ]
}
توضیحات Null نوع نام فیلد
شناسه سفارش False String id
وضعیت کنونی سفارش False Integer status
کد انجام عملیات( تغییر وضعیت موفق بوده یا نه) False Integer code
پیام کد انجام عملیات False String message
بارکد سفارش True String barcode

جدول کد خطاها

کد خطا پیغام
۰  عملیات موفق
۱۰۰  توکن وارد شده نا معتبر میباشد
۱۱۲  فیلد های ارسالی معتبر نمیباشند
۱۰۲  کد فروشگاه وارد شده معتبر نمیباشد
۱۰۸  فروشگاه شما غیر فعال میباشد
۱۰۳  کد محصول وارد شده نامعتبر است
۱۰۵  مبلغ محصول نامعتبر میباشد
۱۰۷  اطلاعات محصول نامعتبر میباشد
۱۰۹  سفارش مورد نظر یافت نشد
۱۱۱  امکان تغییر وضعیت این سفارش وجود ندارد
۱۱۰  اعتبار کافی نیست
۱۰۶  خطا در اتصال به پست
۱۰۴  خطا در انجام عملیات
۱۰۱  کد پستی وارد شده نامعتبر است
۴۰۱  خطا در شناسایی نام کاربری یا کلمه عبور
۴۰۲  خطا در شناسایی نام کاربری فروشنده
۴۰۳  فروشنده مورد نظر منقضی یا مسدود شده است
۴۰۴  درخواست / شناسه مورد نظر یافت نشد
۴۰۵  امکان استفاده از این سرویس ارسال برای این فروشگاه امکان پذیر نیست
۵۰۲  خطا در شناسایی  کد استان/ کدشهرستان ارسال شده
۵۰۳  امکان ارسال مرسوله برای این مقصد میسر نیست
۵۰۵  شناسه سفارش ارسال شده تکراری است
۶۰۰  این درخواست قبلا ثبت شده است
۶۰۱  تغییر وضعیتی برای نمایش وجود ندارد
۸۰۰  رشته تولید شده برای ثبت سفارش معتبر نیست
۸۰۱  تعداد سفارش ارسالی بیشتر از حد مجاز است
۸۰۲  روش ارسال / سرویس درخواستی نامعتبر است
۸۰۳  روش پرداخت درخواستی نامعتبر است
۸۰۴  پارامتر های الزامی به سامانه ارسال نگردید است
۸۰۵  وزن ارسال شده نامعتبر است
۸۰۶  قیمت ارسال شده نامعتبر است
۸۰۷  هزینه ارسال ارسال شده  نامعتبر است
۸۰۸  مالیات بر ارزش افزوده  ارسال شده نامعتبر است
۹۰۰  تعداد سفارش ارسالی بیشتر از حد مجاز است
۸۱۰  نوع سفارش نامعتبر
۱۰۰۰  سقف ارسال روزانه به اتمام رسیده است

جدول وضعیت ها

نام وضعیت کد وضعیت
ثبت شده در فروشگاه (تحت بررسی) ۰
 آماده به پرینت (معلق پستی) ۱
آماده به ارسال ۲
اشتباه در اعلام آماده به ارسال ۳
عدم حضور فروشگاه ۴
قبول شد ۵
غیر قابل توزیع ۶
توزیع شد ۷
باجه معطله ۸
غیر قابل توزیع ۹
پیش برگشتی مرسوله ۱۰
ثبت نهایی برگشتی ۱۱
مرسوله خسارتی ۱۲
مرسوله غرامتی ۱۳
تایید شده مدیر مالی ۷۰
تسویه شده مدیر مالی ۷۱
حذف شده ۸۰
بلاتکلیف ۸۱
مانده قبول ۸۲
تایید برگشتی ۸۳
منتظر استعلام ۱۰۰