Partners API

Kingfisher (Email Service) Endpoints

Authentications

Kingfisher APIs uses Bearer Token as the authentication method. Tokens are valid for seven days and can be extended two days after the expiration date.

Register User

POST https://kingfisher.kamva.ir/api/auth/register

This API registers the user in kingfisher database, and will not create a Sendinblue account. If there is a trial user with the same email in the database, it will check for passwords match. If passwords match, it will return a 200 OK response. Otherwise, it will return 400 Bad Request response.

Request Body

{
    "code": "J1X00",
    "data": {
        "token": "<auth-token>" 
    }
}

Login

POST https://kingfisher.kamva.ir/api/auth/login

This API checks for a user with given email and password and authenticate it. API returns user authentication token in response.

Request Body

{
    "code": "J1X01",
    "data": {
        "token": "<auth-token>" 
    }
}

Logout

DELETE https://kingfisher.kamva.ir/api/auth/logout

This API destroys the auth token and add it to the blacklist. Tokens that put in the blacklist won't authenticate. If auth token was invalid, API returns 400 Bad Request response.

Headers

{
    "code": "J1X02"
}

Refresh auth token

POST https://kingfisher.kamva.ir/api/auth/refresh

This API extends the given tokens expiration date. It checks the expiration date and calculates diff from current time. If the diff is less than two days (or token is not expired yet), then token expiration date will be updated to the next seven days. Otherwise, it returns 400 Bad Request response.

Headers

{
    "code": "J1X03",
    "data": {
        "token": "<refreshed-auth-token>"
    }
}

Global Authentication Responses

There may be other client error responses, for the APIs that checks the auth token before processing the requests.

In the following sections, we will describe these responses, their structures, and their reasons:

Authentication token is not provided

This error response returns when the Authorization header is empty.

{
    "code": "J1E04",
    "message": "دسترسی به این قسمت بدون توکن احراز هویت، امکان پذیر نیست."
}

Invalid token provided

This error response returns when the Authorization header is invalid. It means that the Authorization header value has not Bearer keyword before the token or token has invalid values.

{
    "code": "J1E01",
    "message": "توکن اشتباه است."
}

Token is expired

This error response returns when the provided token has expired.

{
    "code": "J1E02",
    "message": "توکن احراز هویت شما منقضی شده است. لطفا مجددا به سیستم وارد شوید."
}

Token is blacklisted

This error response returns when the provided token has been blacklisted before.

{
    "code": "J1E03",
    "message": "توکن احراز هویت شما فاقد اعتبار است."
}

Forgot Password

POST https://kingfisher.kamva.ir/api/auth/forgot-password

This API sends the forgot password email to the user to reset her/his password.

Request Body

{
    "code": "J12X00",
    "message": "ایمیل جهت تغییر رمز عبور حساب کاربری شما ارسال شد، لطفا جعبه ایمیل های خود را بررسی کنید."
}

Reset password

POST https://kingfisher.kamva.ir/api/auth/reset-password/:user_id

After clicking on the link in the email, the user's browser going to the reset password page , in that page after inserting the new password by the user, you should call to this API to reset the user's password.

Path Parameters

Request Body

{
    "code": "J5X02",
    "message": "پسورد حساب کاربری شما تغییر کرد."
}

GET https://kingfisher.kamva.ir/api/auth/SSO

return SSO link to login to the mail panel

Headers

{
"code":"J1X04",
"login_url":"5cadaxxxxxxxxxxxxxxxxxxxx5a179f85a0"
}

Plan

List available plans

GET https://kingfisher.kamva.ir/api/plan

List all available plans with their price and info (Exclude custom plans).

{
    "code":"J3X00",
    "data":[
        {
            "id":"5ce127b00cdcde50c3f9c09e",
            "price":170000,
            "title":"ساده"
        },
        {
            "id":"5ce1283c0cdcde50c3f9c870",
            "price":340000,
            "title":"حرفه‌ای"
        },
        {
            "id":"5ce128890cdcde50c3f9cb3f",
            "price":680000,
            "title":"بی‌نظیر"
        }
    ]
}

(Admin only) List available plans (Include custom plans)

GET https://kingfisher.kamva.ir/api/plan/all

List all available plans with all features (full feature)

Path Parameters

