Developers

مستندات استفاده از REST API

شروع

برای شروع کار با سامانه اول نیاز دارید تا در سیستم ثبت نام کنید و پس از معرفی خودتون به عنوان نمایش‌دهنده، سیستم به شما یک کلید نمایش‌دهنده (Publisher Key) و یک کلید رمز (Secret Key) اختصاص میده که با استفاده از اون می‌تونید با API ارتباط برقرار کنید.

کلید نمایش‌دهنده (Publisher Key)

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

کلید رمز (Secret Key)

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

نحوه کارکرد کلی

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

درخواست ایجاد تصویر امنیتی

URL: https://api.adeto.ir/v1/create
Method: POST
Response Type: JSON

Parameter Status Description
publisherKey REQUIRED The publisher key which you got after signing-up as a publisher
lang Optional Captcha language. Could be 'fa' or 'en'. default is 'fa'
customId Optional A custom id in case you're locking a specific page and you want to receive the custom id in response

Send an example request using cURL (since we're not sending 'lang', the generated captcha language will be Farsi which is the default language)



curl "https://api.adeto.ir/v1/create" -X POST -d publisherKey=123456789

                                    

Send an example request for an English captcha using cURL



curl "https://api.adeto.ir/v1/create" -X POST -d publisherKey=123456789 -d lang=en

                                    

Response in JSON



{
    "status": "success",
    "message": "",
    "data": {
        "adImage": "1c869d2ca83fc6a16bdf43cb8f92037b_4165534_a.jpg",
        "adImageAddress": "https://tmp.adeto.ir/1c869d2ca83fc6a16bdf43cb8f92037b_4165534_a.jpg",
        "captchaImage": "1c869d2ca83fc6a16bdf43cb8f92037b_4165534.jpg",
        "captchaImageAddress": "https://tmp.adeto.ir/1c869d2ca83fc6a16bdf43cb8f92037b_4165534.jpg",
        "hash": "1513694048:bd7aa50d41d6025cd6e4369a7c34cfe0c873727cca0bdb9a7dd2e370f8e3502c:!od@sw^*$+#",
        "publisherKey": "123456789",
        "lang": "fa",
        "customId": ""
    }
}

                                    

response explanation table

Parameter Description
status if everything goes well in your request, it's gonna be "success", otherwise it will be "failed"
message if anything goes wrong, you will get the error message here
adImage the image name for the add (first image that the user sees before the captcha), just the image name
adImageAddress the adImage above with complete and accessible URL
captchaImage real captcha image name, just the image name
captchaImageAddress the captchaImage above with complete and accessible URL
hash just a long string that we need, don't worry about it
publisherKey we send back your Publisher Key to you again
lang we send back your requested captcha language to you again
customId if you have already sent your request with a customId, we send it back here again so you know what you have requested

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

URL: https://api.adeto.ir/v1/verify
Method: POST
Response Type: JSON

Parameter Status Description
publisherKey REQUIRED The publisher key which you got after signing-up as a publisher
secretKey REQUIRED The secret key which you got after signing-up as a publisher
userInputValue REQUIRED The user response string which you want to validate
userIP REQUIRED The user IP address
imageName REQUIRED The "captchaImage" value which api sent to you when you created the captcha
hash REQUIRED The "hash" value which api sent to you when you created the captcha
customId Optional If you sent the request with a custumId, you need to provide it here again so it matches to your request

Send an example verification request using cURL



curl "https://api.adeto.ir/v1/verify"
-X POST
-d publisherKey=123456789
-d secretKey=zxcvbnm
-d userInputValue=متن کاربر
-d userIP=185.104.192.6
-d imageName=1c869d2ca83fc6a16bdf43cb8f92037b_4165534.jpg
-d hash=1513694048:bd7aa50d41d6025cd6e4369a7c34cfe0c873727cca0bdb9a7dd2e370f8e3502c:!od@sw^*$+#

                                    

Response in JSON



{
    "status": "true",
    "message": "",
    "data": {
        "publisherKey": "123456789",
        "imageName": "1c869d2ca83fc6a16bdf43cb8f92037b_4165534.jpg",
        "hash": "1513694048:bd7aa50d41d6025cd6e4369a7c34cfe0c873727cca0bdb9a7dd2e370f8e3502c:!od@sw^*$+#",
        "userInputValue": "متن کاربر",
        "customId": ""
    }
}

                                    

در پاسخ دریافتی از سمت سرور در بالا با استفاده از مقدار status که true/false هست می‌تونید اعتبار حروف وارد شده توسط کاربر رو بسنجید. بدیهیه که true به معنی معتبر بودن حروف وارد شده توسط کاربر و false به معنی نامعتبر بودن اون هست.

لازم به ذکر هست که هر تصویر امنیتی تولید شده فقط برای 3 دقیقه معتبر هست و بعد از اون expire میشه.