پرداخت کسب‌وکارهای واسط

مقدمه

با گسترش کسب وکارهایی که دارای ماهیت پلتفرمی هستند و نقش واسط بین کاربران و ارائه دهندگان خدمات را ایفا میکنند چالش دریافت پول و تسهیم آن میان ذینفعان پر رنگ تر شده است. دلیل این امر این است که با وجود اینکه سامانه ها یا واسطهای ارائه دهنده خدمات، کل مبلغ پرداختی را از کاربر دریافت می کنند اما عمدتا بخش کوچکی از این مبالغ متعلق به آنها است. دریافت این موجودی علاوه برتحمیل چالشهای مالیاتی، بار عملیاتی زیادی جهت انتقال سهم هریک از ذینفعان را نیز در پی خواهد داشت.

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

نکات:

• سرویسهای به کار رفته در این مستند، تنها به عنوان نمونه معرفی شده اند.
• امکان استفاده از سایر سرویسهای مشابه در هر مرحله وجود دارد.
• امکان کاهش و افزایش و ابطال فاکتور، به منظور ساده سازی در این مستند آورده نشده است.
• امکان تسویه خودکار حساب صنفی، به منظور ساده سازی در این مستند آورده نشده است.

فعالسازی سرویس

ارسال درخواست در سایت پادیوم www.podium.ir:

ابتدا وارد سایت پادیوم شده، سپس در بازارچه‌ی API، سرویسهای مورد نظر خود را انتخاب و درخواست استفاده از آن مجموعه سرویس را ارسال کنید.

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

منو: پنل کسب و کار – منوی میزکار سرویس گیرنده – درخواستهای ارسالی – در بخش مربوط به سرویس مورد نظر با کلیک بر روی "جزئیات درخواست"

درلیست باز شده با کلیک بر روی تصویر کلید سمت چپ هر سطر جدول می‌توانید ApiKey مربوط به آن سرویس را دریافت و ذخیره کنید.

لینک پنل کسب و کار                                                                                                                                                                                     https://panel.pod.ir/Businesses/Requestwebservices

نکته : این کلید در تمام درخواست‌های ارسالی از آن سرویس ، ثابت است تا زمانی که کلید جدیدی برای آن سرویس دریافت نشود و به محض دریافت مقدار جدید برای سرویس مورد نظر, کلید قبلی منقضی خواهد شد.

-این کلید در فیلد scApiKey در بخش body درخواست HTTP ، استفاده می شود.

دریافت کلیدهای سرویس یک (دسته/مجموعه) سرویس در قالب یک فایل:

بعداز فشردن دکمه ی تایید سرویس در پنجره باز شده بالا ، برای تمامی سرویسهای موجود در پنل می‌توانید از گزینه "دریافت فایل خروجی"، لیست کاملی از سرویس‌ها و کلیدهای scApiKey متناظر با هر یک را دریافت کنید.

مرحله 1: درگاه پرداخت

درخواست فعالسازی درگاه پرداخت و دریافت آن ارائه شود. برای این منظور توضیحات مربوطه را در صفحه پرداخت مطالعه فرمایید.

مرحله 2: افتتاح حساب دیجیتال پاسارگاد

لازم است کسب و کارهای ذینفع نیز حساب دیجتال پاسارگاد افتتاح نمایند.

سرویس زیر عملیات مهم زیر را در یک عملیات انجام می‌دهد:

• با استفاده از نام کاربری و ایمیل و شماره موبایل که دریافت می کند، امکان ورود به پنل مدیریت کسب و کار برای کسب و کار دیگر فراهم می‌شود
• اطلاعات کسب و کار در پلتفرم (اصلی یا سندباکس) ثبت می‌شود
• یک اپلیکیشن (client) پیشفرض برای کسب و کار به صورت یکپارچه ایجاد می‌شود که برای هر دو سرور سندباکس و اصلی اعتبار دارد
• بنابراین در صورتی که سرویس زیر را برای مثال در سندباکس فراخوانی نمودید، برای انتقال به سرور اصلی کافیست با همان توکنی که برای کسب و کار از سرور سندباکس دریافت نموده‌اید، اطلاعات پروفایل کاربر را در سرور اصلی دریافت نموده و یک کسب و کار برای آن کاربر ثبت نمایید.
• لازم به ذکر است، شماره شبای این کسب و کارها مبتنی بر کد ملی صاحب کسب و کار ساخته می‌شود. در صورتی که owner کسب و کار تغییر یابد، شماره شباهای ساخته شده با کد ملی قبلی غیر فعال شده و از حساب‌های کسب و کار جدا می‌گردد تا owner جدید با کد ملی خود، شبای جدید دریافت نماید.
• همچنین در این سرویس می توان از کد به جای اسامی کشور، استان و شهر استفاده نمود (که در ادامه سرویس های مربوط به اخذ کد را معرفی خواهیم کرد.)

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

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

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

نمونه پاسخ

سرویس افزودن کسب و کار واسط

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

(سندباکس: 39323)

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

به این معنی که کسب وکار واسط میتواند، فاکتورهایی را با نام و مشخصات کسب وکار سود برنده صادر نماید،

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

پارامترهای خروجی

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

نمونه پاسخ

 businesspanel.pod.ir «کارگزاری » کارگزارهای من» افزودن کارگزار

مرحله 4: صدور فاکتور تسهیمی

