خرید (فرآیند صدور فاکتور)

توکن یکبار مصرف

برای استفاده از برخی از API ها که تعداد دفعات اجرای آنها مهم است، لازم است پارامتر ott در هدر ارسال شود. این پارامتر در هر درخواست که به سرور ارسال می گردد تغییر می کند و ott جدید در پاسخ در خواست صادر می گردد. برای دریافت این پارامتر از سرویس زیر استفاده کنید:

شناسه سرویس : 29819

 شناسه سرویس سندباکس : 39311 

توضیحات

مقدار

نام پارامتر

ورودی

Header

توکن ثابت کسب وکار، که از پنل کسب وکار قابل دریافت است

yourBusinessToken

_token_

این پارامتر همواره دارای مقدار ثابت 1 است .

1

_token_issuer_

این پارامتر نوع داده ارسالی به سرور را مشخص میکند که همواره باید دارای مقدار ثابت application/x-www-form-urlencoded'  باشد

application/x-www-form-urlencoded

Content-Type

Body

شناسه سرویس

29816

scProductId

این مقدار را بعد از درخواست سرویس و تایید پادیوم ، میتوانید از پنل یا از طریق api دریافت نمایید.

کلید فراخوانی سرویس

scApiKey

خروجی

در صورت وقوع خطا در فراخوانی سرویس true خواهد بود

true/false

hasError

جهت بررسی لاگ درخواست و ریسپانس توسط کارشناسان پادیوم ، استفاده میشود. توصیه می شود این پارامتر را برای هر درخواست ذخیره کنید.

string

referenceNumber

شناسه  ott دریافتی از سرویس

true/false

ott

نمونه درخواست

نمونه پاسخ

خطاهای معمول در پلتفرم

کد خطا

توضیح

21

توکن کسب­­وکاری وارد نشده است

227

تایم اوت سرویس اصلی

378

ارسال پاسخ از سرویس اصلی به پلتفرم با مشکل مواجه شده است

صدور فاکتور توسط کسب و کار برای مشتری

شناسه سرویس :  29796 و 29797

شناسه سرویس سندباکس: 39291

هرگونه پرداخت در پلتفرم پاد، از طریق فاکتور invoiceصورت می گیرد.

در این بخش صدور فاکتور با استفاده از توکن کسب و کار شرح داده شده و می توان با خروجی سرویس زیر، کاربر را به راحتی به درگاه پرداخت هدایت نمود.

* این فاکتورها عادی هستند و پس از پرداخت توسط مشتری، اعتبار کسب و کار(موجودی) افزایش مییابد. با دریافت لیست فاکتورها می توانید وضعیت آنها را مشاهده نمایید.

* لازم به ذکر است پس از صدور فاکتور، تعداد فروش محصول افزایش و availableCount  محصول کاهش خواهد یافت.

-  نمونه زیریک فاکتور با دو بند ( قلم ) را شامل می شود.

مقدارapi_token را از پنل مدیریت کسب و کار دریافت نمایید.

- اکثر عملیات مربوط به فاکتور نیاز به ott دارند که می‌توانید آن را از آخرین درخواست به پلتفرم یا از طریقAPI زیر دریافت نمایید. فقط دقت نمایید که توکنی که با آن ott می گیرید با توکنی که در درخواست بعدی باید استفاده شود، یکی باشد.

توجه داشته باشید مقدار ott از api_token متفاوت است، مقدار ott را میتوانید از response سرویس29816 هم دریافت نمایید و مجددا در سرویس صدور فاکتور فراخوانی نمایید.

اگر استفاده از ott در سیستم شما مقدور نیست، بجای متد بالا می توانید از سرویس 29797 استفاده نمایید که billNumberیکتا در آن اجباری می باشد و باید توسط کسب و کار ارسال شود و نیاز به ott ندارد.

* بندهای صدور فاکتور به صورت رنگ متفاوت در جدول پارامترها آمده اند ،

* توجه کنید که فاکتور حداقل باید یک بند فاکتور داشته باشد که شامل پارامترهای زیر می باشد .

productId[]   , price[]  , quantity[]  ,  productDescription[] , discount[]

بندهای فاکتور در این آرایه ها ارسال می شوند. بنابرین طول آرایه ها باید با هم برابر باشد و به ترتیببه صورت زیر می باشند :

- productId  : شناسه محصول

(برای کاهش تعداد موجودی - در صورتی که محصول قبلا در سیستم تعریف نشده است []productId برای آن بند مقدار 0 باید داشته باشد)

- price   :  قیمت محصول (می تواند با قیمت تعریف شده محصول متفاوت باشد)

- quantity : تعداد محصول

-  productDescription : شرح بند فاکتور

- discount : تخفیف برای بند فاکتور 

(به ازای هر بند می توانیدیک تخفیف نیز مشخص نمایید که ارسال آن اجباری نیست ولی در صورت ارسال براییک بند باید برای تمام بندها ارسال گردد.)

* بندهای فاکتور ، در خروجی سرویس و در فاکتور در فیلد invoiceItemSrvs  به صورت یک آرایه خواهند آمد.

* علامت [] در نام پارامتر به منظور ارسال مقادیر آن پارامتر  به صورت آرایه است ، و سرویس صدور فاکتور ،  با پارامتر های با نام تکراری که دارای این علامت باشند ، به شکل مقادیر یک آرایه برخورد میکند.

مثلا وجود دو فیلد price[] در یک درخواست ، به این معنی است که یک آرایه به نام price با دو مقدار ارسال شده است .

//parameters in request

price[]=value1

price[]=value2

// parameters in service

price=[value1,value2];

توضیحات

مقدار