{
    "code": "J3X00",
    "data": [
        {
            "credit": 100,
            "features": {
                "transactional_mail": false,
                "transactional_sms": false,
                "marketing_automation": false
            },
            "id": "5ce128890cdcde50c3f9cb3f",
            "ip": "",
            "is_custom": true,
            "price": 1000,
            "title": "test"
        },
        {
            "credit": 1000,
            "features": {
                "transactional_mail": true,
                "transactional_sms": false,
                "marketing_automation": true
            },
            "id": "5db30de233dfa8005028fd06",
            "ip": "192.168.43.1",
            "is_custom": false,
            "price": 1000,
            "title": "test2"
        },
        {
            "credit": 444,
            "features": {
                "transactional_mail": false,
                "transactional_sms": true,
                "marketing_automation": true
            },
            "id": "5db3196633dfa8004f4ee53f",
            "ip": "192.168.12.12",
            "is_custom": false,
            "price": 1000,
            "title": "special"
        },
        {
            "credit": 100,
            "features": {
                "transactional_mail": false,
                "transactional_sms": false,
                "marketing_automation": false
            },
            "id": "5dd06fac131e96832ec0f862",
            "ip": "",
            "is_custom": false,
            "price": 1000,
            "title": "plan-4"
        },
        {
            "credit": 2000,
            "features": {
                "transactional_mail": false,
                "transactional_sms": true,
                "marketing_automation": true
            },
            "id": "5ddbe55497ea970485f4737b",
            "ip": "67.145.89.3",
            "is_custom": false,
            "price": 17000,
            "title": "test-salam"
        },
        {
            "credit": 3000,
            "features": {
                "transactional_mail": false,
                "transactional_sms": false,
                "marketing_automation": false
            },
            "id": "5ddbe67497ea9700597f9113",
            "ip": "67.145.89.3",
            "is_custom": false,
            "price": 680000,
            "title": "test-salam2"
        },
        {
            "credit": 3,
            "features": {
                "transactional_mail": false,
                "transactional_sms": true,
                "marketing_automation": false
            },
            "id": "5ddbe76997ea9700597f9115",
            "ip": "67.145.89.3",
            "is_custom": true,
            "price": 51000,
            "title": "salam3"
        }
    ]
}

Create new plan(Admin)

POST https://kingfisher.kamva.ir/api/plan

Insert new plan

Headers

Request Body

{
    "code": "J3X01",
    "data": {
        "id": "5dbabddcf0107a00432eea74",
        "price": 34000000,
        "title": "test-2"
    },
    "message": "پلن ایجاد شد."
}

update plan (Admin)

PUT https://kingfisher.kamva.ir/api/plan/:receipt_id

plans that used in subscription, we can not update those.

Path Parameters

Request Body

{
    "code": "J3X02",
    "data": {
        "id": "5dbabddcf0107a00432eea74",
        "price": 34000000,
        "title": "test3"
    },
    "message": "پلن آپدیت شد."
}

Another response for not found plan:

{
    "code": "J3E00",
    "message": "تعرفه\u200cای با مشخصات ارسال شده پیدا نشد."
}

Delete plan (Admin)

DELETE https://kingfisher.kamva.ir/api/plan/:receipt_id

We can not remove plans that are using a subscription

Path Parameters

Headers

Subscription

Subscribe

POST https://kingfisher.kamva.ir/api/subscription/subscribe

This API creates a subscription receipt and returns a receipt id for that receipt.

Headers

Request Body

{
    "code": "J2X09",
    "data": {
        "receipt_id": "<id of the receipt>"
    }
}

Here we have three state:

  • User have extended receipt: we update it's receipt's plan and price, then redirect to bank gateway and set callback to https://kingfisher.kamva.ir/receipt/verify.

  • User already subscribed : we return 403 forbidden response.

  • User don't have any subscription: we redirect to bank gateway and set callback to https://kingfisher.kamva.ir/verify

kingfisher callback URLs tries to verify payment and redirect the user back to the client. The client verification URL can be customized via PAYMENT_VERIFICATION_URL env variable. Kingfisher also pass some value through query string parameters when redirecting, to specify the status of the payment.

These parameters are:

  • authority [string]: The payment refer_id to show to the user.

  • verified [bool]: Determine whether payment verified by payment gateway or not.

  • status [string]: Determine the status of payment, subscription creation and registration on Sendinblue. It may have one of the following values:

    • success: everything went well.

    • failed: payment not verified in kingfisher side or payment gateway side.

    • cancelled: payment has been cancelled by user.

    • internal_error: some internal error occurred.

  • receipt_id: ID of paying receipt. It is not_found if no receipt found related to payment authority.

  • error_code: when status parameter value is internal_error, an error code will be passed to specify the reason of error.

In some situations, an internal error may occur after verifying payment. It means that payment has been verified successfully – and the money will not return back to the payee account – but some of the operation that will happen after payment verification has been failed. You should find the reason by searching error_code in codes and fix it manually.

