درباره API

صفحه‌های این بخش مستقیماً از سند OpenAPI کوین‌لند پی تولید می‌شوند، پس دقیقاً همان چیزی را توصیف می‌کنند که هر اندپوینت می‌پذیرد و برمی‌گرداند. خودِ سند در /openapi.json منتشر شده است، اگر می‌خواهید از رویش کلاینت، سرور ساختگی یا تایپ تولید کنید.

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

نشانی پایه

https://my.coinlandexchange.com

هر اندپوینت کوین‌لند پی زیر /api/pay/v1 قرار دارد. یک میزبان و یک محیط وجود دارد: جلسه‌ای که می‌سازید جلسه‌ای است که یک مشتری واقعی می‌تواند پرداختش کند. برای تمرین ایمن آماده انتشار را ببینید.

احراز هویت

یک هدر روی هر درخواست:

Authorization: Bearer clpay_live_<64 hex>

کلیدها در کنسول کسب‌وکار ساخته و باطل می‌شوند و فقط در لحظه ساخت نمایش داده می‌شوند. هر رد شدن در لایه احراز هویت — هدر غایب، کلید بدشکل، کلید باطل‌شده، کلید ناشناس — با کد یگانه UNAUTHORIZED (۴۰۱) پاسخ می‌گیرد، تا فراخواننده نتواند بفهمد کدام بخش اشتباه بوده است.

قراردادها

درخواست‌ها و پاسخ‌ها JSON هستند؛ روی هر چیزی که بدنه دارد Content-Type: application/json بفرستید.

مبالغ رشته اعشاری هستند. "24.90"، هرگز 24.9. این برای amount، fee_amount و net_amount و در درخواست و پاسخ یکسان صادق است. تا رسیدن به یک نوع اعشاری دقیق در کد خودتان، آن‌ها را رشته نگه دارید.

زمان‌ها با قالب RFC 3339 و در UTC هستند. شامل expires_at، created_at، paid_at و فیلترهای from و to.

شناسه‌ها دو شکل دارند و هر دو به‌عنوان کلید جست‌وجو کار می‌کنند. جلسه‌های پرداخت و پرداخت‌ها شناسه یکتا دارند، اما GET /sessions/{id} شناسه reference_id خودتان را هم می‌پذیرد و GET /payments/{id} شماره رسید (CLP-...) را. پس می‌توانید هر کدام را بخوانید بدون آنکه چیزی از آنچه کوین‌لند تولید کرده ذخیره کرده باشید.

فهرست‌ها با مکان‌نما صفحه‌بندی می‌شوند و از جدید به قدیم‌اند. limit و cursor بفرستید و next_cursor را دنبال کنید تا null برگردد. صفحه‌ها را نشمارید و اندازه صفحه را فرض نگیرید.

ایدمپوتنسی روی reference_id است. هدر Idempotency-Key وجود ندارد. ارسال دوباره POST /sessions با همان reference_id و محتوای یکسان جلسه اصلی را برمی‌گرداند؛ همان شناسه با محتوای متفاوت با PAY_DUPLICATE_REFERENCE رد می‌شود. جلسه‌های پرداخت را ببینید.

«پیدا نشد» و «مال شما نیست» یکسان پاسخ می‌دهند. PAY_SESSION_NOT_FOUND (۴۰۴) هر دو را پوشش می‌دهد، چون پاسخ متفاوت برای «وجود دارد اما به کسب‌وکار دیگری تعلق دارد» به هر کسی با یک کلید اجازه می‌داد سفارش‌های کسب‌وکارهای دیگر را شمارش کند.

پایداری

API در مسیر و با /v1 نسخه‌بندی شده است. درون یک نسخه، تغییرات افزودنی‌اند: اندپوینت‌های تازه، فیلدهای اختیاری تازه در درخواست و ویژگی‌های تازه در پاسخ می‌توانند بدون اطلاع قبلی ظاهر شوند، و فیلدهای موجود معنایشان تغییر نمی‌کند و حذف نمی‌شوند. هر تغییر ناسازگار به‌صورت یک نسخه تازه منتشر می‌شود و /v1 به کار خود ادامه می‌دهد.

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

قابلیت اتکا

وقفه زمانی را با همان reference_id دوباره تلاش کنید؛ ایدمپوتنسی برای همین است. روی 429 با تأخیر تصادفی عقب بکشید. هر خطا از یک قالب واحد استفاده می‌کند — خطاها را ببینید.

از کجا شروع کنیم

Sessions مجموعه اندپوینتی است که هر یکپارچه‌سازی به آن نیاز دارد. GET /me اولین فراخوانی است که ارزش انجام دادن دارد، چون می‌گوید مجاز به قیمت‌گذاری در چه ارزهایی هستید.