نام پارامتر

ورودی

Header

توکن ثابت کسب وکار، که از پنل کسب وکار قابل دریافت است

yourBusinessToken

_token_

این پارامتر همواره دارای مقدار ثابت 1 است .

1

_token_issuer_

این پارامتر نوع داده ارسالی به سرور را مشخص میکند که همواره باید دارای مقدار ثابت application/x-www-form-urlencoded'  باشد

application/x-www-form-urlencoded

Content-Type

Body

شناسه سرویس:

 / عملیاتی / تستی procuction=29796 , sandbox=39291  

29796

scProductId

این مقدار را بعد از درخواست سرویس و تایید پادیوم ، میتوانید از پنل یا از طریق api دریافت نمایید.

کلید فراخوانی سرویس

scApiKey

سایر پارامترهای سرویس در Body

آدرس فراخوانی صادر کننده فاکتور- الزامی نیست

redirectURL

شناسه کاربر- شناسه مشتری که فاکتور برای او صادر می شود. برای بدست آورن این شناسه می توانید پروفایل کاربر را دریافت نمایید

userId

شماره قبض–شماره قبض دلخواه کسب و کار که بر اساس ساختار داخلی خودش آن را ثبت میکند و میتواند بعداً با استفاده از این مقدار فاکتور را به راحتی پیدا نماید.

مقدارbillNumber در آدرس برگشت، به کسب و کار بازگردانده می شود. شماره قبض رقم می باشد و نه عدد. به این معناکه مقدار 1 از 01 متفاوت است و می توان برای نام گذاری از این شیوه بهره مند شد.

billNumber

متادیتا برای فاکتور–هرگونه اطلاعات اضافی در مورد فاکتور که در قالب json ذخیره می گردد و قابل جستجو می باشد. به عنوان مثال اگر این مقدار را ارسال کنیم.

میتوانیم با استفاده از کوئری که در ادامه توضیح داده خواهد شد فاکتور را براساس این دیتا  جستجو کرد.

{"name":"Aria"}

metadata

شرح  فاکتور

description

yyyy/mm/dd تاریخ سررسید شمسی = مهلت پرداخت فاکتور، در صورتی که کاربر بخواهد پس از این زمان فاکتور را پرداخت نماید پیغام خطا دریافت می کند.

deadline

*شناسه محصول بند فاکتور، اگر شناسه محصول را نمی‌دانید مقدارصفر را ارسال نمایید

productId[]

*مبلغ بند فاکتور= قیمت محصول (می تواند با قیمت تعریف شده محصول متفاوت باشد)

price[]

*لیست تعداد محصول در هر بند فاکتور

quantity[]

*توضیحات هر بند از فاکتور

productDescription[]

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

discount[]

شناسه محصول بند دوم فاکتور، اگر شناسه محصول را نمی‌دانید مقدار صفر را ارسال نمایید

productId[]

*مبلغ بند فاکتور

price[]

*توضیحات هر بند از فاکتور

productDescription[]

* لیست تعداد محصول در هر بند فاکتور

quantity[]

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

discount[]

* کد صنف که فاکتور در آن صادر می شود. پس از پرداخت فاکتور، مبلغ آن به اعتبار صنفی که در اینجا اشاره شده، افزوده می شود.

guildCode

کد ارز پیش فرض IRR

currencyCode

شناسه یکی از آدرس های موجود کاربر

addressId

کد بن تخفیف برای فاکتور (امکان ایجاد بن تخفیف در پنل کسب و کار و یا با استفاده از  وب سرویس) وجود دارد ، که در اختیار مشتری قرار میگیرد تا در حین پرداخت فاکتور در درگاه ، با اعمال بن تخفیف ، مبلغ پرداختی در فاکتور را کاهش دهد.

voucherHash

میزان مالیات بین صفر تا یک که به صورت پیشفرض 0.09 است.درصورتی که خالی باشد 9 درصد محاسبه می شود.

preferredTaxRate

پرداخت دومرحله ای true/false = گر true داده شود، کسب و کار باید دریافت وجه را تایید نماید، در غیر این صورت پس از یک ساعت، پول پرداخت شده به کیف پول کاربر برمی گردد. (پرداخت سه مرحله ای)

verificationNeeded

تایید خودکار فاکتور در پرداخت دومرحله ای true/false

verifyAfterTimeout

)پیش نمایش فاکتور -در سیستم ثبت نمی گردد–در صورتی که true ارسال شود، یک پیش نمایش از فاکتور بازگردانده میشود و فاکتور ثبت نمی گردد.true/false  و با استفاده از سرویس پیش نمایش ، میتوان هش دسترسی به این فاکتور را بدست اورد و آنرا  در لینک مورد نظر قرار داد و به کاربر نمایش داد. توضیحات در سرویس نمایش پیش فاکتور 30359

preview

پرداخت فاکتور به روش امن–در صورتی که true ارسال شود، تاییدیا لغو پرداخت برعهده مشتری قرار می گیرد و اگر تا 2 روز اقدامی صورت نگیرد، فاکتور به صورت خودکار تایید می شود. / مقدار دیفالت این پارامتر، در صورت عدم ارسال false می باشد.

safe

امکان اضافه کردن ووچر بعد از صدر فاکتور–در صورتی که true باشد، مشتری قادر خواهد بود در صفحه فاکتور پاد، کد تخفیف وارد نماید.

postVoucherEnabled

عنوان رویداد - در صورتی که فاکتور رویداد داشته باشد مقدار true را ارسال نمایید.

hasEvent

منطقه زمانی رویداد

eventTimeZone

یادآورهای رویداد - فرمت json/ یادآورهای رویداد

