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.
post
https://kingfisher.kamva.ir/api
/auth/register
Register User
post
https://kingfisher.kamva.ir/api
/auth/login
Login
delete
https://kingfisher.kamva.ir/api
/auth/logout
Logout
post
https://kingfisher.kamva.ir/api
/auth/refresh
Refresh 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": "توکن احراز هویت شما فاقد اعتبار است."
}
post
https://kingfisher.kamva.ir/api
/auth/forgot-password
Forgot Password
post
https://kingfisher.kamva.ir/api
/auth/reset-password/:user_id
Reset password
get
https://kingfisher.kamva.ir/api
/auth/SSO
SSO Link
Plan
get
https://kingfisher.kamva.ir/api
/plan
List available plans
get
https://kingfisher.kamva.ir/api
/plan/all
(Admin only) List available plans (Include custom plans)
post
https://kingfisher.kamva.ir/api
/plan
Create new plan(Admin)
put
https://kingfisher.kamva.ir/api
/plan/:receipt_id
update plan (Admin)
Another response for not found plan:
{
    "code": "J3E00",
    "message": "تعرفه\u200cای با مشخصات ارسال شده پیدا نشد."
}
delete
https://kingfisher.kamva.ir/api
/plan/:receipt_id
Delete plan (Admin)
Subscription
post
https://kingfisher.kamva.ir/api
/subscription/subscribe
Subscribe
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.
post
https://kingfisher.kamva.ir/api
/subscription/update/:receipt_id
update subscription receipt 
get
https://kingfisher.kamva.ir/api
/subscription/pay/:receipt_id
Get payment link to subscription receipt
All 4xx  error responses in /subscription/subscribe API may return here also.
post
https://kingfisher.kamva.ir/api
/verify-failed
Verify Failed payment
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": "اشتراک شما فعال می باشد."
}
post
https://kingfisher.kamva.ir/api
/subscription/manual
[Admin Only] subscribe user manually
In addition to the written responses, you need to also check internal error responses.
post
https://kingfisher.kamva.ir/api
/subscription/extend
(Admin only) Extend user's subscription manually
Some other 403 Forbidden responses:
{
    "code":"J2E22",
    "message":"کاربر ابتدا باید اشتراک بگیرد.(تا به حال اشتراکی نداشته است)"
}
{
    "code":"J2E23",
    "message":"بیشتر از ۱۰ روز تا اتمام اشتراک فعلی زمان باقی مانده است."
}
{
    "code":"J2E26",
    "message":"رسید تمدید دستی قبلا ایجاد شده است."
}
{
    "code":"J2E25",
    "message":"کاربر مورد نظر قبلا رسیدی را جهت تمدید، پرداخت کرده است."
}
post
https://kingfisher.kamva.ir/api
/subscription/history/extend
(Admin Only) Extend user's extension history
Some other 403 Forbidden responses:
{
    "code":"J2E22",
    "message":"کاربر ابتدا باید اشتراک بگیرد.(تا به حال اشتراکی نداشته است)"
}
{
    "code":"J2E29",
    "message":"تاریخ تمدید باید در گذشته باشد."
}
post
https://kingfisher.kamva.ir/api
/subscription/trial
[Admin Only] Add Trial User (Deprecated)
If a 200 OK response returns with an empty auth_key field, it means registering user in sendinblue and it has queued for retrying.
post
https://kingfisher.kamva.ir/api
/v1/subscription/trial-existed-user
Give Trial subscription to user (Admin Only)
post
https://kingfisher.kamva.ir/api
/subscription/sponsorship
[Admin Only] Add Sponsorship Account
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
post
https://kingfisher.kamva.ir/api
/credit/add
(Admin Only) Add credit to user 
Low Credit Reminder Settings
post
https://kingfisher.kamva.ir/api
/credit/threshold
Add low credit threshold settings (Admin Only)
put
https://kingfisher.kamva.ir/api
/credit/threshold/{threshold_settings_id}
Update Low Credit Threshold Settings
delete
https://kingfisher.kamva.ir/api
/credit/threshold/{threshold_settings_id}
Delete low credit threshold settings (Admin Only)
Receipt
get
https://kingfisher.kamva.ir/api
/receipt/{receipt_id}
Get Receipt Info
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
https://kingfisher.kamva.ir/api
/receipt/unpaid
Get unpaid receipt 
post
https://kingfisher.kamva.ir/api
/receipt/:receipt_id/update
Update extension receipt  (Upgrade receipt)
Other Situations:
If plan id be invalid (404 : Not Found)
{
    "code":"J3E00",
    "message":"تعرفه‌ای با مشخصات ارسال شده پیدا نشد."
}
get
https://kingfisher.kamva.ir/api
/receipt/{receipt_id}/pay
Pay Receipt
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
get
https://kingfisher.kamva.ir/api
/discount/all
List all discounts (Admin only)
post
https://kingfisher.kamva.ir/api
/discount
Create New Discount (Admin only)
put
https://kingfisher.kamva.ir/api
/discount/:descount_id
Edit discount (Admin only)
post
https://kingfisher.kamva.ir/api
/discount/:discount_id/expire
Expire Discount (Admin only)
IP
get
https://kingfisher.kamva.ir/api
/ip
List IPs (Admin Only)
post
https://kingfisher.kamva.ir/api
/ip/associate
Associate IP to user
post
https://kingfisher.kamva.ir/api
/ip/dissociate
Dissociate IP (Admin Only)
Sender
post
https://kingfisher.kamva.ir/api
/sender
Create Sender (Admin Only)
Info
get
https://kingfisher.kamva.ir/api
/info/malicious-users
Get Malicious users list (Admin Only)
Notification
get
https://kingfisher.kamva.ir/api
/notification/{driver}/settings
Get Notification settings
post
https://kingfisher.kamva.ir/api
/notification/{driver}/settings
Set Notification Settings
get
https://kingfisher.kamva.ir/api
/notification/{driver}/settings
post
https://kingfisher.kamva.ir/api
/{driver}/contact/{server_key:string}/
Insert (update if exists) Contact
get
https://kingfisher.kamva.ir/api
/{driver}
Get notification list
post
https://kingfisher.kamva.ir/api
/{driver}
Create Notification
get
https://kingfisher.kamva.ir/api
/{driver}/{notification_id}
Get Notification Info
put
https://kingfisher.kamva.ir/api
/{driver}/{notification_id}
Update notification 
delete
https://kingfisher.kamva.ir/api
{driver}/{notification_id}
Delete Notification
get
https://kingfisher.kamva.ir/api
/lab/healthcheck
Health check
Profile
get
https://kingfisher.kamva.ir/api
/profile
Get Profile Info
patch
https://kingfisher.kamva.ir/api
/profile
Update User Info
Reports
get
https://kingfisher.kamva.ir/api
/report
[Admin Only] Sales Report
​
​
​
​
​
​
​
​
​
​
​
Pakat Email Service API
RESTFUL Tracker
Last modified 3yr ago