estaheri / perfectapi
php library for communicating perfect panel websites using API for clients and AdminAPI for panel owners
Requires
- php: >=8.2
- estaheri/json: ^1.1.3
- guzzlehttp/guzzle: ^7.10
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 06:59:58 UTC
README
A small, dependency-light PHP client for Perfect Panel websites.
It talks to both APIs that every Perfect Panel installation exposes:
| API | Base URL | Used by | Class |
|---|---|---|---|
| Client API v2 | https://your-panel.com/api/v2 |
panel users (place/cancel orders, refill, services) | PerfectAPI\Api |
| Admin API v2 | https://your-panel.com/adminapi/v2 |
panel owners / staff (orders, users, payments, tickets, cancel & refill tasks) | PerfectAPI\AdminApi |
Both APIs are covered 1:1 with the official documentation, with typed filters, typed request bodies and a uniform result/response layer.
Requirements
- PHP 8.1+
- Composer
- A Perfect Panel api key (client key from your account, or an admin key created in the panel admin area)
Installation
composer require estaheri/perfectapi
Configuration
use PerfectAPI\AdminApi; use PerfectAPI\Api; // Admin API (panel owner) $admin_config = AdminApi::config( 'https://my.panel.com/adminapi/v2', // base url, no trailing slash needed 'your-admin-api-key' ); // Client API (panel user) $client_config = Api::config( 'https://my.panel.com/api/v2', 'your-client-api-key' );
config() accepts two extra optional arguments:
| Argument | Default | Description |
|---|---|---|
$timeout |
10 |
request timeout in seconds |
$verify |
true |
verify the panel ssl certificate — only disable it for panels with a self-signed certificate |
Every resource class (Order, User, Payments, Ticket, Cancel, Refill)
is instantiated with the same config array:
use PerfectAPI\AdminApi\Order; use PerfectAPI\AdminApi\User; $orders = new Order($admin_config); $users = new User($admin_config);
You can change the timeout at runtime, and measure the panel latency:
$orders->timeout(30); // set + return the new timeout $orders->timeout(); // read the current timeout $orders->ping(); // float (ms) or false
Reading a result
Every call returns a Result (PerfectAPI\AdminApi\Result or
PerfectAPI\Api\Result), so a failing transport never throws:
$result = $orders->list($filter); $result->ok(); // bool — request was sent and answered with valid json $result->status(); // ?int — http status code $result->error(); // ?string — curl/connection/timeout error message $result->response();// ?Response — parsed api response envelope $result->response(true); // ?string — raw response body
Response wraps the api envelope:
$response = $result->response(); $response->success(); // bool — the api accepted the request $response->error(); // ?string — api error message $response->error_code(); // ?int — api error code $response->data(); // object|array|string|null ('object' by default) $response->data('array');// same data as an array $response->data('json'); // same data as a json string $response->pagination(); // paginated endpoints only $response->count(); // data.count of a list response $response->items(); // data.list of a list response (array) $response->raw(); // the whole envelope
So the usual flow is:
$result = $orders->list($filter); if (!$result->ok()) die('network error: ' . $result->error()); if (!$result->response()->success()) die('api error: ' . $result->response()->error()); foreach ($result->response()->items() as $order) { echo $order->id . ' — ' . $order->status . PHP_EOL; }
Admin API
Orders
| Method | Endpoint |
|---|---|
pull(?array $service_ids = null, int $limit = 100) |
POST /orders/pull |
list(OrderList $filters) |
GET /orders |
order(int $id) / get(int $id) |
GET /orders/{id} |
update(array $orders) |
POST /orders/update |
edit_link(int $id, string $link) |
POST /orders/{id}/edit-link |
resend(int|array $ids) |
POST /orders/resend |
change_status(int|array $ids, string $status) |
POST /orders/change-status |
partial(int $id, int $remains) |
POST /orders/{id}/set-partial |
cancel(int|array $ids) — creates a cancel task |
POST /orders/request-cancel |
cancel_refund(int|array $ids, ?string $reason = null) |
POST /orders/cancel |
List orders:
use PerfectAPI\AdminApi\Filters; $filter = Filters::Order() ->order_status(Filters::STATUS_Processing) ->mode(Filters::MODE_Manual) ->created_from(strtotime('-7 days')) ->include([Filters::INCLUDE_UserData, Filters::INCLUDE_LastUpdate]) ->sort(Filters::ORDER_SORT_DateDesc) ->limit(100) ->offset(0); $result = (new Order($admin_config))->list($filter);
Filters::Order() matches the api query parameters: ids, external_order_ids,
created_from, created_to, order_status, mode, service_ids,
creation_type, user, provider, ip_address, link, offset, limit,
sort and include. Empty filters are never sent. Any other filter can be
appended with ->add('key', $value).
Update one or multiple orders (status, start count, remains, cancel reason):
use PerfectAPI\AdminApi\Setters; $result = $orders->update([ Setters::Order()->id(12)->status(Filters::STATUS_Processing)->start_count(1200), Setters::Order()->id(15)->status(Filters::STATUS_Partial)->remains(500), Setters::Order()->id(18)->status(Filters::STATUS_Canceled)->cancel_reason('Incorrect link'), ]);
Pull manual orders and move them to processing:
$result = $orders->pull([1061, 1062], 50); foreach ($result->response()->items() as $order) { // process the manual order ... }
Users
| Method | Endpoint |
|---|---|
list(UserList $filters) |
GET /users |
get(int $id) |
GET /users?ids={id} |
add(AddUser|array $user) |
POST /users/add |
edit(int $id, EditUser|array $user) |
POST /users/{id}/edit |
use PerfectAPI\AdminApi\Filters; use PerfectAPI\AdminApi\Setters; use PerfectAPI\AdminApi\User; $users = new User($admin_config); $filter = Filters::User() ->status(Filters::USER_Active) ->limit(50); $list = $users->list($filter); $created = $users->add( Setters::User() ->username('john') ->email('john@mail.com') ->password('12qw34er5ty') ->first_name('John') ->allowed_methods(Setters\AddUser::METHODS_All) // 'all', 'none', 'new_users' or 'custom' ); // allow only payment methods 50 and 51 $created = $users->add( Setters::User() ->username('jane') ->email('jane@mail.com') ->password('12qw34er5ty') ->custom([50, 51]) );
Edit a user — unset fields are not sent, null clears a stored value:
$users->edit(345, Setters::EditUser() ->email('new@mail.com') ->phone(null) // clear the phone ->allow_methods([50, 51]) ->disallow_methods([55]) ->hidden_services(Setters\EditUser::HIDDEN_Allowed)); // 'allowed' | 'not_allowed'
Payments
| Method | Endpoint |
|---|---|
list(PaymentList $filters) |
GET /payments |
add(AddPayment|array $payment) |
POST /payments/add |
use PerfectAPI\AdminApi\Filters; use PerfectAPI\AdminApi\Payments; use PerfectAPI\AdminApi\Setters\AddPayment; $payments = new Payments($admin_config); $list = $payments->list( Filters::Payment() ->payment_status(Filters::PAYMENT_Completed) ->sort(Filters::PAYMENT_SORT_CreatedAtDesc) ->limit(100) ); // add a payment by user id, username or email $payments->add(AddPayment::by_id(42, 12, 'Perfect Money USD', 'added via admin api')); $payments->add(AddPayment::by_username('john', 12, 'Perfect Money USD')); $payments->add(AddPayment::by_email('john@mail.com', 12.5, 'Perfect Money USD', 'bonus', true));
Tickets
| Method | Endpoint |
|---|---|
list(TicketList $filters) |
GET /tickets |
get(int $id) |
GET /tickets/{id} |
add(AddTicket|array $ticket) |
POST /tickets/add |
reply(int $id, string $staff_name, string $message) |
POST /tickets/{id}/reply |
use PerfectAPI\AdminApi\Filters; use PerfectAPI\AdminApi\Setters\AddTicket; use PerfectAPI\AdminApi\Ticket; $tickets = new Ticket($admin_config); $list = $tickets->list( Filters::Ticket() ->status(Filters::TICKET_Pending) ->is_read(false) ->limit(50) ); $ticket = $tickets->get(255); $tickets->add(AddTicket::by_username('john', 'Order problem', 'My order is stuck.', 'admin')); $tickets->add(AddTicket::by_email('john@mail.com', 'Order problem', 'My order is stuck.')); $tickets->reply(255, 'admin', 'We are checking your order.');
Cancel tasks
| Method | Endpoint |
|---|---|
pull(?array $service_ids = null, int $limit = 100) |
POST /cancel/pull |
reject(RejectCancel|int|array $ids) |
POST /cancel/reject |
use PerfectAPI\AdminApi\Cancel; use PerfectAPI\AdminApi\Setters; use PerfectAPI\AdminApi\Setters\RejectCancel; $cancel = new Cancel($admin_config); $pulled = $cancel->pull([84], 100); $cancel->reject(Setters::RejectCancel([12, 33, 46])); // or $cancel->reject([12, 33, 46]);
Refill tasks
| Method | Endpoint |
|---|---|
pull(?array $service_ids = null, int $limit = 100) |
POST /refill/pull |
change_status(array $refill_tasks) |
POST /refill/change-status |
use PerfectAPI\AdminApi\Refill; use PerfectAPI\AdminApi\Setters; use PerfectAPI\AdminApi\Setters\RefillTask; $refill = new Refill($admin_config); $pulled = $refill->pull(null, 100); $refill->change_status([ Setters::RefillTask()->id(345)->status(RefillTask::STATUS_Completed), Setters::RefillTask()->id(346)->status(RefillTask::STATUS_Rejected), ]);
Raw calls & concurrency
Any endpoint (including ones added to the panel later) is reachable directly:
$result = $orders->call('POST', 'orders/pull', ['limit' => 100]); $result = $orders->call('GET', 'orders', ['ids' => '12,33,46']);
Multiple admin calls at once (keep in mind the 5 requests per second limit
of the admin api, otherwise the panel answers 429 Too Many Requests):
$results = $orders->concurrent([ ['GET', 'orders', ['limit' => 10]], ['GET', 'users', ['limit' => 10]], ['GET', 'payments', ['limit' => 10]], ]); foreach ($results as $key => $result) { // $key is exactly the same key used in the $calls array }
Client API
The client api is action based, every request is a POST to /api/v2 with an
action parameter.
Orders
use PerfectAPI\Api\Filters; use PerfectAPI\Api\Order; use PerfectAPI\Api\Setters\AddOrder; $order = new Order($client_config); // add $result = $order->add(AddOrder::default(1061, 'https://instagram.com/p/xxx', 1000)); // drip feed $result = $order->add(AddOrder::default(1061, 'https://instagram.com/p/xxx', 100, 5, 30)); // custom comments $result = $order->add(AddOrder::custom_comments(10, 'https://instagram.com/p/xxx', ['nice', 'great'])); // subscription $result = $order->add(AddOrder::subscription(20, 'username', 10, 20, 5)); // status of one or multiple orders $status = $order->status(Filters::Status(1234)); $status = $order->status(Filters::Status([1234, 5678])); // cancel $order->cancel(Filters::Cancel(1234)); $order->cancel(Filters::Cancel([1234, 5678]));
Services
use PerfectAPI\Api\Service; $service = new Service($client_config); $all = $service->list(); $one = $service->get(1061); $many = $service->get([1061, 1062]);
Refills
use PerfectAPI\Api\Filters; use PerfectAPI\Api\Refill; $refill = new Refill($client_config); $refill->add(Filters::Refill(1234)); $refill->add([1234, 5678]); $refill->status(Filters::Refill([111, 222]));
Raw calls
$result = $order->call('add', [ 'service' => 1061, 'link' => 'https://instagram.com/p/xxx', 'quantity' => 1000, ]); $results = $order->concurrent([ ['status', ['order' => 1234]], ['status', ['order' => 5678]], ]);
Constants
PerfectAPI\AdminApi\Filters:
| Group | Constants |
|---|---|
| order status | STATUS_Pending, STATUS_InProgress, STATUS_Processing, STATUS_Completed, STATUS_Partial, STATUS_Canceled, STATUS_Rejected, STATUS_Fail, STATUS_Error |
| order mode | MODE_Manual, MODE_Auto |
| creation type | CREATION_NewOrderForm, CREATION_Api, CREATION_MassOrderForm, CREATION_Subscription, CREATION_DripFeed, CREATION_Refiller |
| order sort | ORDER_SORT_DateDesc, ORDER_SORT_DateAsc |
| order include | INCLUDE_UserData, INCLUDE_LastUpdate, INCLUDE_ProviderResponse |
| payment status | PAYMENT_Waiting, PAYMENT_Completed, PAYMENT_Pending, PAYMENT_Fail, PAYMENT_Expired, PAYMENT_Hold, PAYMENT_Underpaid |
| payment sort | PAYMENT_SORT_CreatedAtDesc, PAYMENT_SORT_CreatedAtAsc, PAYMENT_SORT_UpdatedAtDesc, PAYMENT_SORT_UpdatedAtAsc |
| user status | USER_Active, USER_Suspended, USER_Unconfirmed |
| user sort | USER_SORT_CreatedAtDesc, USER_SORT_CreatedAtAsc |
| ticket status | TICKET_Pending, TICKET_Answered, TICKET_Closed, TICKET_Locked, TICKET_Welcome |
PerfectAPI\Api\Filters: STATUS_Pending, STATUS_Active, STATUS_InProgress,
STATUS_Processing, STATUS_Completed, STATUS_Partial, STATUS_Cancelled,
STATUS_Awaiting, STATUS_Error, STATUS_Fail, STATUS_Rejected.
Error handling
try { $result = $orders->update([$update]); } catch (Exception $e) { // invalid local input (missing id, too many items, ...) } if (!$result->ok()) { // transport problem: timeout, dns, tls, non-json body echo $result->error(); } elseif (!$result->response()->success()) { // api problem: validation error, missing access, not found echo $result->response()->error() . ' (' . $result->response()->error_code() . ')'; } else { $data = $result->response()->data(); }
Local validation is done before sending a request whenever the api documents a
required field, so you get an immediate Exception instead of a round trip.
Example
See test.php for a runnable example:
PERFECT_PANEL_URL="https://my.panel.com/adminapi/v2" \ PERFECT_PANEL_ADMIN_KEY="your-key" \ php test.php
License
MIT © Esmaeil Taheri