eventReminders

توضیحات رویداد

eventDescription

اطلاعات جانبی رویداد

eventMetadata

شماره تلفن همراه - در صورت عدم وجود کاربر ثبت شده در پلتفرم، جهت نمایش شماره کارت های مربوط به مشتری این پارامتر می تواند بجایuserId ارسال گردد. در صورت وجود userId، این مقدار نادیده گرفته شده و شماره موبایل مربوط به userId به درگاه ارسال می گردد.

cellphoneNumber

در فاکتور غیر SAFE  (فاکتوری که تایید یا لغو آن بر عهده ی مشتری است ) پس از گذشت این زمان ، از زمان تایید فاکتور ، (فاکتور به صورت خودکار بسته می شود (به ثانیه و بالای 10 دقیقه) )

* باعث " بستن فاکتور "  ، فاکتور ی که  تایید شده ، بعد از گذشت این زمان  می شود.

closeTimeOut

   مهلت معلق بودن فاکتور است و پس از گذشت این زمان از صدور فاکتور، و تاییدنشدن فاکتور ، فاکتور به صورت خودکار کنسل خواهد شد (به ثانیه و بالای 6 دقیقه)

willCancelAfterTimeout

خروجی

در صورت وقوع خطا در فراخوانی سرویس true خواهد بود

true/false

hasError

جهت بررسی لاگ درخواست و ریسپانس توسط کارشناسان پادیوم ، استفاده میشود. توصیه می شود این پارامتر را برای هر درخواست ذخیره کنید.

string

referenceNumber

درصورت موفقیت آمیز بودن فراخوانی سرویس ، نتیجه در یک JSON در این فیلد قرارخواهد گرفت .

{}

result

مقادیر خروجی

شناسه فاکتور  -  در سایر سرویسها تحت عنوان invoiceId استفاده خواهد شد.

invoiceId

id

totalAmountWithoutDiscount

مقدار اعتبار اختصاصی و تخصیص داده شده

delegationAmount 

مبلغ تعیین شده برای محصول

totalAmount

مبلغ قابل پرداخت بعد از محاسبه مالیات و کدهای تخفیف و ...

payableAmount 

مالیات بر ارزش افزوده

vat

تاریخ ایجاد فاکتور

issuanceDate 

شناسه پرداخت

paymentBillNumber  

شناسه انحصاری فاکتور

uniqueNumber 

وضعیت پرداخت فاکتور

payed 

serial

وضعیت ابطال فاکتور

canceled 

وضعیت بسته بودن فاکتور

closed 

وضعیت پرداخت به روش امن فاکتور

safe 

وضعیت زیرمجموعه بودن فاکتور –

در فاکتور تسهیمی علاوه بر فاکتور اصلی ، چند فاکتور خرد  وجود دارد.

false

subInvoice

اگر فاکتور ویرایش شود ( کاهش داده شود ) این فیلد برابر true خواهد شد.

false

edited

وضعیت در انتظار تایید پرداخت بودن فاکتور  

false

waiting

شماره ارجاع  به فاکتور ، در فاکتورهای تسهیمی به تمام فاکتورهای زیر مجموعه اشاره خواهد داشت .

referenceNumber 

وضعیت فعال بودن  پرداخت دو مرحله ای

verificationNeeded  

اطلاعات کسب وکار صادر کننده فاکتور

{}

business

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

[]

invoiceItemSrvs

مشخصات حساب صنفی که مبلغ فاکتور بعد از پرداخت به آن واریز میشود .

guildSrv

وضعیت فعال بودن  اعمال بن تخفیف در پرداخت 

postVoucherEnabled 

false

willBeBlocked"

false

willBePaid

مراجعه شود به فیلدcloseTimeOut  در بدنه درخواست

unsafeCloseTimeOut 

shaparakTransactionDate

9951435100120006/inv-69751014/265

depositId

9951435100120006/inv-69751014/265

depositBillId

کاربر صادر کننده فاکتور

issuerSrv

کاربری که فاکتور برای اون ایجاد شده است .

userSrv

caller

نمونه درخواست

نمونه پاسخ

خطاهای معمول در پلتفرم

کد خطا

توضیح

10

INVALID_DATE - ارسال فرمت اشتباه تاریخ در پارامتر deadLine

19

DUPLICATE_CANCELED_BILLNUMBER - اگر شماره قبض لحاظ شده، متعلق به فاکتور کنسل شده ای با همین شماره قبض باشد، این خطا را دریافت خواهید نمود.

21

client not authenticated– بیزنس توکن  ( توکن کسب­­وکار  )  وارد نشده است

25

DUPLICATE_CANCELED_BILLNUMBER - اگر شماره قبض لحاظ شده، متعلق به فاکتور کنسل شده ای با همین شماره قبض باشد، این خطا را دریافت خواهید نمود.

37

INVALID_ELEMENT_CODE - کد صنف با فرمت صحیح موجود در پنل مدیریت کسب و کار، وارد نشده است.

39

PERMISSION_ACCESS_DENIED - در صورت عدم ارسال پارامتر ott با این خطا رو به رو می شوید. به منظور بازنشانی کردن ott ، سرویس دریافت توکن یکبار مصرف فراخوانی نمایید.

53

INVALID_BUSINESS_GUILD - اگر صنف انتخابی در پنل کسب و کار نباشد این خطا را دریافت خواهید نمود. ابتدا باید آن صنف را از پنل مدیریت کسب و کار، اضافه نمایید.

56

INVALID_GUILD_AMOUNT - پارامتر کد صنف به درستی ارسال نشده است.

66