Sometime when API returns 200 OK response, sendinblue registration may be failed but successfully queue for retrying.

update subscription receipt

POST https://kingfisher.kamva.ir/api/subscription/update/:receipt_id

Update subscription receipt, e.g apply discount code, change plan

Headers

Request Body

{
    "code": "J2X02",
    "messsage":"تغییرات روی فاکتور اعمال شد.",
    "data": {
				"confirm_url": "https:pakat.profile.net/confirm/5df0a68c9643cb0048794ab7",
        "discount": 0,
        "has_authority": false,
        "id": "5df0a68c9643cb0048794ab7",
        "plan": "special",
        "plan_id": "5db3196633dfa8004f4ee53f",
        "price": 1000,
        "tax": 90,
        "total_price": 1090,
        "type": "subscription",
        "verified": false
    }
}

GET https://kingfisher.kamva.ir/api/subscription/pay/:receipt_id

Get payment link to subscription receipt

Headers

{
    "code": "J2X00",
    "data": {
        "payment_url": "https://www.zarinpal.com/pg/StartPay/<authority>/ZarinGate"
    }
}

All 4xx error responses in /subscription/subscribe API may return here also.

Verify Failed payment

POST https://kingfisher.kamva.ir/api/verify-failed

Check last state of receipt and verify it (if needed)

Headers

Request Body

{
    "code": "J2X03",
    "message": "فاکتور با موفقیت بررسی و ثبت شد."
}

There may be other responses in some situations:

If payment is unsuccessful:

{
    "code": "J2E03",
    "message": "Payment failed with status code 22|..."
}

or

{
    "code": "J2E03",
    "message": "مشکلی در بررسی پرداخت شما رخ داده است، لطفا چند دقیقه بعد مجددا تلاش نمایید."
}

When the subscription is active but the user calls to this API

{
    "code": "J2E13",
    "message": "اشتراک شما فعال می باشد."
}

[Admin Only] subscribe user manually

POST https://kingfisher.kamva.ir/api/subscription/manual

Subscribe a user manually by admin

Request Body

{
    "code": "J2X04",
    "message": "اشتراک با موفقیت ایجاد و در صف پردازش قرار گرفت"
}

In addition to the written responses, you need to also check internal error responses.

(Admin only) Extend user's subscription manually

POST https://kingfisher.kamva.ir/api/subscription/extend

Extend user's subscription manually by admin

Request Body

{
"code":"J2E05",
"message":"اشتراک به صورت دستی تمدید شد."
}

Some other 403 Forbidden responses:

{
    "code":"J2E22",
    "message":"کاربر ابتدا باید اشتراک بگیرد.(تا به حال اشتراکی نداشته است)"
}
{
    "code":"J2E23",
    "message":"بیشتر از ۱۰ روز تا اتمام اشتراک فعلی زمان باقی مانده است."
}
{
    "code":"J2E26",
    "message":"رسید تمدید دستی قبلا ایجاد شده است."
}
{
    "code":"J2E25",
    "message":"کاربر مورد نظر قبلا رسیدی را جهت تمدید، پرداخت کرده است."
}

(Admin Only) Extend user's extension history

POST https://kingfisher.kamva.ir/api/subscription/history/extend

Extend the user subscription history, This API doesn't add the credit, just add expired receipt

Request Body

{
"code":"J2X05",
"message":"اشتراک به صورت دستی تمدید شد."
}

Some other 403 Forbidden responses:

{
    "code":"J2E22",
    "message":"کاربر ابتدا باید اشتراک بگیرد.(تا به حال اشتراکی نداشته است)"
}
{
    "code":"J2E29",
    "message":"تاریخ تمدید باید در گذشته باشد."
}

[Admin Only] Add Trial User (Deprecated)

POST https://kingfisher.kamva.ir/api/subscription/trial

This API register a user as a trial user. Note: This API method is deprecated, use /api/subscription/trial-existed-user

Headers

Request Body

{
    "code": "J4X00",
    "message": "اکانت آزمایشی با موفقیت ساخته شد و پروسه فعال‌سازی اکانت در سرویس sendinblue در صف پردازش قرار گرفت.",
    "data": {
        "auth_key": "<user-auth-key>"
    }
}

If a 200 OK response returns with an empty auth_key field, it means registering user in sendinblue and it has queued for retrying.

Give Trial subscription to user (Admin Only)

POST https://kingfisher.kamva.ir/api/v1/subscription/trial-existed-user

Give trial charge to user

Headers

Request Body

{
    "code": "J4X00",
    "message": "اکانت آزمایشی با موفقیت ساخته شد و پروسه فعال‌سازی اکانت در سرویس sendinblue در صف پردازش قرار گرفت.",
    "data": {
        "auth_key": "<user-auth-key>"
    }
}

