# معرفی

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

با استفاده از این 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) در دسترس توضیح داده می‌شود.

راهنمای احراز هویت