INVOICE_SAME_BIZ_AND_CUSTOMER - اگر توکن(_token_) و شناسه ی کاربر(userId) ای که استفاده می نمایید متعلق به یک کسب و کار باشد، این خطا را دریافت می کنید. چرا که صدور فاکتور از کسب و کار خودتان برای خودتان امکان پذیر نیست.

به مستند افزودن کسب و کار واسط مراجعه نمایید. کسب و کار جدیدی ثبت نمایید، و به این کسب وکار مجوز صدور فاکتور براییک محصول خاص(ارجاع به مستند مجوز فروش محصول)، اعطا نمایید و سپس نسبت به صدور فاکتور اقدام نمایید

194

INVALID_REQUEST_PARAMETER - کد تخفیف وارد شده اشتباه می باشد.

227

تایم اوت سرویس اصلی

378

ارسال پاسخ از سرویس اصلی به پلتفرم با مشکل مواجه شده است

999

UNKNOWN- خطای داخلی

دریافت لیست آدرسهای مشتری

شناسه سرویس : 29819 ( سندباکس : 39314 )

توضیحات:

در صورتی که تمایل به ارسال آدرس مشتری دارید، از طریق سرویس زیر شناسه‌های آدرس‌های موجود برای کاربر را استخراج نمایید: (ارسال مقدار توکن دسترسی کاربر جاری)

توضیحات

مقدار

نام پارامتر

ورودی

Header

توکن ثابت کسب وکار، که از پنل کسب وکار قابل دریافت است

توکن  دسترسی کاربر Access-Token

yourBusinessToken

_token_

این پارامتر همواره دارای مقدار ثابت 1 است .

1

_token_issuer_

این پارامتر نوع داده ارسالی به سرور را مشخص میکند که همواره باید دارای مقدار ثابت application/x-www-form-urlencoded'  باشد

application/x-www-form-urlencoded

Content-Type

Body

شناسه سرویسشناسه سرویس : 29819 ( سندباکس : 39314 )

29819

scProductId

این مقدار را بعد از درخواست سرویس و تایید پادیوم ، میتوانید از پنل یا از طریق api دریافت نمایید.

کلید فراخوانی سرویس

scApiKey

 سایر پارامترهای سرویس در Body

// در صورت تمایل به دریافت کل لیست، این مقدار را صفر وارد نمایید

* الزامی

offset

تعداد آدرسها در خروجی

size

خروجی

در صورت وقوع خطا در فراخوانی سرویس true خواهد بود

true/false

hasError

جهت بررسی لاگ درخواست و ریسپانس توسط کارشناسان پادیوم ، استفاده میشود. توصیه می شود این پارامتر را برای هر درخواست ذخیره کنید.

string

referenceNumber

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

{}

result

مقادیر خروجی

نمونه درخواست

نمونه پاسخ

خطاهای معمول در پلتفرم

کد خطا

توضیح

21

توکن کسب­­وکاری وارد نشده است

227

تایم اوت سرویس اصلی

378

ارسال پاسخ از سرویس اصلی به پلتفرم با مشکل مواجه شده است

دریافت لیست فاکتورها با استفاده از متادیتا

شناسه سرویس :  29814  ( سندباکس 39309)

توضیحات:

جهت جستجو در متادیتای ثبت شده برای فاکتور، می‌توانید از سرویس زیر استفاده نمایید

در قسمت metaQuery مقادیر درخواستی خود را به فرم json با استفاده از توصیحات جستجوی متادیتا ارسال نمایید.

با توجه به فیلد metadate در سرویس صدور فاکتور ، یک کوئری به شکل زیر در پارامتر metaQuery ارسال خواهیم کرد.

* اگر فیلد metaQuery ارسال نشود، سرویس مانند سرویس 29813 عمل خواهدکرد.

توضیحات

مقدار

نام پارامتر

ورودی

Header

توکن ثابت کسب وکار، که از پنل کسب وکار قابل دریافت است

yourBusinessToken

_token_

این پارامتر همواره دارای مقدار ثابت 1 است .

1

_token_issuer_

این پارامتر نوع داده ارسالی به سرور را مشخص میکند که همواره باید دارای مقدار ثابت application/x-www-form-urlencoded'  باشد

application/x-www-form-urlencoded

Content-Type

Body

شناسه سرویس29814  ( سندباکس 39309)

29814

scProductId

این مقدار را بعد از درخواست سرویس و تایید پادیوم ، میتوانید از پنل یا از طریق api دریافت نمایید.

کلید فراخوانی سرویس

scApiKey

پارامترهای سرویس در Body

عبارت جستجو در متادیتا - اگر فیلدmetaQuery ارسال نشود، سرویس مانند سرویس 29813 عمل خواهدکرد.

{

"field":"name",

"is": "Aria"

}

metaQuery

اندازه خروجی

size

شروع نمایش خروجی

offset

وضعیت بسته بودن فاکتو

true/false

isClosed

وضعیت پرداختی فاکتور

true/false

isPayed

وضعیتلغو  فاکتور

true/false

isCanceled

true/false

isEdited

true/false

isCustomerInvoice

وضعیت پرداختی فاکتور

وضعیت بسته بودن فاکتو

true/false

hasError

وضعیت در انتظار پرداخت بودن فاکتور

string

referenceNumber

درصورت موفقیت آمیز بودن عملیات ، شامل لیستی از اطلاعات فاکتور ها را مانند سرویس 29813   خواهد بود.

[{},{}]

result

مقادیر خروجی

نمونه درخواست

نمونه پاسخ

خطاهای معمول در پلتفرم

کد خطا

توضیح

21

توکن کسب­­وکاری وارد نشده است

227

تایم اوت سرویس اصلی

378

