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

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

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

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

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

Request Body

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

Request Body

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

Request Body

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

Headers

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

Headers

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

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

Request Body

{
    "code": "J5X02"
}

Reports

[Admin Only] Sales Report

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

This API returns sales reports.

Query Parameters

Headers

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