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

Name

Type

Description

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

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

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

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

Name

Type

Description

string

user email

password

string

user password

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

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

Name

Type

Description

Authorization

string

Auth token

{
    "code": "J1X02"
}

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

Name

Type

Description

Authorization

string

Auth token

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

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

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

Subscription

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

Name

Type

Description

Authorization

string

Auth token

Request Body

Name	Type	Description
plan_id	string	ID of selected plan

Name

Type

Description

plan_id

string

ID of selected plan

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

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

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

Name

Type

Description

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

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

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

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

Name

Type

Description

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

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

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

Name

Type

Description

receipt_id

string

ID of receipt

Headers

Name	Type	Description
Authorization	string	Auth token

Name

Type

Description

Authorization

string

Auth token

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

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

Name

Type

Description

receipt_id

string

ID of receipt to pay

Headers

Name	Type	Description
Authorization	string	Auth token

Name

Type

Description

Authorization

string

Auth token

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

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

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

Name

Type

Description

Authorization

string

auth token

{
    "code": "J5X00",
    "data": {
        "user": {
            "email": "hoshang.ahmadi@gmail.com",
            "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

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

Name

Type

Description

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

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

Name

Type

Description

month_limit

number

number of previous month to count in reports

Headers

Name	Type	Description
Authorization	string	Admin auth token

Name

Type

Description

Authorization

string

Admin auth token

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

PreviousGetting Started

Last updated 5 years ago

Authentications

Register User

Request Body

Login

Request Body

Logout

Headers

Refresh auth token

Headers

Global Authentication Responses

Authentication token is not provided

Invalid token provided

Token is expired

Token is blacklisted

Plan

List available plans

Subscription

Subscribe

Headers

Request Body

[Admin Only] Add Trial User

Headers

Request Body

[Admin Only] Add Sponsorship Account

Headers

Request Body

Receipt

Get Receipt Info

Path Parameters

Headers

Pay Receipt

Path Parameters

Headers

Profile

Get Profile Info

Headers

Update User Info

Headers

Request Body

Reports

[Admin Only] Sales Report

Query Parameters

Headers