ارسال پاسخ از سرویس اصلی به پلتفرم با مشکل مواجه شده است

درخواست ایجاد فایل لیست فاکتورها

شناسه سرویس :  29817 ( سندباکس : 39312) 

توضیحات:

امکان جستجو و دریافت فایل فاکتورهای صادر شده توسط کسب و کار قابل انجام خواهد بود و میتوانیدیک فایل اکسل با فیلترهای متنوع دریافت کنید.

* توجه داشته باشید :

1 - که ابتدا باید توسط این سرویس درخواست ایجاد فایل ارسال شود

2-  سپس ، در سرویس 29818 ، کد هش و شناسه فایل تولید شده را دریافت نمایید.

3-  سپس جهت دانلود فایل ، کد هش و شناسه فایل را در لینک دانلود فایل (لینک زیر ) ، قرار دهید و ، فایل یرا دانلود نمایید.

https://core.pod.ir/nzh/file/

?fileId=9857

&hashCode=17bab0efc24-0.6833405721775528

* بدیهی است در سرویس بالا با توجه به اختیاری بودن اکثر فیلدها اگر هیچیک از پارامترهای اختیاری ارسال نشود گزارش حجیم تر و کاملتری در اکسل خواهید داشت و هرچه تعداد فیلترها بیشتر باشد گزارش دقیق تر و سبک تری در اختیار خواهید داشت.

* توجه: در بین پارامترهای ارسالییکی از پارامترهایlastNRows و یا بازه زمانی اجباری است.)

* در بخش پاسخ همانطور که مشاهده میکنید در صورت موفقیت آمیز بودن سرویسیک شناسه (ID) برای فایل ایجاد شده صادر خواهد شد

 و statusCode برابر با مقدار EXPORT_SERVICE_STATUS_CREATED قرار خواهد گرفت

در این مرحله باید حدود 1 تا 2 دقیقه منتظر بمانید تا statusCode به EXPORT_SERVICE_STATUS_SUCCESSFUL تغییر وضعیت بدهد.

*کدهای وضعیتی که ممکن است در حین کار با این سرویس مشاهده کنید به شرح زیر میباشد.

سرویس در حال ایجاد فایل میباشدEXPORT_SERVICE_STATUS_CREATED

فایل در حال آماده سازی میباشدEXPORT_SERVICE_STATUS_RUNNING

فایل با موفقیت ایجاد شدEXPORT_SERVICE_STATUS_SUCCESSFUL

خطایی در ایجاد فایل اتفاق افتاده استEXPORT_SERVICE_STATUS_FAILED

توضیحات

مقدار

نام پارامتر

ورودی

Header

توکن ثابت کسب وکار، که از پنل کسب وکار قابل دریافت است

yourBusinessToken

_token_

این پارامتر همواره دارای مقدار ثابت 1 است .

1

_token_issuer_

این پارامتر نوع داده ارسالی به سرور را مشخص میکند که همواره باید دارای مقدار ثابت application/x-www-form-urlencoded'  باشد

application/x-www-form-urlencoded

Content-Type

دریافتی از سرویس  29816 یا سرویس فراخوانی شده ی قبلی توسط کسب وکار

_ott_

Body

شناسه سرویس:  29817 ( سندباکس : 39312)

29817

scProductId

این مقدار را بعد از درخواست سرویس و تایید پادیوم ، میتوانید از پنل یا از طریق api دریافت نمایید.

کلید فراخوانی سرویس

scApiKey

پارامترهای سرویس در Body

شروع تاریخ صدور فاکتور  *

1400/05/11 00:00:00:000

fromDate

پایان تاریخ صدور فاکتور *

1400/06/12 13:50:00:000

toDate

شروع نمایش از لیست تولیدی

0

offset

تعداد

10

size

* کدصنف

*

guildCode

شناسهفاکتور

id

شمارهقبضکهبهتنهاییباآنمیتوانجستجونمود

billNumber

شمارهکدشدهیقبضکهبهتنهاییباآنمیتوانجستجونمود

uniqueNumber

وضعیتلغو  فاکتور

true / false

isCanceled

وضعیت پرداختی فاکتور

true / false

isPayed

وضعیت بسته بودن فاکتو

true / false

isClosed

وضعیت در انتظار تایید پرداخت بودن فاکتور

true / false

isWaiting

شمارهارجاع

referenceNumber

شناسهکاربریمشتری

userId

[ productIdList ]      لیست آرایه ای از شماره محصولات

productIdList

عبارتجهتجستجو درتوضیحاتفاکتور

query

تعداد ردیف های مورد نظر در خروجی فایل

*

lastNRows

آدرسفراخوانیپسازاتمامتولیدگزارش

callbackUrl

خروجی

در صورت وقوع خطا در فراخوانی سرویس true خواهد بود

true/false

hasError

جهت بررسی لاگ درخواست و ریسپانس توسط کارشناسان پادیوم ، استفاده میشود. توصیه می شود این پارامتر را برای هر درخواست ذخیره کنید.

string

referenceNumber

نتیجه خروجی سرویس که به صورت یک json خواهد بود.

{}

result

مقادیر خروجی  result

شناسه درخواست ایجاد فایل

id

کدهای وضعیتی که ممکن است در حین کار با این سرویس مشاهده کنید به شرح زیر میباشد.

سرویس در حال ایجاد فایل میباشد

EXPORT_SERVICE_STATUS_CREATED

فایل در حال آماده سازی میباشد

EXPORT_SERVICE_STATUS_RUNNING

فایل با موفقیت ایجاد شد

EXPORT_SERVICE_STATUS_SUCCESSFUL