[Admin Only] Add Sponsorship Account

POST https://kingfisher.kamva.ir/api/subscription/sponsorship

Headers

Request Body

{
    "code": "J4X01",
    "message": "اکانت اسپانسرشیپ با موفقیت ساخته شد و پروسه فعال‌سازی اکانت در سرویس sendinblue در صف پردازش قرار گرفت.",
    "data": {
        "auth_key": "<user-auth-key>"
    }
}

If a 200 OK response returns with an empty auth_key field, it means registering user in sendinblue and it has queued for retrying.

Credit

(Admin Only) Add credit to user

POST https://kingfisher.kamva.ir/api/credit/add

Request Body

{
"code":"J2X06"
"message":"کردیت به صورت دستی اضافه شد."
}

Low Credit Reminder Settings

Add low credit threshold settings (Admin Only)

POST https://kingfisher.kamva.ir/api/credit/threshold

Add low credit settings for specific user

Headers

Request Body

{
    "code": "J19X01",
    "message": "تنظیمات credit ثبت شد."
}

Update Low Credit Threshold Settings

PUT https://kingfisher.kamva.ir/api/credit/threshold/{threshold_settings_id}

Headers

Request Body

{
    "code": "J19X02",
    "message": "تنظیمات credit بروز شد."
}

Delete low credit threshold settings (Admin Only)

DELETE https://kingfisher.kamva.ir/api/credit/threshold/{threshold_settings_id}

Headers

{
    "code": "J19X03",
    "message": "تنظیمات credit حذف شد."
}

Receipt

Get Receipt Info

GET https://kingfisher.kamva.ir/api/receipt/{receipt_id}

This API returns information about the receipt with the given ID.

Path Parameters

Headers

{
    "code": "J2X01",
    "data": {
        "discount": 0,
        "has_authority": true,
        "plan": "ساده",
        "price": 1000,
        "tax": 0,
        "total_price": 1000,
        "type": "extended",
        "verified": false
    }
}

Client should have a page to show the receipt data before redirecting user to payment gateway. This page url should be like https://<domain>/<path>/<receipt_id>. Since this URL is used in expiration reminder emails and SMSs, it is configurable via RECEIPT_BASE_URL. This variable should contains domain and path part of example url above. for example it should be https://kamva.ir/email/receipt.

In this page we have either "Pay" or "Verify Payment" or "Pay Again" button relative to these scenarios : 1. if the receipt is unverified (verified: false) and authority is false (has_authority: false ) , show a simple "pay" button.

2. If the receipt is unverified but has_authority is true , show "Verify payment" button that on clicked on it, send request to /verify-failed route and get result, if have paymentError result (see description of this route) , hide this button and show "pay again" button that have URL same as "Pay" button.

Get unpaid receipt

GET https://kingfisher.kamva.ir/api/receipt/unpaid

This API return unpaid extended receipt to you.

Headers

{
    "code":"J2X07",
    "data": {
        "discount": 0,
        "has_authority": false,
        "plan": "ساده",
        "price": 1000,
        "tax": 0,
        "total_price": 1000,
        "type": "extended",
        "verified": false
    }
}

Update extension receipt (Upgrade receipt)

POST https://kingfisher.kamva.ir/api/receipt/:receipt_id/update

Update plan of receipt or set you'r discount code for extended receipt.

Path Parameters

Headers

Request Body

{
    "code":"J2X02",
    "data":{
        "discount": 0,
        "has_authority": true,
        "plan": "حرفه ای",
        "price": 1000,
        "tax": 0,
        "total_price": 1000,
        "type": "extended",
        "verified": false
    }
}

Other Situations:

If plan id be invalid (404 : Not Found)

{
    "code":"J3E00",
    "message":"تعرفه‌ای با مشخصات ارسال شده پیدا نشد."
}

Pay Receipt

GET https://kingfisher.kamva.ir/api/receipt/{receipt_id}/pay

This API generate and return receipt payment url.

Path Parameters

Headers

{
    "code": "J2X00",
    "payment_url": "https://www.zarinpal.com/pg/StartPay/<authority>/ZarinGate"
}

After the user paid the subscription receipt, will be redirected to https://kingfisher.kamva.ir/verify. In this URL, kingfisher tries to verify payment and redirect the user back to the client. The client verification URL can be customized via PAYMENT_VERIFICATION_URL env variable. Kingfisher also pass some value through query string parameters when redirecting, to specify status of the payment.

These parameters are exactly like the parameter in subscription section.

Discount