کسب و کار معامله گر که لازم است فاکتور تسهیمی صادر نماید باید از جانب کسب و کارهای سهیم دارای مجوز صدور فاکتور باشد. همچنین در این سرویس امکان برای یک کسب وکار با ایجاد فاکتور تسهیمی برای چند صنف مختلف با توجه به رشته json، در نظر گرفته شده است. سپس می تواند با استفاده از سرویس زیر تسهیم فروش انجام دهد:

سرویس صدور فاکتور تسهیمی

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

یک فاکتور تسهیمی شامل  3 بخش اصلی می باشد.

 mainInvoice

subInvoices

customerInvoiceItemVOs

* mainInvoice:

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

* subInvoices:

فاکتور و سهم سایر  ذینفعان از فروش ،  در این بخش قرار میگیرد، که به صورت یک آرایه از چند Object فاکتور  ، وارد میشود. که دراین قسمت شناسه کسب وکار ،ذینفع و سود برنده از این فروش ، به همراه محل واریز ( حساب تفصیلی آن کسب وکار ) و همینطور میزان سهمی که از فروش می برد ، آورده میشود . 

*  customerInvoiceItemVOs:

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

ساختار فاکتور تسهیمی

توجه داشته باشید که در مقادیر بالا معادله زیر باید برقرار باشد:

سهم فروشنده + (سهم سایر سودبرندگان ) = مبلغ پرداختی توسط کاربر در فاکتور

* دقت شود که پارامتر billNumber باید برای کسب وکار یونیک باشد.

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

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

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

برای پرداخت فاکتور می توانید مقدار result -> customerInvoice -> id را با انواع روش های پرداخت ارسال نمایید.

یا از مقدار result -> customerInvoice-> uniqueNumber برای پرداخت پیشرفته استفاده نمایید.

برای تایید فاکتور یا لغو فاکتور یا بستن فاکتور، مقدار result -> customerInvoice -> id را بفرستید.

با توجه به اینکه در فاکتور تسهیمی، آدرس کاربر در خروجی subinvoiceها قابل مشاهده نمی‌باشد، جهت دسترسی هر کسب و کار به آدرس کاربر، امکان ارسال addressId برای subInvoiceها نیز  فراهم گردیده است.

در صورتی که addressId در subInvoice ارسال گردد، آدرس کاربر در خروجی subInvoice فاکتور قابل مشاهده خواهد بود.

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

پارامترهای خروجی:

نمونه data

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

نمونه پاسخ

مرحله 5: تولید لینک پرداخت

از آدرس زیر استفاده شود. به جای returnuri.ir آدرس بازگشتی ثبت شده هنگام فعالسازی درگاه پرداخت جایگزین شود.

نمونه لینک پرداخت

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

مرحله 6: کنترل پرداخت

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

نمونه فراخوانی آدرس بازگشتی

کسب و کار واسط باید مقادیر ارسال شده به آدرس بازگشتی را کنترل نماید تا متوجه پرداخت فاکتور شود

مرحله 7: بستن فاکتور

سرویس بستن فاکتور

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

(سندباکس: 39307)

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

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

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

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

* چنانچه فاکتور به صورت safe=true صادر شده باشد ( مراجعه شود به سرویس صدور فاکتور فیلد safe ) و یا فاکتور متعلق به کسب و کار شما نباشد پیغام خطای " اجازه بستن این فاکتور را ندارید " دریافت خواهید کرد.

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

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

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

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

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

ورودی

خروجی

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

نمونه پاسخ

مرحله 8: تسویه شاپرکی

تسویه شاپرکی توسط سامانه شاپرک در ساعت 9 صبح برای فاکتورهای بسته شده تا ساعت 22 شب قبل انجام شده و این فاکتورها قابل تسویه می شوند. البته ممکن است به دلیل طولانی شدن عملیات مغایرت گیری شاپرکی، تسویه شاپرکی بیشتر از این بازه طول بکشد.

مرحله 9: مبلغ قابل تسویه

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

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

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

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

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

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

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

* withdrawableAmount   : نمایش مبلغ قابل برداشت 

* notWithdrawableAmount : نمایش میزان مبلغ غیر قابل برداشت .

* amount  : نمایش تمام مبلغ موجود در حساب .

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

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

نمونه پاسخ

مرحله 10: ثبت حساب برای تسویه

برای انجام تسویه ، باید شماره شبای مقصد مورد نظر  را پیش از تسویه ، در سیستم اضافه نمایید. این کار برای هر حساب فقط یک بار انجام می شود و برای تسویه های بعدی به مقصد این حساب، نیازی به ثبت دوباره آن نیست.

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

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

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

نمونه پاسخ

businesspanel.pod.ir » حسابهای تفصیلی » کارتها و شباها » شماره های شبا » شماره شبای جدید

مرحله 11: درخواست تسویه حساب

سرویس تسویه و برداشت از حساب تفصیلی کسب و کار

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

 (سندباکس: 158268)

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

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

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

نمونه پاسخ

نکته: به جای درخواست تسویه حساب تفصیلی به صورت موردی، می توان از تسویه خودکار استفاده کرد تا در هر 24 ساعت یک بار به صورت خودکار تسویه حساب انجام شود.

مرحله 12: تسویه حساب کسب و کار ذی نفع

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

مبلغ قابل تسویه

دریافت مبلغ قابل تسویه ذی نفع توسط سرویس 39634

ثبت حساب

ثبت حساب برای تسویه ذی نفع توسط سرویس 46871

businesspanel.pod.ir » حسابهای تفصیلی » کارتها و شباها » شماره های شبا » شماره شبای جدید

تسویه حساب

تسویه حساب ذینفع توسط سرویس 2467366

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