Kingfisher 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": "توکن احراز هویت شما فاقد اعتبار است."
}

Plan

List available plans

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

List all available plans with their price and info.

200 returns array of plan objects

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

Subscription

Subscribe

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

This API creates a subscription receipt and returns a payment url 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": "J2X00",
    "data": {
        "payment_url": "https://www.zarinpal.com/pg/StartPay/<authority>/ZarinGate"
    }
}

404

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

• 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.

[Admin Only] Add Trial User

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

This API register a user as a trial 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.

[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.

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": {
        "price": 170000,         // price of the plan
		"tax": 15300,            // value added tax
		"discount": 25500,       // discount
		"total_price": 159800,   // payable amount of receipt
        "plan": "ساده"           // name of selected plan
    }
}

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.

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

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.

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": {
        "user": {
            "email": "[e-mail]",
            "phone": "09123456789",
            "first_name": "Hooshang",
            "last_name": "Ahmadi",
            "company_name": "Asan Pardakht"
        },
        // This field will not be present if user has not any sendinblue account
        "info": {
            "credits": 10356,
            "statistics": {
                "previous_month_total_sent": 13865,
                "current_month_total_sent": 4644,
                "total_sent": 32544
            },
            "ips": [ "194.133.15.75" ],
            "api_key": "<auth-key>"
        },
        // This field will not be present if user has no active subscription
        "subscription": {
            "plan": "ساده",
            "plan_credit": 15000,
            "expiration_date": "1398-06-28"
        }
    },
}

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
            }
        },
    }
}