List all discounts (Admin only)

GET https://kingfisher.kamva.ir/api/discount/all

Path Parameters

{
    "code": "J18X00",
    "data": [
        {
            "code": "yalda-1",
            "count": 1,
            "description": "تخفیف یلد",
            "discount": 10,
            "expire_at": "2019-12-10T11:46:36.515Z",
            "expired": true,
            "id": "5df0d4699643cb00506bab43",
            "multi_pass": true,
            "multi_plan": true,
            "plan_id": "",
            "plan_title": "",
            "user_email": ""
        },
        {
            "code": "yalda2",
            "count": 1,
            "description": "test",
            "discount": 50,
            "expire_at": "2019-12-21T00:00:00Z",
            "expired": false,
            "id": "5defb78e9643cb005b870715",
            "multi_pass": true,
            "multi_plan": true,
            "plan_id": "",
            "plan_title": "",
            "user_email": ""
        }
    ]
}

Create New Discount (Admin only)

POST https://kingfisher.kamva.ir/api/discount

Request Body

{
    "code": "J18X02",
    "data": {
        "code": "yalda-1",
        "count": 1,
        "description": "تخفیف یلد",
        "discount": 10,
        "expire_at": "2020-02-02T12:00:00Z",
        "expired": false,
        "id": "5df0d4699643cb00506bab43",
        "multi_pass": true,
        "multi_plan": true,
        "plan_id": "",
        "plan_title": "",
        "user_email": ""
    },
    "message": "تخفیف ایجاد شد."
}

Edit discount (Admin only)

PUT https://kingfisher.kamva.ir/api/discount/:descount_id

Request Body

{
    "code": "J18X03",
    "data": {
        "code": "yalda-1",
        "count": 1,
        "description": "تخفیف یلد",
        "discount": 10,
        "expire_at": "2020-02-02T12:00:00Z",
        "expired": false,
        "id": "5df0d4699643cb00506bab43",
        "multi_pass": true,
        "multi_plan": true,
        "plan_id": "",
        "plan_title": "",
        "user_email": ""
    },
    "message": "تخفیف بروز شد."
}

Expire Discount (Admin only)

POST https://kingfisher.kamva.ir/api/discount/:discount_id/expire

Path Parameters

{
    "code": "J18X04",
    "message": "تخفیف expire شد."
}

IP

List IPs (Admin Only)

GET https://kingfisher.kamva.ir/api/ip

List all IPs for the Admin

Headers

{
    "code": "J14X02",
    "data": {
        "ips": [
            {
                "ip": "86.34.3.23",
                "domain": "smtp2.kamva.ir",
                "active": true
            },
            {
                "ip": "70.83.33.3",
                "domain": "smtp2.kamva.ir",
                "active": true
            }
        ]
    }
}

Associate IP to user

POST https://kingfisher.kamva.ir/api/ip/associate

Headers

Request Body

{
    "code":"J14X00",
    "message":"IP اختصاص داده شد."
}

Dissociate IP (Admin Only)

POST https://kingfisher.kamva.ir/api/ip/dissociate

Dissociate IP form specific user

Headers

Request Body

{
    "code":"J14X01",
    "message":"IP حذف شد."
}

Sender

Create Sender (Admin Only)

POST https://kingfisher.kamva.ir/api/sender

Headers

Request Body

{
    "code":"J17X00",
    "message":"ارسال کننده ایجاد شد."
}

Info

Get Malicious users list (Admin Only)

GET https://kingfisher.kamva.ir/api/info/malicious-users

Return list of malicious users with their campaigns name. Malicious user is user that send spam mails

Headers

{
    "code": "J16X00",
    "data": [
        {
            "campaign_id": 43,
            "campaign_name": "test-campaign",
            "company_name": "Check Company",
            "detection_date": "1398-09-15 03:30",
            "email": "mehr.prs@gmail.com",
            "first_name": "mehran",
            "full_name": "mehran prs",
            "id": "5d97273cd6194c28f890fed4",
            "is_admin": false,
            "last_name": "prs",
            "phone": ""
        },
        {
            "campaign_id": 43,
            "campaign_name": "test-campaign",
            "company_name": "check",
            "detection_date": "1398-09-15 03:30",
            "email": "check@gmail.com",
            "first_name": "mehran",
            "full_name": "check-user check-last",
            "id": "5de7b097d06e7d009a294194",
            "is_admin": false,
            "last_name": "prs",
            "phone": ""
        }
    ]
}

Notification

Get Notification settings

GET https://kingfisher.kamva.ir/api/notification/{driver}/settings

Use this API to get notification settings.

Path Parameters

Headers

{