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

Name	Type	Description
email	string	user valid email address
phone	string	user phone number
first_name	string	user first name
last_name	string	user last name
company_name	string	user company name
password	string	a secure strong password, minimum 8 character

200 User successfully registered.

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

400 User already exists. Note: If trial users, enter the correct password in register API a 200 OK response will be returned.

{
    "code": "J1E00",
    "message": "کاربری با این ایمیل وجود دارد."
}

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

Name	Type	Description
email	string	user email
password	string	user password

200

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

401

{
    "code": "J1E00",
    "message": "ایمیل یا رمز عبور اشتباه است."
}

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

Name	Type	Description
Authorization	string	Auth token

200

{
    "code": "J1X02"
}

400 If token was invalid

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

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

Name	Type	Description
Authorization	string	Auth token

200

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

400

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

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

Name	Type	Description
email	string	users's email

200

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

404

{
    "code": "J1E07",
    "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

Name	Type	Description
user_id	string	The user's ID

Request Body

Name	Type	Description
sig	string	The signature in link query parameter (don't need to unescaping it)
expires	integer	The expire time (get from link query parameters)
password	string	The new password

200

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

400 When the signature is invalid

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

422 When the link has been expired

{
    "code": "J12E01",
    "message": "لینک منقضی شده است."
}

SSO Link

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

return SSO link to login to the mail panel

Headers

Name	Type	Description
Authorization	string	Auth token

200

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

500

{
"code":"J9E00",
"message":"در پردازش درخواست شما مشکلی از سمت ما پیش ‌آمده، لطفا چند دقیقه بعد مجددا تلاش کنید. در صورت تکرار مشکل را با پشتیبانی مطرح کنید."
}

Plan

List available plans

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

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

200 returns array of plan objects

{
    "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

Name	Type	Description
	string

200

{
    "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

Name	Type	Description
Authorization	string	Auth token

Request Body

Name	Type	Description
marketing_automation	boolean	enable marketing automation
transactional_mail	boolean	enable transactional mail
transactional_sms	boolean	enable transactional sms
is_custom	boolean	plan is custom?
credit	number	credit
price	number	Price (in euro)
key	string	key of plan (must be unique)
title	string	Title of plan(must be unique)
ip	string	plan's IP

201

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

400

{
    "code": "J3E02",
    "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

Name	Type	Description
receipt_id	string	ID of receipt

Request Body

Name	Type	Description
marketing_automation	string	enable marketing automation
transactional_sms	string	enable transactional SMS
transactional_mail	string	enable transactional mail
is_custom	string	panel is custom?
credit	string	credit value
price	string	price
ip	string	IP
key	string	key
title	string	Title of plan

200

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

400

{
    "code": "J3E02",
    "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

Name	Type	Description
receipt_id	string	receipt id

Headers

Name	Type	Description
Authorization	string	Auth token

204

400

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

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

Name	Type	Description
Authorization	string	Auth token

Request Body

Name	Type	Description
plan_id	string	ID of selected plan

200

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

403 When the user have subscription

{
"code":"J2E21",
"message":"کاربر قبلا پلن اشتراکی خود را گرفته است، میتوانید آن را تمدید کنید."
}

404

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

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

Name	Type	Description
Authorization	string	bearer <your jwt token>
Content-Type	string	Application/json

Request Body

Name	Type	Description
code	string	discount code
plan_id	string	id of plan

200

{
    "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 payment link to subscription receipt

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

Get payment link to subscription receipt

Headers

Name	Type	Description
Content-Type	string	Application/json
Authorization	string	bearer <your jwt token>

200

{
    "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

Name	Type	Description
Authorization	string	Auth token

Request Body

Name	Type	Description
receipt_id	string	ID of receipt

200

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

404

{
    "code": "J2E11",
    "message": "رسیدی با این مشخصات وجود ندارد."
}

422

{
    "code": "J2E18",
    "message": "درخواستی برای پرداخت فاکتور صورت نگرفته است."
}

500

{
    "code":"J9E00",
    "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

Name	Type	Description
discount_code	string	If you have discount code, insert it here. API accept this discount code just if you don't provide any subscribed_at field.
email	string	The user's email address
subscribed_at	string	subscription date, if it's before now, we do not add credit to her/his account. Example format of date: 2006-01-02T15:04:05Z
plan_id	string	The plan ID

200

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

403 When you are not Admin

{
    "code":"J1E06",
    "message":"شما دسترسی لازم برای انجام این عملیات را ندارید."
}
or 
{
    "code":"J2E21",
    "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

Name	Type	Description
discount_code	string	discount code to using on extend plan.
plan_id	string	The plan ID
email	string	The user's email address

200

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

404

{
    "code":"J1E07"
    "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

Name	Type	Description
plan_id	string	The plan ID
email	string	The user's email address
begin_at	string	Date of beginning extension example format: 2016-02-01T15:03:04Z

200

{
"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

Name	Type	Description
Authorization	string	Admin auth token

Request Body

Name	Type	Description
email	string	user valid email address
first_name	string	user first name
last_name	string	user last name
company_name	string	user company name
password	string	a secure strong password, minimum 8 character

200 Trial user added.

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

403 A user with the given email already exists and it has used trial or has purchased a plan before.

{
    "code": "J4E00",
    "message": "کاربری با این ایمیل قبلا در سیستم ثبت شده است و از اکانت آزمایشی استفاده کرده است و یا قبلا سرویس را خریداری کرده است."
}

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

Name	Type	Description
Authorization	string	your bearer token
Content-Type	string	Application/json

Request Body

Name	Type	Description
email	string	user's email that you want to give trial subscription to her/him

200

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

403 A user with the given email already has purchased a plan or used trial subscription.

{
    "code": "J4E00",
    "message": "کاربری با این ایمیل قبلا در سیستم ثبت شده است و از اکانت آزمایشی استفاده کرده است و یا قبلا سرویس را خریداری کرده است."
}

[Admin Only] Add Sponsorship Account

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

Headers

Name	Type	Description
Authorization	string	Admin auth token

Request Body

Name	Type	Description
email	string	user valid email address
first_name	string	user first name
last_name	string	user last name
company_name	string	user company name
password	string	a secure strong password, minimum 8 character
month	integer	number of sponsorship months
plan_id	string	ID of plan for sponsor

200 Sponsorship account added successfully.

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

400 A user with given email already exists and password does not match.

{
    "code": "J1E00",
    "message": "کاربری با این ایمیل وجود دارد."
}

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

Name	Type	Description
credit	integer	Credit value (e.g 200)
email	string	The user's email

200

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

400 When user don't have any active subscription, cannot add credit.

{
"code":"J2E28"
"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

Name	Type	Description
Authorization	string	you'r bearer token
Content-Type	string	Application/json

Request Body

Name	Type	Description
threshold	integer	emails credit threshold to send notify user
user_email	string	user's email address

200

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

404

{
"code":"J1E07",
"message":"کاربر با ایمیل وارد شده وجود ندارد."
}

Update Low Credit Threshold Settings

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

Headers

Name	Type	Description
Authorization	string	your bearer token
Content-Type	string	Application/json

Request Body

Name	Type	Description
threshold	integer	emails credit count to send notification

200

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

404

{
    "code": "J19E01",
    "message": "تنظیمات یافت نشد."
}

Delete low credit threshold settings (Admin Only)

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

Headers

Name	Type	Description
Authorization	string	your bearer token
Content-Type	string	Application/json

200

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

404

{
    "code": "J19E01",
    "message": "تنظیمات یافت نشد."
}

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

Name	Type	Description
receipt_id	string	ID of receipt

Headers

Name	Type	Description
Authorization	string	Auth token

200 Receipt data fetched successfully.

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

404

{
    "code": "J2E11",
    "message": "رسیدی با این مشخصات وجود ندارد."
}

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

Name	Type	Description
Authorization	string	bearer <your bearer token>
Content-Type	string	Application/json

200

{
    "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

Name	Type	Description
receipt_id	string	The receipt ID

Headers

Name	Type	Description
Authorization	string	Auth token

Request Body

Name	Type	Description
code	string	Discount code to apply on receipt
plan_id	string	The plan ID

200

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

403

{
    "code":"J2E14",
    "message":"رسید قبلا مورد استفاده قرار گرفه است"
}

404

{
    "code":"J2E11",
    "message":"رسیدی با این مشخصات وجود ندارد."
}

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

Name	Type	Description
receipt_id	string	ID of receipt to pay

Headers

Name	Type	Description
Authorization	string	Auth token

200 Receipt payment url generated successfully.

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

403 Return this response when you'r previous payment was successful but want to pay again. (in this situation you should show old receipt page and request to /verify-failed page)

{
    "code": "J2E20",
    "message": "پرداخت قبلی شما برای این فاکتور موفقیت آمیز بوده است، لطفا فاکتور خود را بررسی کنید",
    "data":{
        "receipt_id":"5daec856b1ddca000ed7f1f5"
    }
}

404

{
    "code": "J2E11",
    "message": "رسیدی با این مشخصات وجود ندارد."
}

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

Name	Type	Description
limit	integer	count of items that should retrn (default:50)
skip	integer	how many item should skip? (default : 0)

200

{
    "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

Name	Type	Description
expire_at	string	expire date of discount (in ISO8601 format)
multi_pass	string	This discount can use by all user's or just specific user?
multi_plan	boolean	This discount is for all plans or just specific plan?
count	integer	How many times can use this discount code?
description	string	Short description about your discount
discount	integer	The discount value (percent)
code	string	discount code (this value should be unique per plans)
user_email	string	If discount is for just single user, pass the user's email here. This field is required if multi_user is false .
plan_id	string	ID of the plan that you want to add discount to it. This field is required if multi_plan field is false

200

{
    "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

Name	Type	Description
expire_at	string	Expire date of discount (ISO8061 format)
multi_pass	boolean	Set this field to true if all users can use this discount.
multi_plan	boolean	Set this field to true if all plans can use this discount.
count	integer	How many times can use this discount?
Description	string	Short description about the discount.
discount	integer	Percent of discount
code	string	Discount code
user_email	string	Id of user that can use this discount required if multi_pass is false.
plan_id	string	Id of the plan. required if multi_plan is false.

200

{
    "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

Name	Type	Description
	string

200

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

IP

List IPs (Admin Only)

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

List all IPs for the Admin

Headers

Name	Type	Description
Cotent-Type	string	Application/json
Authorization	string	bearer <your token>

200

{
    "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

Name	Type	Description
Content-Type	string	Application/json
Authorization	string	bearer <token>

Request Body

Name	Type	Description
ip	string	The IP that want to associate to your user
email	string	The user's email

200

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

Dissociate IP (Admin Only)

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

Dissociate IP form specific user

Headers

Name	Type	Description
Authorization	string	bearer <token>
Content-Type	string	Application/json

Request Body

Name	Type	Description
email	string	User's email
ip	string	The IP that want to dissociate from user

200

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

Sender

Create Sender (Admin Only)

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

Headers

Name	Type	Description
Authorization	string	bearer <token>
Content-Type	string	Application/json

Request Body

Name	Type	Description
name	string	Name of the sender
email	string	The email
ip	string	The IP
domain	string	Domain name

200

{
    "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

Name	Type	Description
Authorization	string	bearer <token>
Content-Type	string	Application/json

200

{
    "code": "J16X00",
    "data": [
        {
            "campaign_id": 43,
            "campaign_name": "test-campaign",
            "company_name": "Check Company",
            "detection_date": "1398-09-15 03:30",
            "email": "[e-mail]",
            "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": "[e-mail]",
            "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

Name	Type	Description
driver	string	driver is notification provider name. possible values: najva

Headers

Name	Type	Description
Authorization	string	Authorization token.

200

{
    "code": "J1X01",
    "data": {
        "token": "9oNT1MjNnCfABu4aGXUXmRSO-PtAq9ZoEFYBJd53TmgOu4Ir8q3RVe_DmQH7r2w0LTEeSQDFw-Y6YD2Y0cQUqR6SpGve0crvb-tWXMGxayvbqp6h5nDY5PQbqjcL41fX54cJSglxLJTEBTc2gcdgxQ"
    }
}

Set Notification Settings

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

Use this API to set API key of your app and also Authorization token (or server_key)

Path Parameters

Name	Type	Description
driver	string	name of notifaction provider. possible values: najva
Authorization	string	Authorization token

Request Body

Name	Type	Description
server_key	string	your server key or Authorization token (relative to notification provider settings)
web_api_key	string	your app api key

200

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

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

Path Parameters

Name	Type	Description
driver	string	driver is notification provider name. possible values: najva

200

Insert (update if exists) Contact

POST https://kingfisher.kamva.ir/api/{driver}/contact/{server_key:string}/

Use this API to upsert (insert or update) your contact token with sendinblue contacts.

Path Parameters

Name	Type	Description
driver	string	name of notification provider. possible values: najva

Request Body

Name	Type	Description
device_type	string	user's device type that you get token from it. possible values: "ios", "android", "web"
token	string	notification token
email	string	user's email

200

{
    "code":"J20X01",
    "message":"کاربر ثبت شد."
}

Get notification list

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

Get notification list

Path Parameters

Name	Type	Description
driver	string	name of notification provider. possible values: najva

Query Parameters

Name	Type	Description
limit	integer	use to limit pagination items count (defaul:50)
skip	integer	skip paramter for paginaion (defaut:0)

200

{
    "code": "J20X07",
    "data": [
        {
            "body": "خوبی؟",
            "content": null,
            "device_type": "web",
            "icon": null,
            "id": "5e1c519d62a53f0059a087fc",
            "image": null,
            "on_click_action": "open-link",
            "title": "سلام",
            "url": "https://google.com/",
            "webhook": "kamva.ir/api/notification/najva/webhook/yOawAcMAsseEAQzPjjvAfKPYXQmkGc"
        },
        {
            "body": "khoobi?",
            "content": "heeyyy",
            "device_type": "phone",
            "icon": "https://google.com",
            "id": "5e1b0600361f480051e342ab",
            "image": "https://google.com",
            "on_click_action": "open-link",
            "title": "Salam",
            "url": "http://pakat.net",
            "webhook": "kamva.ir/notification/najva/webhook/NsbFGqmiRPHJZFLXXQTugwZehxiibw"
        }
    ]
}

Create Notification

POST https://kingfisher.kamva.ir/api/{driver}

Use to create notification

Path Parameters

Name	Type	Description
driver	string	name of notification provider. possible values: najva

Request Body

Name	Type	Description
title	string	Notification title
body	string	Notification body
content	string	If set your "on_click_action" to "open-sms", using this value as sms content.
icon	string	notification icon url
image	string	notification image url
on_click_action	string	what happen on user clicked on the notification?
url	string	URL to use as URL of your click action
device_type	string	send this notification to what type of devices? possible values: ios, android, web, phone, all. If you choose "phone", we send notification to ios and android phones.

200

{
    "code": "J20X02",
    "message": "نوتیفیکیشن ایجاد شد."
}

Get Notification Info

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

Get notification by it's id.

Path Parameters

Name	Type	Description
notification_id	string	id of notification.
driver	string	name of notification provider. possible values: najva.

200

{
    "code": "J20X03",
    "data": {
        "body": "khoobi?",
        "content": "",
        "device_type": "phone",
        "icon": "https://google.com",
        "id": "5e1b0600361f480051e342ab",
        "image": "https://google.com",
        "on_click_action": "open-call",
        "title": "Salam",
        "url": "http://pakat.net",
        "webhook": "localhost/api/notification/najva/webhook/NsbFGqmiRPHJZFLXXQTugwZehxiibw"
    }
}

Update notification

PUT https://kingfisher.kamva.ir/api/{driver}/{notification_id}

Update notification.

Path Parameters

Name	Type	Description
notification_id	string	Notification's ID
driver	string	name of notification provider. possible values: najva

Request Body

Name	Type	Description
title	string	Notification title
body	string	Notification body
content	string	If you set on_click_action to open-sms, using this value as sms content.
icon	string	Notification icon url.
image	string	Notification Image url.
on_click_action	string	what happen if user clicked on the notification?
url	string	url to use as action url on clicked on the notificatino.
device_type	string	send notification to what type of devices? possible values: ios: send notification to ios device. android: send notification to the android device. web: send notification to the web device. phone: send notification to the ios and android device. all: send to all user's devices.

200

{
    "code": "J20X04",
    "message": "نوتیفیکیشن بروز شد."
}D

Delete Notification

DELETE https://kingfisher.kamva.ir/api{driver}/{notification_id}

Delete a notification.

Path Parameters

Name	Type	Description
notification _id	string	ID of notification
driver	string	name of notification provider. possible values: najva,pushe

200

{
    "code": "J20X05",
    "message": "نوتیفیکیشن حذف شد."
}

Health check

GET https://kingfisher.kamva.ir/api/lab/healthcheck

Check healthy of API

Path Parameters

Name	Type	Description
	string

200

{
    "code": "J10X00",
    "data": {
        "db": "DB connection established :)",
        "redis": "Redis connection established :)",
        "redis_second_connection": "Redis Second connection type established :)"
    }
}

Profile

Get Profile Info

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

This API returns Information of user account

Headers

Name	Type	Description
Authorization	string	auth token

200

{
    "code": "J5X00",
    "data": {
        "domains": {
            "accepted": {
                "domain": "salam.com",
                "id": "5dd94b518ad1200057b4c932",
                "status": 2,
                "status_name": "accepted",
                "user": {
                    "id": "5d97273cd6194c28f890fed4",
                    "name": "mehran prs (Check Company)"
                }
            },
            "unverified": {
                "domain": "checkme.com",
                "id": "5dd39a43f700a2004c11acc6",
                "status": 1,
                "status_name": "unverified",
                "user": {
                    "id": "5d97273cd6194c28f890fed4",
                    "name": "mehran prs (Check Company)"
                }
            }
        },
        "info": {
            "api_key": "xkeysib-db07ba0d7277c49xxxxxxxxe16eb435a7f2e677321706af7227218e3ee6c7ec4f-YV5n19SpDCOa83wq",
            "api_keys": {
                "v2": [
                    {
                        "name": "N˚2",
                        "key": "nOpxxxxxy7z"
                    }
                ],
                "v3": [
                    {
                        "name": "N˚3",
                        "key": "xkeysib-21881axxxxxcc92e04-mIrexxxx7z"
                    }
                ]
            },
            "credits": 98555,
            "ips": [
                "176.2.39.4",
                "231.43.21.7"
            ],
            "statistics": {
                "current_month_total_sent": 4566,
                "previous_month_total_sent": 7654,
                "total_sent": 987554
            }
        },
        "subscription": {
            "expiration_date": "1398-10-25",
            "plan": "test2",
            "plan_credit": 1000
        },
        "user": {
            "company_name": "Check Company",
            "email": "[e-mail]",
            "first_name": "mehran",
            "full_name": "mehran prs",
            "id": "5d97273cd6194c28f890fed4",
            "is_admin": true,
            "last_name": "prs",
            "phone": "09366579399"
        }
    }
}

Update User Info

PATCH https://kingfisher.kamva.ir/api/profile

This API updates user informations.

Headers

Name	Type	Description
Authorization	string	auth token

Request Body

Name	Type	Description
email	string	user valid email address
phone	string	user phone number
first_name	string	user first name
last_name	string	user last name
company_name	string	user company name
password	string	new password
current_password	string	current password

202 User updated successfully.

{
    "code": "J5X02"
}

Reports

[Admin Only] Sales Report

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

This API returns sales reports.

Query Parameters

Name	Type	Description
month_limit	number	number of previous month to count in reports

Headers

Name	Type	Description
Authorization	string	Admin auth token

200 Report generated successfully.

{
    "code": "J6X00",
    "coustomer_count": 7536,
    "paying_customer_count": 5891,
    "monthly_revenue_data": {
        "2019-06" : {
            "count": 562,
            "total_amount": 112400000,
            "revenue": {
                "kamva": 35732000,
                "sendinblue": 76668000
            }
        },
        // ...
        "2019-12" : {
            "count": 768,
            "total_amount": 145920000,
            "revenue": {
                "kamva": 51214200,
                "sendinblue": 94705800
            }
        },
    }
}