خطایی در ایجاد فایل اتفاق افتاده است

EXPORT_SERVICE_STATUS_FAILED

statusCode

تاریخ ایجاد

creationDate

نمونه درخواست

نمونه پاسخ

خطاهای معمول در پلتفرم

کد خطا

توضیح

21

توکن کسب­­وکاری وارد نشده است

227

تایم اوت سرویس اصلی

378

ارسال پاسخ از سرویس اصلی به پلتفرم با مشکل مواجه شده است

تایید پرداخت فاکتور

شناسه سرویس :29809  ( سندباکس : 39304)

توضیحات :

در صورتی که در صدور فاکتور پارامتر verificationNeeded را با مقدار true ارسال نموده باشید، پرداخت سه مرحله ای فعال شده است. به این معنی که پس از هدایت کاربر به صفحه پرداخت(فقط در صورت پرداخت فاکتور از طریق اتصال به درگاه می توانید سرویس تایید فاکتور را صدا بزنید) و دریافت پاسخ در redirectUri لازم است پرداخت توسط کسب و کار با استفاده از API زیر تایید شود:

* در صورتی که فاکتور مورد نظر تسهیمی است، شناسه ای که باید به این سرویس ارسال گردد، معادل result -> id موجود در خروجی فاکتور تسهیمی می باشد.

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

* (از بین شناسه فاکتور و شناسه قبض ارسال یک مورد اجباری است)

* اگر عملیات تایید با موفقیت انجام شود ، فیلد payed در خروجی و همینطور در فاکتور به مقدار true در خواهد آمد.

توضیحات

مقدار

نام پارامتر

ورودی

Header

توکن ثابت کسب وکار، که از پنل کسب وکار قابل دریافت است

yourBusinessToken

_token_

این پارامتر همواره دارای مقدار ثابت 1 است .

1

_token_issuer_

این پارامتر نوع داده ارسالی به سرور را مشخص میکند که همواره باید دارای مقدار ثابت application/x-www-form-urlencoded'  باشد

application/x-www-form-urlencoded

Content-Type

Body

شناسه سرویس 29809   ( سندباکس : 39304)

29809  

scProductId

این مقدار را بعد از درخواست سرویس و تایید پادیوم ، میتوانید از پنل یا از طریق api دریافت نمایید.

کلید فراخوانی سرویس

scApiKey

سایر پارامترهای سرویس در Body

شناسهفاکتور * (از بین شناسه فاکتور و شناسه قبض ارسال یک مورد اجباری است)

id

شناسه قبض* (از بین شناسه فاکتور و شناسه قبض ارسال یک مورد اجباری است)

billNumber

خروجی

در صورت وقوع خطا در فراخوانی سرویس true خواهد بود

true/false

hasError

جهت بررسی لاگ درخواست و ریسپانس توسط کارشناسان پادیوم ، استفاده میشود. توصیه می شود این پارامتر را برای هر درخواست ذخیره کنید.

string

referenceNumber

.پاسخ نهایی سرویس

result

مقادیر خروجی

                                                                         invoiceId

id

totalAmountWithoutDiscount

delegationAmount

payableAmount

مالیات بر ارزش افزوده

vat

totalAmount

payableAmount

1536151382204

issuanceDate

deliveryDate

1397/06/14

issuancePersianDate

uniqueNumber

1536151698170

paymentDate

payed

serial

false

canceled

Your Business ID

business.id

invoiceItemSrvs

invoiceItemSrvs.id

ID of user who payed

userSrv.id

Name Of Card Owner

userSrv.name

closed

// if verification is successful, this will be true

true

verificationNeeded

PODLAND_WALLET

wallet

false

safe

false

postVoucherEnabled

false

edited

false

waiting

false

subInvoice

transactionReferenceId

نمونه درخواست

نمونه پاسخ

خطاهای معمول در پلتفرم

کد خطا

توضیح

21

توکن کسب­­وکاری وارد نشده است

55

BILL_NOT_PAYED  -  صورتحساب پرداخت نشده است.

59

BILL_IS_NOT_WAITING_FOR_VERIFICATION -  فقط در صورتی که فاکتور با سرویس پرداخت از طریق کیف پول پرداخت شده باشد، اتصال به درگاه اقساطی، در دسته منتظر برای تایید قرار می گیرد.

72

BILL_IS_WAITING_FOR_GATEWAY - صورتحساب منتظر هدایت به درگاه است.

227

تایم اوت سرویس دهنده

378

ارسال پاسخ از سرویس  به پلتفرم با مشکل مواجه شده است

999

UNKHOWN– خطای داخلی

بستن فاکتور

شناسه سرویس : 29812 ( سندباکس : 39307 )

توضیحات :

برای اینکه بتوانید مبالغ فروش خود را تسویه نمایید ( و از حساب دیجیتال خود خارج کنید ) لازم است حتما فاکتورها را ببندید.

با این عمل فیلدclosed در مشخصات فاکتور true  خواهد شد

فاکتور هایی که بسته شوند دیگر قابل ابطال نیستند.

* در صورتی که فاکتور مورد نظر تسهیمی است، شناسه ای که باید به این سرویس ارسال گردد، معادل result -> id موجود در خروجی فاکتور تسهیمی می باشد. تا زمانی که فاکتور بسته نشود هیچکدام از ذینفعان قادر به تسویه و برداشت سهم خود نیستند.

* چنان چه فاکتور به صورت safe=true صادر شده باشد ( مراجعه شود به سرویس صدور فاکتور فیلد safe )

و یا فاکتور متعلق به کسب و کار شما نباشد پیغام خطای " اجازه بستن این فاکتور را ندارید " دریافت خواهید کرد.

