معرفی

از نسخه‌ فعلی زرین‌پال، یک رابط برنامه‌نویسی (API) برای ارائه‌ی خدمات به مشتریان تحت پروتکل oAuth 2.0 و زبان پرس‌و‌جوی GraphQL (opens new window) معرفی و در دسترس قرار داده شده است.

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

اولین شرط استفاده از امکاناتAPI، دریافت یک Access Token است که پس از طی‌کردن مراحل احراز هویت به دست می‌آید.

بعد از دریافت Access Token خریدار، می‌توانید با اضافه‌کردن توکن به هدر Authorization در درخواست‌های خود، پرس‌و‌جوها را اجرا کرده و نتیجه را دریافت کنید.

پرس‌و‌جو با GraphQL

به جز مراحل احراز هویت، بقیه‌ی امکانات API از طریق کارگزاری در‌دسترس هستند که با زبان پرس‌و‌جوی GraphQL کار می‌کند.

برخی از تفاوت‌های GraphQL و REST عبارت است از:

• GraphQL تنها یک آدرس Endpoint دارد و برای دسترسی به امکانات مختلف، نیازی به عوض‌کردن Endpoint نیست.
• تمامی درخواست‌ها با پروتکل HTTP، با نوع POST و نوع محتوای application/json ارسال می‌شوند.
• در قسمت درخواست‌ها می‌توانید همه اطلاعات را دریافت نکرده و تنها فیلدها و اطلاعات مورد نیاز خود را دریافت کنید.
• در قالب یک درخواست، می‌توانید چندین پرس‌و‌جو ارسال کنید که در کاهش زمان Round-trip مؤثر است.
• سرورهای GraphQL یک فایل Schema به شما ارائه می‌دهد که تمام پرس‌و‌جوهای در دسترس و ساختار پاسخ‌های آن‌ها لیست شده‌اند.

ارسال درخواست

شما می‌توانید بسته به محیط توسعه‌ی خودتان، از روش‌های معمول ارسال درخواست HTTP POST یا از کتاب‌خانه‌های آماده استفاده کنید.

کد زیر، یک نمونه‌ی ارسال درخواست GraphQL با استفاده‌ از ابزار مرسوم cURL است:

$ curl 'https://next.zarinpal.com/api/v4/graphql/' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  --data-binary '{"query":"query { Application { application, platform } }","variables":null}'

احراز هویت

در این مستندات، روش احراز هویت کاربران برای دریافت مقدار{ACCESS_TOKEN}، پرس‌و‌جوها و تغییرهای (Mutations) در دسترس توضیح داده می‌شود.