* هنگام استفاده از این وب سرویس به نکات زیر دقت نمایید:

مبلغ فاکتور بعد از واریز شاپرک قابل برداشت خواهد بود.

بعد از فراخوانی این سرویس امکان کاهش فاکتور یا لغو فاکتور وجود ندارد.

جهتعودت  وجه به مشتری پرداخت کننده فاکتور، لازم است از سرویس"انتقال وجه به مشتریان براساس فاکتور 34988 " - transferByInvoice استفاده نمایید که شامل کارمزد می باشد.(این سرویس در مجموعه سرویس حساب دیجیتال قرار دارد)

بعد از فراخوانی این سرویس وضعیت فاکتور دیگر تغییر نخواهد کرد

توضیحات

مقدار

نام پارامتر

ورودی

Header

توکن ثابت کسب وکار، که از پنل کسب وکار قابل دریافت است

yourBusinessToken

_token_

این پارامتر همواره دارای مقدار ثابت 1 است .

1

_token_issuer_

این پارامتر نوع داده ارسالی به سرور را مشخص میکند که همواره باید دارای مقدار ثابت application/x-www-form-urlencoded'  باشد

application/x-www-form-urlencoded

Content-Type

Body

شناسه سرویس29812 ( سندباکس : 39307 )

29812

scProductId

این مقدار را بعد از درخواست سرویس و تایید پادیوم ، میتوانید از پنل یا از طریق api دریافت نمایید.

کلید فراخوانی سرویس

scApiKey

سایر پارامترهای سرویس در Body

شناسه فاکتور invoiceId

id

خروجی

در صورت وقوع خطا در فراخوانی سرویس true خواهد بود

true/false

hasError

جهت بررسی لاگ درخواست و ریسپانس توسط کارشناسان پادیوم ، استفاده میشود. توصیه می شود این پارامتر را برای هر درخواست ذخیره کنید.

string

referenceNumber

.پاسخ نهایی سرویس  : نتیجه سرویس بستن فاکتور

true

result

نمونه درخواست

نمونه پاسخ

خطاهای معمول در پلتفرم

کد خطا

توضیح

21

توکن کسب­­وکاری وارد نشده است

4

PERMISSION_DENIED -  اجازه بستن این فاکتور را ندارید

45

BILL_ALREADY_CLOSED - فاکتور بسته شده است.

55

BILL_NOT_PAYED - اگر فاکتوری که پرداخت نشده است را بخواهید ببندید این خطا را دریافت می کنید.

58

BILL_IS_WAITING_FOR_VERIFICATION  -  فاکتور تا قبل از تایید شدن قابل بستن نمی باشد.

227

تایم اوت سرویس اصلی

378

ارسال پاسخ از سرویس اصلی به پلتفرم با مشکل مواجه شده است

999

UNKHOWN - خطای داخلی

تایید و بستن فاکتور در یک مرحله

شناسه سرویس :29808 ( سندباکس :  39303 )

توضیحات :

با فراخوانیسرویس زیر، می‌توانید همزمان تایید و بستن فاکتور را انجام دهید و فیلدهای payed  و closed در مشخصات فاکتور ، دارای مقدار true  خواهند بود.

* هنگام استفاده از این وب سرویس به نکات زیر دقت نمایید:

مبلغ فاکتور بعد از واریز شاپرک قابل برداشت خواهد بود.

بعد از فراخوانی این سرویس امکان کاهش فاکتور یا لغو فاکتور وجود ندارد.

جهت عودت  وجه به مشتری پرداخت کننده فاکتور، لازم است از سرویس "انتقال وجه به مشتریان براساس فاکتور 34988 " - transferByInvoice استفاده نمایید که شامل کارمزد می باشد.(این سرویس در مجموعه سرویس حساب دیجیتال قرار دارد)

بعد از فراخوانی این سرویس وضعیت فاکتور دیگر تغییر نخواهد کرد

توضیحات

مقدار

نام پارامتر

ورودی

Header

توکن ثابت کسب وکار، که از پنل کسب وکار قابل دریافت است

yourBusinessToken

_token_

این پارامتر همواره دارای مقدار ثابت 1 است .

1

_token_issuer_

این پارامتر نوع داده ارسالی به سرور را مشخص میکند که همواره باید دارای مقدار ثابت application/x-www-form-urlencoded'  باشد

application/x-www-form-urlencoded

Content-Type

Body

شناسه سرویس: 29808 ( سندباکس :  39303 )

29808

scProductId

این مقدار را بعد از درخواست سرویس و تایید پادیوم ، میتوانید از پنل یا از طریق api دریافت نمایید.

کلید فراخوانی سرویس

scApiKey

سایر پارامترهای سرویس در Body

شناسه فاکتور

id

خروجی

در صورت وقوع خطا در فراخوانی سرویس true خواهد بود

true/false

hasError

جهت بررسی لاگ درخواست و ریسپانس توسط کارشناسان پادیوم ، استفاده میشود. توصیه می شود این پارامتر را برای هر درخواست ذخیره کنید.

string

referenceNumber

.پاسخ نهایی سرویس که شامل اطلاعات فاکتور خواهد بود.

result

مقادیر خروجی

نمونه درخواست

نمونه پاسخ

خطاهای معمول در پلتفرم

کد خطا

توضیح

21

توکن کسب­­وکاری وارد نشده است

227

تایم اوت سرویس اصلی

378

ارسال پاسخ از سرویس اصلی به پلتفرم با مشکل مواجه شده است

کاهش فاکتور

شناسه سرویس :29803  ( سندباکس:39298)

توضیحات :

* در مواردی ممکن است نیاز به تغییری در بندهای فاکتور داشته باشید.

*  در صورتی که فاکتور پرداخت نشده است، فاکتور قبلی را باطل (cancel) نمایید و فاکتور جدیدی صادر کنید.

*  اگر فاکتور پرداخت شده است(در صورتی که باید پول بیشتری از مشتری دریافت نمایید)، لازم است فاکتوری جداگانه به مبلغ افزوده شده، با ذکر دلیل صادر نموده و مشتری را مجددا برای پرداخت هدایت نمایید.

* در برخی مواقع لازم است مبلغی از فاکتور پرداخت شده به مشتری بازگردانده شود. برای این منظور از سرویس کاهش فاکتور برای اصلاح فاکتور پرداخت شده استفاده نمایید

* توجه: تعداد پارامترهای []invoiceItemId و []productId و []price و []quantity و []itemDescription  باید با هم برابر و برابر با تعداد آنها در فاکتور اول باشد.

* در این سرویس ، موارد زیر اجرا می شوند:

- فاکتور اول باطل شده و یک فاکتور جدید با همان خصوصیات قبلی و با اصلاحات بالا صادر شده و billNumber فاکتور اول Null می شود.

- فیلدedited در فاکتور اول true می شود.

- در فاکتور جدید مقدار editedInvoiceId برابر با id فاکتور اول قرار می گیرد.

- در لیست فاکتورها فقط فاکتورهای ویرایش نشده نمایش داده می شوند مگر اینکه دقیقاًid فاکتور ویرایش شده مورد نظر ارسال شود.

- فاکتور ویرایش شده قابل بستن یا باطل شدن نیست و لازم است فاکتور نهایی بسته یا باطل شود.

- اگر فاکتور اول با مقدار مالیات پیشفرض سیستم ثبت شده باشد و در اصلاح فاکتور نیز داده نشود، در صورتی که مالیات پیشفرض سیستم عوض شده باشد، فاکتور دوم نیز با مالیات پیشفرض جدید ثبت خواهد شد.

- در صورت استرداد محصول ،available count محصول (موجوی محصول ) بعد از استرداد ، مجددا اضافه شده و تعداد فروش محصول کاهش خواهد یافت.

- در صورت استرداد محصول توسط مشتری، چنان‌چه کسب و کار بخواهد مبلغی رو به عنوان جریمه از مشتری دریافت نماید، بایستی شناسه محصولی که از قبل به عنوان جریمه در کسب و کار تعریف شده است را به جای شناسه محصول مسترد شده در سرویس فوق ارسال نماید.

- برای دیدن فاکتور قبلی باید از شناسه ی آن فاکتور در سرویس لیست فاکتور استفاده کرد. در غیر این صورت . آن فاکتور دیگر نمایش داده نمیشود( در فاکتور قبلی فیلدedited=true می باشد )

توضیحات

مقدار

نام پارامتر

ورودی

Header

توکن ثابت کسب وکار، که از پنل کسب وکار قابل دریافت است

yourBusinessToken

_token_

این پارامتر همواره دارای مقدار ثابت 1 است .

1

_token_issuer_

این پارامتر نوع داده ارسالی به سرور را مشخص میکند که همواره باید دارای مقدار ثابت application/x-www-form-urlencoded'  باشد

application/x-www-form-urlencoded

Content-Type

Body

شناسه سرویس29803  ( سندباکس: 39298)

scProductId

این مقدار را بعد از درخواست سرویس و تایید پادیوم ، میتوانید از پنل یا از طریق api دریافت نمایید.

کلید فراخوانی سرویس

scApiKey

سایر پارامترهای سرویس در Body

* شناسهفاکتور

*

id

شناسهبندفاکتور (به خروجی سرویس صدور فاکتور مراجعه کنید)

invoiceItemSrvs.id

invoiceItemId[]

شناسه  محصول در بند فاکتور (به خروجی سرویس صدور فاکتور مراجعه کنید)

productId[]

* مبلغ در بندفاکتور - باید کوچکتر مساوی مقدار قبلی باشد(به خروجی سرویس صدور فاکتور مراجعه کنید)

new Price

price[]

* تعدادمحصولدربندفاکتور - باید کوچکتر مساوی مقدار قبلی باشد(به خروجی سرویس صدور فاکتور مراجعه کنید)

new quantity

quantity[]

* توضیح بند فاکتور(به خروجی سرویس صدور فاکتور مراجعه کنید)

new description

itemDescription[]

نرخمالیاتبرایاینخریدکهبرایتمامآیتمهایفاکتوراعمالمیشود. اگرمقداریارسالنشودمقدارمالیاتبرارزشافزودهپیشفرضمحاسبهمیشود

Default value : 0.09

باید کوچکتر مساوی مقدار قبلی باشد

new taxRate

preferredTaxRate

متادیتا برای فاکتور

metadata

لیست کد بن تخفیف

voucherHash

خروجی

در صورت وقوع خطا در فراخوانی سرویس true خواهد بود

true/false

hasError

جهت بررسی لاگ درخواست و ریسپانس توسط کارشناسان پادیوم ، استفاده میشود. توصیه می شود این پارامتر را برای هر درخواست ذخیره کنید.

string

referenceNumber

.پاسخ نهایی سرویس  که شامل اطلاعات فاکتور تغییر یافته و جدید است

result

مقادیر خروجی

نمونه درخواست

نمونه پاسخ

خطاهای معمول در پلتفرم

کد خطا

توضیح

21

توکن کسب­­وکاری وارد نشده است

227

تایم اوت سرویس اصلی

378

ارسال پاسخ از سرویس اصلی به پلتفرم با مشکل مواجه شده است