==============================================================================
RABISU RESELLER API — COMPLETE DOCUMENTATION
==============================================================================
This file contains the complete Rabisu Reseller API documentation in a single plain-text file.
You can upload it to an AI assistant (ChatGPT, Claude, etc.) and ask your integration questions.
Web version: https://www.rabisu.com/docs/reseller-api/getting-started
API version: 1.0.0
Generated: 2026-10-06
Production base URL: https://api.rabisu.com/api/v1
TABLE OF CONTENTS
PART 1 — GUIDES
- Rabisu Reseller API — Overview
- Authentication
- Idempotency (Safe Retries)
- Rate Limiting
- Error Codes
- Order Lifecycle
- Webhooks
PART 2 — API REFERENCE (ENDPOINTS) — 36 endpoints
[System]
GET /health — Health check (no auth required)
GET /openapi.yaml — Raw YAML content of the OpenAPI 3.0 spec
[Auth]
GET /auth/me — Returns authenticated key metadata
GET /auth/balance — Reseller WHMCS credit balance (APCu 60s cache)
GET /auth/balance/movements — Reseller balance movements (live WHMCS tblcredit)
[Products]
GET /products — Product catalog list (+ stock-active flag)
GET /products/{id} — Single product detail
[Orders]
GET /orders — The reseller's order list (provision records)
POST /orders — Create a new order + attempt AUTOMATIC payment from balance
GET /orders/{id} — Single order detail (reseller isolation enforced)
POST /orders/{id}/settle — Settle a pending payment from credit (InvoicePaid)
[Services]
GET /services — Reseller's services — bulk list (cursor or page + search)
GET /services/{id} — VPS service detail (WHMCS + Virtualizor combined)
DELETE /services/{id} — Terminate the service via the WHMCS module hook (asynchronous)
GET /services/{id}/status — Real-time VPS metrics (CPU/RAM/disk/net)
GET /services/{id}/credentials — Access details (username/password/ip/hostname/panel_url)
GET /services/{id}/os-templates — OS templates allowed for rebuild on this VPS (service-specific filter)
POST /services/{id}/power/{action} — VPS power operation (start/stop/restart/poweroff)
POST /services/{id}/rebuild — VPS OS reinstall (asynchronous, 202 Accepted)
POST /services/{id}/vnc-token — Short-lived (60s) NoVNC connection info
POST /services/{id}/password — Change the VPS root password
POST /services/{id}/suspend — Suspend the service via the WHMCS module hook
POST /services/{id}/unsuspend — Unsuspend the service via the WHMCS module hook
POST /services/{id}/upgrade — Upgrade the service's config options
[Webhooks]
GET /webhooks — List the reseller's webhook registrations
POST /webhooks — Register a new webhook endpoint
GET /webhooks/{id} — Single webhook detail
PATCH /webhooks/{id} — Partially update a webhook (reactivate / event_types / description)
DELETE /webhooks/{id} — Delete a webhook (soft delete)
[ModuleReleases]
GET /module-releases/{module}/latest — Latest valid release of the module
GET /module-releases/{module}/{version}/download — Download the signed module zip
[Admin]
GET /admin/keys — List a reseller's active API keys (NO secret)
POST /admin/keys — Generate a new API key for a reseller (secret returned ONCE)
POST /admin/keys/{id}/webhook-secret — Issue a webhook secret to a legacy key (if missing, one time)
POST /admin/keys/{id}/rotate — Rotate the reseller API key secret (secret returned ONCE)
POST /admin/keys/{id}/revoke — Revoke the reseller API key (soft delete)
PART 3 — DATA SCHEMAS (components/schemas)
==============================================================================
PART 1 — GUIDES
==============================================================================
# Rabisu Reseller API — Overview
The Rabisu Reseller API is a REST API that lets resellers sell Rabisu Virtualizor
VPS products through their own WHMCS installation. It provides order creation,
service lifecycle management (suspend, terminate, rebuild), resource upgrades,
credit balance queries, and webhook notifications.
:::tip[Complete documentation in one file (for AI)]
Instead of browsing page by page, you can download the entire API documentation
(guides, every endpoint, parameters, responses, examples and data schemas) as a
single text file. Upload it to an AI assistant such as ChatGPT or Claude and ask
your integration questions directly.
📄 Download the English documentation (.txt) · Türkçe sürüm (.txt)
:::
## Basics
| Property | Value |
|---|---|
| **Production base URL** | `https://api.rabisu.com/api/v1` |
| **Protocol** | HTTPS required (TLS) |
| **Authentication** | HTTP Basic Auth (API Key + Secret) |
| **Content type** | `application/json` |
| **Version** | All paths under `/api/v1` |
## Request Format
All request bodies must be JSON. Authentication is sent on every request using the
HTTP Basic Auth header (see Authentication).
```bash
curl -u "rsk_live_xxx:rsks_yyy" \
https://api.rabisu.com/api/v1/auth/me
```
## Standard Response Envelope
Every response uses the same envelope. Success:
```json
{
"success": true,
"data": {
"reseller_id": 42,
"name": "Example Reseller"
},
"meta": {
"trace_id": "1f9a...uuid",
"timestamp": "2026-07-22T12:00:00Z"
}
}
```
Error:
```json
{
"success": false,
"error": {
"code": "insufficient_credit",
"message": "Credit balance is insufficient.",
"details": { "required": "10.00", "available": "3.50" }
},
"meta": {
"trace_id": "1f9a...uuid",
"timestamp": "2026-07-22T12:00:00Z"
}
}
```
- **`success`**: Result of the operation (`true` / `false`).
- **`data`**: Present only in successful responses.
- **`error`**: Present only in error responses — `code` (English slug),
`message` (human-readable), and optional `details`.
- **`meta.trace_id`**: Unique trace identifier per request. Include it when
contacting support.
- **`meta.timestamp`**: ISO 8601 UTC timestamp.
## Trace ID
Every response returns an `X-Request-ID` header and a `meta.trace_id` field. If you
send your own `X-Request-ID` header, the system preserves it; otherwise a UUID is
generated automatically. Keep this identifier in your logs for troubleshooting.
## Next Steps
- Authentication — using API Key/Secret with HTTP Basic Auth
- Idempotency — safe request retries
- Rate Limiting — quota headers
- Error Codes — all error slugs
- Order Lifecycle — POST /orders and the provisioning flow
- Webhooks — event notifications and signature verification
------------------------------------------------------------------------------
# Authentication
The Rabisu Reseller API uses **HTTP Basic Authentication**. Each request sends an
API Key (username) and an API Secret (password). No JWT or session is used — the
API is fully stateless.
## Credentials
When you become a reseller you receive two values:
| Field | Example | Role |
|---|---|---|
| **API Key** | `rsk_live_ab55mtkb7azdr1pyh5xs56whcab4pjv9` | Username |
| **API Secret** | `rsks_zfe4yk848aa737k3s1q1h3mmnd963jk6651fcc3` | Password |
> **Important:** The API Secret is shown **only once**. Store it securely. If you
> lose it, you must rotate the secret or create a new key.
## Request Example
The Basic Auth header is `Authorization: Basic base64(api_key:api_secret)`. Most
HTTP clients build it for you:
```bash
curl -u "rsk_live_ab55mtkb7azdr1pyh5xs56whcab4pjv9:rsks_zfe4yk848..." \
https://api.rabisu.com/api/v1/auth/me
```
PHP (cURL) example:
```php
$ch = curl_init('https://api.rabisu.com/api/v1/auth/me');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ':' . $apiSecret);
$response = curl_exec($ch);
```
## Failed Authentication
If credentials are missing or invalid, **401 Unauthorized** is returned. For
security, all failure cases return the same generic message (which field is wrong
is never leaked):
```json
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Authentication failed."
},
"meta": { "trace_id": "...", "timestamp": "..." }
}
```
Per RFC 7235, 401 responses also include:
```
WWW-Authenticate: Basic realm="Rabisu Reseller API", charset="UTF-8"
```
## Security Notes
- **Never** use the API Secret in client-side (browser) code. The API is designed
for server-to-server calls only.
- **Never** log the `Authorization` header in plaintext.
- If a secret is leaked, rotate or revoke the key immediately.
- If an IP whitelist is configured, you can only access from allowed IPs.
## Primary Endpoint: `GET /auth/me`
The simplest endpoint to verify your credentials. It returns the key owner, its
permissions, and the `auto_apply_credit` flag:
```json
{
"success": true,
"data": {
"reseller_id": 42,
"name": "Example Reseller",
"permissions": ["*"],
"auto_apply_credit": true,
"last_used_ip": "203.0.113.5"
},
"meta": { "trace_id": "...", "timestamp": "..." }
}
```
------------------------------------------------------------------------------
# Idempotency (Safe Retries)
Network errors or timeouts may force you to resend a request. Idempotency prevents
the same request from being accidentally processed twice (e.g. duplicate orders,
double charges).
## How It Works
Add an `Idempotency-Key` header to mutating requests (`POST`, `DELETE`). It must be
a unique **UUID v4** value:
```bash
curl -X POST https://api.rabisu.com/api/v1/orders \
-u "rsk_live_xxx:rsks_yyy" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f" \
-d '{ "product_id": 101, "period": "monthly" }'
```
Behavior:
| Case | Result |
|---|---|
| **No key** | Processed normally (no idempotency protection). |
| **Key present, same body** | The first response within 24h is returned from cache — the operation is not re-executed. |
| **Key present, different body** | `422 idempotency_key_reuse` — the same key cannot be used with different content. |
## Endpoints Where It Is Required
Some financial / destructive endpoints **require** `Idempotency-Key`; if missing,
`400 missing_idempotency_key` is returned:
- `POST /orders` — create an order
- `POST /services/{id}/upgrade` — resource upgrade (difference invoice)
- `POST /services/{id}/rebuild` — OS reinstall
- `POST /services/{id}/power/{action}` — power actions
- `DELETE /services/{id}` — service termination (disk is wiped)
## Recommendations
- Generate a **stable** key per logical operation. For example, when retrying the
"monthly upgrade for service 500" request, use the **same** key to avoid double
billing.
- Generate a **new** key for a new operation.
- Keys are stored for 24 hours; after that, the same key can be reused.
------------------------------------------------------------------------------
# Rate Limiting
To protect the API from overload, the number of requests is limited per minute.
The limit is computed using a sliding window.
Every API key has its **own** limit — there is no shared/global limit. Limits are
applied per endpoint group (bucket); usage in one bucket does not affect the others.
## Quotas
| Bucket | Default limit | Scope |
|---|---|---|
| `default` | 60 requests / minute | Orders, products, balance, webhooks, VNC, credentials, lifecycle (suspend/unsuspend/terminate) |
| `services_read` | 150 requests / minute | `GET /services`, `GET /services/{id}` |
| `services_status` | 300 requests / minute | `GET /services/{id}/status` (high-frequency polling) |
| `services_changes` | 120 requests / minute | Change endpoints (power, rebuild, password, upgrade) |
Per-bucket increases for large resellers are configured by Rabisu. You can read your
key's **effective** limits from the `rate_limits` field of the `GET /auth/me` response:
```json
"rate_limits": {
"default": 60,
"services_read": 150,
"services_status": 300,
"services_changes": 120
}
```
## Response Headers
Every response returns the current quota state:
| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Total quota per minute |
| `X-RateLimit-Remaining` | Remaining requests |
| `X-RateLimit-Reset` | Unix timestamp when the quota resets |
## Quota Exceeded (429)
When the quota is exceeded, **429 Too Many Requests** is returned, and the
`Retry-After` header tells you how many seconds to wait:
```
HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1785000000
```
```json
{
"success": false,
"error": {
"code": "rate_limited",
"message": "Request limit exceeded. Please try again later."
},
"meta": { "trace_id": "...", "timestamp": "..." }
}
```
## Recommendations
- On `429`, wait for the `Retry-After` duration and retry with **exponential
backoff**.
- Instead of continuously polling service status, use Webhooks
where possible — notifications arrive instantly and consume no quota.
- For bulk operations, spread requests over time; do not send hundreds of requests
at once.
------------------------------------------------------------------------------
# Error Codes
All errors are returned in the standard envelope with `error.code` (an English
slug) and `error.message` (human-readable). The code (slug) is stable for
programmatic checks; the message text may change.
```json
{
"success": false,
"error": {
"code": "validation_error",
"message": "Input validation failed.",
"details": { "field": "period" }
},
"meta": { "trace_id": "...", "timestamp": "..." }
}
```
## Generic HTTP Errors
| HTTP | `code` | Meaning |
|---|---|---|
| 400 | `invalid_input` | Invalid or missing input |
| 400 | `missing_idempotency_key` | Required `Idempotency-Key` header is missing |
| 401 | `unauthorized` | Authentication failed (missing/invalid key or secret) |
| 403 | `forbidden` | Not authorized (e.g. you do not own the service) |
| 404 | `not_found` | Resource not found |
| 405 | `method_not_allowed` | HTTP method not supported on this endpoint |
| 409 | `conflict` | Conflicting request (e.g. downgrade attempt) |
| 422 | `validation_error` | Business rule validation failed |
| 429 | `rate_limited` | Request limit exceeded (see Rate Limiting) |
| 500 | `internal_error` | Unexpected server-side error |
## Domain Errors
| HTTP | `code` | Meaning |
|---|---|---|
| 402/422 | `insufficient_credit` | Credit balance insufficient for the operation |
| 422 | `idempotency_key_reuse` | Same `Idempotency-Key` used with a different body |
| 422 | `location_locked` | Location cannot be changed during an upgrade |
| 404 | `webhook_not_found` | Webhook endpoint record not found |
| 409 | `webhook_limit_exceeded` | Maximum active webhooks per reseller exceeded |
## How To Handle
- **Always check `error.code`** programmatically, not the message text.
- Retrying makes sense for `5xx` and `429`; do not retry `4xx` errors (except 429)
without fixing the request.
- When contacting support, share the `meta.trace_id` value — it lets us find the
related request in server logs.
------------------------------------------------------------------------------
# Order Lifecycle
The flow from creating a VPS order to the service becoming active is asynchronous:
the order is created instantly, while the actual VPS provisioning completes in the
background.
## 1. Create an Order — `POST /orders`
`Idempotency-Key` is **required** (duplicate-order protection).
```bash
curl -X POST https://api.rabisu.com/api/v1/orders \
-u "rsk_live_xxx:rsks_yyy" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f" \
-d '{
"product_id": 101,
"period": "monthly",
"config_options": { "12": 3, "15": 1 },
"extra": { "domain": "vps01.customer.com" }
}'
```
The response (202 Accepted) returns a **provision record**. The `id` field is your
reseller-side correlation key (store it in your local record):
```json
{
"success": true,
"data": {
"id": 5001,
"status": "pending_provision",
"order_id": 88123,
"service_id": null,
"payment_applied": true
},
"meta": { "trace_id": "...", "timestamp": "..." }
}
```
## 2. Applying Credit (auto_apply_credit)
An invoice is generated when the order is created. Depending on your
`auto_apply_credit` flag:
- **On (default):** The invoice is automatically paid from your reseller credit. If
you have enough credit, provisioning is queued (`pending_provision`).
- **Off:** No credit is applied; the order stays `pending_payment`. You settle it
manually later (see step 4). This gives you a pre-provisioning review window
(fraud/hostname checks, etc.).
If credit is insufficient, an `insufficient_credit` notice is returned and the order
waits in `pending_payment`.
## 3. Provisioning Status — `GET /orders/{id}`
Once the VPS is provisioned, a `service_id` is assigned and the status becomes
`active`. Poll the status:
```bash
curl -u "rsk_live_xxx:rsks_yyy" \
https://api.rabisu.com/api/v1/orders/5001
```
Provisioning states:
| Status | Meaning |
|---|---|
| `pending_payment` | Awaiting payment (credit not applied) |
| `pending_provision` | Paid, VPS provisioning queued |
| `active` | VPS provisioned, `service_id` assigned |
| `failed` | Provisioning failed |
> **Tip:** Instead of continuous polling, use Webhooks — the
> `service.created` event is delivered instantly when the VPS is ready.
## 4. Settling a Pending Payment — `POST /orders/{id}/settle`
If the order is `pending_payment` (credit was insufficient or auto-apply was off),
trigger payment after topping up your balance:
```bash
curl -X POST https://api.rabisu.com/api/v1/orders/5001/settle \
-u "rsk_live_xxx:rsks_yyy"
```
This endpoint is naturally idempotent: an already-paid order returns a no-op with
`already_applied`. After a successful settle, provisioning is queued.
## 5. Managing the Service
Once the service is `active`, you can use the service endpoints:
- `GET /services/{id}` — summary (IP, hostname, status)
- `GET /services/{id}/status` — live CPU/RAM/disk
- `POST /services/{id}/power/{action}` — start/stop/restart/poweroff
- `POST /services/{id}/rebuild` — OS reinstall
- `POST /services/{id}/upgrade` — resource upgrade (prorated difference invoice)
- `POST /services/{id}/suspend` · `/unsuspend` — suspend / unsuspend
- `DELETE /services/{id}` — terminate (disk wiped, `Idempotency-Key` required)
See the OpenAPI reference for all field details.
------------------------------------------------------------------------------
# Webhooks
Webhooks let you receive events instantly instead of continuously polling your
server. When an event occurs, Rabisu sends a signed `POST` request to your
registered URL.
## 1. Register an Endpoint — `POST /webhooks`
```bash
curl -X POST https://api.rabisu.com/api/v1/webhooks \
-u "rsk_live_xxx:rsks_yyy" \
-H "Content-Type: application/json" \
-d '{
"url": "https://reseller.com/modules/addons/rabisu/webhook.php",
"event_types": ["service.*", "credit.added"],
"description": "Production webhook"
}'
```
The HMAC **secret is returned only once** — store it securely:
```json
{
"success": true,
"data": {
"id": 12,
"url": "https://reseller.com/.../webhook.php",
"event_types": ["service.*", "credit.added"],
"secret": "whsec_...ONE_TIME...",
"is_active": true
},
"meta": { "trace_id": "...", "timestamp": "..." }
}
```
### URL Rules (SSRF Protection)
- `https://` is required.
- The URL may not contain `user:pass@`.
- All resolved DNS IPs must be public (private/internal IPs are rejected).
## 2. Subscription Patterns
The `event_types` array supports these forms:
| Pattern | Meaning |
|---|---|
| `*` | All events (catch-all) |
| `service.*` | Namespace wildcard — all events starting with `service` |
| `service.created` | Exact event name |
Valid namespaces: `service`, `product`, `credit`. Sending an invalid pattern makes
the registration fail with `422` (a clear error instead of silently "receiving no
events").
## 3. Event Catalog
| Event | When | Payload fields (summary) |
|---|---|---|
| `service.created` | VPS provisioning completed (active) | `provision_id`, `service_id`, `order_id`, `product_id`, `status` |
| `service.suspended` | Service suspended | `service_id`, `reason` |
| `service.unsuspended` | Suspension lifted | `service_id` |
| `service.terminated` | Service terminated | `service_id` |
| `product.price_changed` | Product price changed (notification) | `product_id` |
| `product.stock_changed` | Product stock status changed | `product_id`, `stock_active` |
| `product.disabled` | Product closed for sale | `product_id` |
| `credit.added` | Reseller credit added (refund/manual) | `reseller_id`, `amount`, `currency`, `reason`, `new_balance` |
> **Note:** `product.*` events carry a **notification** only. Fetch the current data
> with `GET /products/{id}` (hybrid notification + pull).
Every payload includes a `schema_version` field at its root (currently `1`).
## 4. Signature Verification (CRITICAL)
Every delivery includes two signature headers:
| Header | Content | Usage |
|---|---|---|
| `X-Rabisu-Signature-V2` | `t=,v1=` — `HMAC-SHA256(secret, "{t}.{X-Rabisu-Event-Type}.{raw body}")` | **Recommended.** Protects against replay and event-type swapping |
| `X-Rabisu-Signature` | `sha256=` — HMAC-SHA256 of the raw body only | For legacy receivers. **No** replay protection; do not use in new integrations |
The receiver must verify that `|now - t| <= 300` seconds and check the signed
event type (`X-Rabisu-Event-Type`).
Verification (PHP, V2):
```php
$raw = file_get_contents('php://input');
$eventType = $_SERVER['HTTP_X_RABISU_EVENT_TYPE'] ?? '';
$header = $_SERVER['HTTP_X_RABISU_SIGNATURE_V2'] ?? '';
parse_str(str_replace(',', '&', $header), $parts); // t=..., v1=...
$t = (int) ($parts['t'] ?? 0);
$v1 = (string) ($parts['v1'] ?? '');
if (abs(time() - $t) > 300) {
http_response_code(401); // Outside the time window (replay)
exit;
}
$expected = hash_hmac('sha256', $t . '.' . $eventType . '.' . $raw, $webhookSecret);
if (!hash_equals($expected, $v1)) {
http_response_code(401); // Invalid signature
exit;
}
// Safe: the payload can be processed
$payload = json_decode($raw, true);
```
- **Always** verify the signature — otherwise you accept forged requests.
- Use a **constant-time** comparison such as `hash_equals`.
- Verify against the raw body **before** decoding to JSON (re-serialized JSON breaks
the signature).
## 5. Delivery and Response Contract
Your endpoint should return the following HTTP codes:
| Response | Meaning | Rabisu behavior |
|---|---|---|
| `2xx` | Processed successfully | Delivery complete |
| `4xx` (incl. 401) | Permanent error (signature/format) | Not retried |
| `5xx` | Transient error | Retried with exponential backoff |
Retry schedule: 1m → 5m → 15m → 1h → 6h → 24h. After 6 attempts the event is marked
"dead letter". After 5 consecutive failures the endpoint is automatically
deactivated (circuit breaker) — reactivate it with `PATCH /webhooks/{id}` once fixed.
## 6. Management Endpoints
- `GET /webhooks` — list registered endpoints (including inactive)
- `GET /webhooks/{id}` — detail
- `PATCH /webhooks/{id}` — reactivate / update `event_types` or `description`
- `DELETE /webhooks/{id}` — delete (soft delete)
==============================================================================
PART 2 — API REFERENCE (ENDPOINTS)
==============================================================================
Rabisu Virtual Server Reseller API — a REST interface that lets resellers
programmatically order virtual servers, manage existing services and query
their account balance.
**Authentication:** HTTP Basic Auth (RFC 7617).
Username = API Key (`rsk_live_*`), Password = API Secret (`rsks_live_*`).
**Rate Limit:** Every API key has its OWN limit (there is no shared/global limit).
Limits are per minute, by endpoint group (bucket):
`default` 60 (orders, products, balance, webhooks, vnc, credentials, lifecycle),
`services_read` 150 (`GET /services`, `GET /services/{id}`),
`services_status` 300 (`GET /services/{id}/status`),
`services_changes` 120 (power, rebuild, password, upgrade).
Per-bucket increases for large resellers are configured by Rabisu; effective values
are in `GET /auth/me` → `rate_limits`. All responses include `X-RateLimit-*` headers;
when exceeded, `429` + `Retry-After` (seconds) is returned — the client should wait
that long and retry.
**Idempotency:** POST/PUT/PATCH endpoints support the `Idempotency-Key` header
(RFC draft-irsdl-httpbis-idempotency-header). If the same key + same body is
sent again within 24 hours, the cached response is returned. Same key + different
body → 422 `idempotency_key_reuse`.
==============================================================================
[System]
==============================================================================
Health check and version info (no auth required)
------------------------------------------------------------------------------
GET /health
Health check (no auth required)
------------------------------------------------------------------------------
operationId: getHealth
Authentication: Not required
Confirms the server is up. Used by load balancers / monitoring. It is NOT bound to the auth, rate limit and idempotency middlewares — it can be called without limit.
Responses:
200 — Server healthy
Combination of the following (allOf):
→ see schema: ApiResponse
- data (object, optional)
- status (string, optional) [Example: "ok"]
- version (string, optional) [Example: "1.0.0"]
- timestamp (string(date-time), optional) [Example: "2026-04-24T12:00:00Z"]
------------------------------------------------------------------------------
GET /openapi.yaml
Raw YAML content of the OpenAPI 3.0 spec
------------------------------------------------------------------------------
operationId: getOpenApiSpec
Authentication: Not required
Returns this API's OpenAPI 3.0 spec as raw YAML. No auth required — the endpoint list and schemas are documentary in nature, not secret.
Use cases:
- The dev test panel (`/dev/docs.html`) renders this with Swagger UI.
- Import into tools like Postman / Insomnia.
- SDK / client code generators (openapi-generator etc.).
**Cache:** ETag + 5 minutes `Cache-Control: public, max-age=300`. The spec rarely changes; the browser gets a cheap 304 Not Modified response.
Responses:
200 — YAML content of the OpenAPI 3.0 spec
Response headers: ETag: 16-char MD5 prefix; used with If-None-Match to return 304. | Cache-Control
(application/yaml)
string [Example: "openapi: 3.0.3\ninfo:\n title: Rabisu Reseller API\n version: 1.0.0\n...\n"]
304 — Spec unchanged (If-None-Match matched). Empty body.
404 — docs/openapi.yaml file not found on the server (deploy error)
(text/plain)
string [Example: "openapi.yaml not found"]
==============================================================================
[Auth]
==============================================================================
Authentication smoke test + key metadata + credit balance
------------------------------------------------------------------------------
GET /auth/me
Returns authenticated key metadata
------------------------------------------------------------------------------
operationId: getAuthMe
Authentication: BasicAuth
Returns the authenticated identity of a request made with HTTP Basic Auth.
Smoke test endpoint — for quickly verifying that the integration works.
RETURNED FIELDS (there is **NO** api_secret_hash or similar sensitive field):
- `api_key_id`: Internal numeric ID
- `reseller_id`: WHMCS `tblclients.id` (the reseller's client id)
- `name`: Key label
- `permissions`: Scope list (`["orders:create", "*"]`)
- `client_ip`: IP of the client making this request (resolved via X-Forwarded-For trusted proxy resolver)
- `last_used_at`: Last time this key was used (RFC 3339)
- `expires_at`: Key expiry date (NULL = never)
- `rate_limit_rpm`: Legacy single-number override; affects only the `default` bucket (NULL = 60)
- `rate_limits`: EFFECTIVE per-minute limits per bucket
(`{"default":60,"services_read":150,"services_status":300,"services_changes":120}`)
- `auto_apply_credit`: POST /orders automatic balance charge toggle
(true = default; if false the order returns `pending_payment` + `notice=auto_apply_credit_disabled`
and the reseller pays the invoice manually). Changed via admin CLI:
`php bin/api-key-update.php --auto-apply-credit=0|1`
Responses:
200 — Authenticated, identity returned
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (AuthMeResponse, optional)
401 — Authentication failed — missing header, invalid API key/secret, revoked or expired key.
Response headers: WWW-Authenticate: RFC 7235 header — signals the Basic Auth requirement to the client
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "invalid_credentials",
"message": "Gecersiz kimlik bilgileri."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
403 — IP whitelist violation — the incoming IP is not in the key's allow list
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "ip_not_whitelisted",
"message": "Bu IP adresinden erisim izniniz bulunmamaktadir."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
------------------------------------------------------------------------------
GET /auth/balance
Reseller WHMCS credit balance (APCu 60s cache)
------------------------------------------------------------------------------
operationId: getAuthBalance
Authentication: BasicAuth
Returns the authenticated reseller's WHMCS credit balance. The balance is read FIRST from the read-only WHMCS DB replica (`tblclients.credit`); if the DB is unreachable it falls back to the WHMCS HTTP API (`GetClientsDetails`).
**Cache:** APCu 60 seconds (env: `BALANCE_CACHE_TTL_SECONDS`, 0 = bypass). The `cached` field in the response indicates a cache hit.
**Currency:** In Phase 1 a global `BALANCE_DEFAULT_CURRENCY` (default `TRY`). In Phase 2 per-client currency will come via a WHMCS `tblcurrencies` join.
**Normalize:** If the client is not found in WHMCS, `credit=0.0` is returned (no 404 — a safer default for defensive programming on the integration side).
Responses:
200 — Balance returned
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (BalanceResponse, optional)
Example:
{
"success": true,
"data": {
"reseller_id": 1024,
"credit": 125.5,
"currency": "TRY",
"cached": false
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
401 — Authentication failed
→ see schema: ErrorResponse
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
------------------------------------------------------------------------------
GET /auth/balance/movements
Reseller balance movements (live WHMCS tblcredit)
------------------------------------------------------------------------------
operationId: listAuthBalanceMovements
Authentication: BasicAuth
Returns the authenticated reseller's balance movements chronologically (new → old). Source: **live WHMCS `tblcredit`** — exactly matching WHMCS Credit Management (all credit entries + used/invoice-applied credit included).
**Important:** Use `GET /auth/balance` for the current balance. Because this list is read directly from WHMCS there is no local sync lag; if the WHMCS replica is temporarily unreachable the list may come back empty.
**`reason` values:** `manual_credit` (admin credit load), `refund` (invoice-linked refund, `related_invoice_id` populated), `apply_credit` (payment made from credit, negative `amount`).
**Isolation:** A reseller sees only its own movements (client id filter).
**`amount` sign:** Positive = addition (credit loaded/refunded), Negative = outflow (payment from credit). `new_balance` is the cumulative balance including that movement. `currency` is the reseller's actual WHMCS currency (`tblclients.currency`).
**NOTE:** The local `mod_reseller_credit_movements` table is now fed only for the `credit.added` webhook; this list is NOT read from there.
Parameters:
- limit (query, integer, optional) [default: 50; min 1; max 200]
Records per page (1-200)
- offset (query, integer, optional) [default: 0; min 0]
Number of records to skip (pagination)
Responses:
200 — Movement list returned
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (object, optional)
- items (array, optional)
Example:
{
"success": true,
"data": {
"items": [
{
"id": 4821,
"amount": -99,
"currency": "TRY",
"reason": "apply_credit",
"description": "Automatic payment from balance for order #5012 / invoice #8841",
"related_invoice_id": 8841,
"related_order_id": 5012,
"new_balance": 26.5,
"occurred_at": "2026-05-29T13:05:11Z",
"created_at": "2026-05-29T13:05:11Z"
}
]
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-05-29T13:05:12Z"
}
}
401 — Authentication failed
→ see schema: ErrorResponse
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
==============================================================================
[Products]
==============================================================================
Product catalog (WHMCS products + /ozl/active.json stock status)
------------------------------------------------------------------------------
GET /products
Product catalog list (+ stock-active flag)
------------------------------------------------------------------------------
operationId: getProducts
Authentication: BasicAuth
Combines the WHMCS `tblproducts` record with the `/ozl/active.json` stock status.
`hidden=1` WHMCS products are AUTOMATICALLY filtered out of the list.
**Resellable filter (Rabisu Master module):** Products with `resellable=1` in the
`mod_rabisu_master_product_meta` table of Rabisu's main WHMCS are returned.
If the Master module is NOT INSTALLED (no table), no filter is applied —
all visible products are returned (backward compatibility).
**service_type + management (Rabisu Master module):** The Rabisu admin selects a
type (`vps`, `dedicated`, `hosting`) and a management panel for each product. The
type is returned to the reseller as `service_type` (the panel name is not exposed).
`management`: `full` = the API manages the panel (status, power, reinstall...);
`basic` = the API has no integration for that panel; the product is still sold and
the reseller's customer is shown only the access details
(`GET /services/{id}/credentials`: IP, user, password, `panel_url`). Products without
a type are not listed and cannot be ordered. The reseller module must not import a
type/management pair it does not recognize.
**stock_active** flag:
- If `global_status=0`, false for ALL products
- If a `products` map is given, only products with `1` are true
- If NO `products` map is given, all are true (fail-open)
**group_id** query parameter (optional, positive integer): list only the
given WHMCS product group. Invalid/empty values are IGNORED.
Parameters:
- group_id (query, integer, optional) [min 1]
WHMCS `tblproducts.gid` filter
Responses:
200 — Product list returned
Combination of the following (allOf):
→ see schema: ApiResponse
- data (ProductListResponse, optional)
401 — Authentication failed
→ see schema: ErrorResponse
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
------------------------------------------------------------------------------
GET /products/{id}
Single product detail
------------------------------------------------------------------------------
operationId: getProductById
Authentication: BasicAuth
Returns the details of a specific product. If the product is not found OR is
hidden from the reseller (hidden=1) OR is not resellable (Rabisu Master `resellable=0`)
OR has no service type selected (`service_type`), the
SAME 404 `product_not_found` response is returned — the cases are not distinguished
to prevent inventory leakage between resellers.
**config_options[].role (Rabisu Master module):** Each config option group is
returned with a `role` field coming from `mod_rabisu_master_configgroup_meta`
(2 roles): `resource` (RAM/CPU/disk = upgradable), `fixed` (locked/fixed,
INCLUDING LOCATION — does not change on upgrade). A group with no record, or when the
master module is not installed, returns `fixed` (safe default). The legacy `location`
value is also treated as `fixed` (locked). The reseller module + upgrade guard consume this role.
**config_options[].options[].stock_active (Rabisu Master module):** Each
sub-option (e.g. a single location / OS version) is returned with a `stock_active`
bool field coming from `mod_rabisu_master_configoption_stock`. If `false`, that
sub-option is CLOSED for sale to resellers — the reseller module hides it in the
catalog, and if selected in an order, 409 `config_option_out_of_stock` is returned.
Sub-options with no record / when the master module is not installed are `true`.
INDEPENDENT of the WHMCS `hidden` flag (only closes reseller sales; Rabisu continues
its own sales).
Parameters:
- id (path, integer, required) [min 1]
WHMCS `tblproducts.id`
Responses:
200 — Product returned
Combination of the following (allOf):
→ see schema: ApiResponse
- data (ProductDetail, optional)
401 — Authentication failed
→ see schema: ErrorResponse
404 — Product not found or hidden from the reseller
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "product_not_found",
"message": "Aradiginiz urun bulunamadi.",
"details": {
"product_id": 9999
}
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
==============================================================================
[Orders]
==============================================================================
New VPS order, existing order list/detail
------------------------------------------------------------------------------
GET /orders
The reseller's order list (provision records)
------------------------------------------------------------------------------
operationId: listOrders
Authentication: BasicAuth
Parameters:
- limit (query, integer, optional) [default: 50; min 1; max 200]
- offset (query, integer, optional) [default: 0; min 0]
Responses:
200 — Order list
→ see schema: OrderListResponse
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
------------------------------------------------------------------------------
POST /orders
Create a new order + attempt AUTOMATIC payment from balance
------------------------------------------------------------------------------
operationId: createOrder
Authentication: BasicAuth
**Flow with 3 outcomes:**
1. If `StockService::isAvailable(pid)` = false → 409 `product_unavailable`.
1b. If a sub-option CLOSED for reseller sale (e.g. an out-of-stock location) is selected in `extra.configoptions` → 409 `config_option_out_of_stock` (Rabisu Master `mod_rabisu_master_configoption_stock.in_stock=0`). The reseller module already hides these; this is the server-side second line of defense.
2. If `period` is outside the whitelist → 422 `invalid_period`.
3. WHMCS `AddOrder` -> an order + unpaid invoice are created.
4. The reseller's `auto_apply_credit` toggle (GET /auth/me) is checked:
- **false** -> `ApplyCredit` is SKIPPED; `status=pending_payment`, `payment_applied=false`, `notice=auto_apply_credit_disabled`. The reseller pays the invoice manually (from the panel / by bank transfer) as it prefers. The toggle is enabled via the admin CLI:
`php bin/api-key-update.php --auto-apply-credit=1`.
- **true (default)** -> WHMCS `ApplyCredit` (SINGLE call), depending on the result:
- **success** -> `status=pending_provision`, `payment_applied=true`; the WHMCS InvoicePaid hook triggers the virtualizor queue cron.
- **insufficient funds** -> `status=pending_payment`, `notice=insufficient_credit`; the reseller can pay manually.
- **HTTP 5xx / timeout** -> `status=payment_failed`, a record is opened in RequestLogger with an `alarm` flag.
**Actions NOT called:** `AcceptOrder` (the WHMCS InvoicePaid hook already kicks in), `VirtualizorClient` (the WHMCS cron installs the VPS), balance pre-check, `DeleteOrder` (even in the insufficient edge case).
**The Idempotency-Key header is REQUIRED** (otherwise 400 `missing_idempotency_key`). For a same key+body replay a 202 cached response is returned.
Parameters:
- Idempotency-Key (header, string, required) [maxLength 64; Example: "a3f2b1e4-00d6-4c89-9fef-1a2b3c4d5e6f"]
Required replay-protection key (UUIDv4 recommended)
Request body (application/json, required):
→ see schema: CreateOrderRequest
Example:
{
"product_id": 101,
"period": "monthly",
"extra": {
"hostname": "web01.bayi.example",
"configoption1": "centos-stream-9"
}
}
Responses:
202 — The order has been written to the DB. `status` reflects the ApplyCredit result; poll `GET /orders/{id}` for the VPS to be installed.
Response headers: X-Idempotent-Replay: Becomes `"true"` on a repeated request served from cache.
→ see schema: CreateOrderResponse
Example — pending_provision_balance_sufficient: Sufficient balance — ApplyCredit success
{
"success": true,
"data": {
"id": 77,
"order_id": 9001,
"invoice_id": 8001,
"invoice_total": 99,
"currency": "TRY",
"status": "pending_provision",
"payment_applied": true,
"balance_after": 26,
"notice": null,
"due_date": null
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
Example — pending_payment_insufficient_credit: Insufficient balance — the invoice stays unpaid in WHMCS
{
"success": true,
"data": {
"id": 78,
"order_id": 9002,
"invoice_id": 8002,
"invoice_total": 499,
"currency": "TRY",
"status": "pending_payment",
"payment_applied": false,
"balance_after": null,
"notice": "insufficient_credit",
"due_date": null
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440001",
"timestamp": "2026-04-24T12:00:00Z"
}
}
Example — payment_failed_apply_credit_5xx: ApplyCredit 5xx/timeout — admin intervention required
{
"success": true,
"data": {
"id": 79,
"order_id": 9003,
"invoice_id": 8003,
"invoice_total": 199,
"currency": "TRY",
"status": "payment_failed",
"payment_applied": false,
"balance_after": null,
"notice": null,
"due_date": null
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440002",
"timestamp": "2026-04-24T12:00:00Z"
}
}
Example — pending_payment_auto_apply_credit_disabled: The reseller's auto_apply_credit toggle is OFF — ApplyCredit was not called at all, the reseller pays the invoice manually.
{
"success": true,
"data": {
"id": 80,
"order_id": 9004,
"invoice_id": 8004,
"invoice_total": 99,
"currency": "TRY",
"status": "pending_payment",
"payment_applied": false,
"balance_after": null,
"notice": "auto_apply_credit_disabled",
"due_date": null
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440003",
"timestamp": "2026-04-24T12:00:00Z"
}
}
400 — Idempotency-Key header missing
Example:
{
"success": false,
"error": {
"code": "missing_idempotency_key",
"message": "POST /orders icin Idempotency-Key header zorunludur.",
"details": {
"header": "Idempotency-Key"
}
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
409 — Product not in stock (`product_unavailable`) OR the selected config sub-option is closed for reseller sale (`config_option_out_of_stock`).
Example — product_unavailable
{
"success": false,
"error": {
"code": "product_unavailable",
"message": "Secilen urun su anda siparise kapali.",
"details": {
"product_id": 101
}
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
Example — config_option_out_of_stock
{
"success": false,
"error": {
"code": "config_option_out_of_stock",
"message": "Secilen secenek (orn. lokasyon) su anda stokta degil. Lutfen farkli bir secenek secin.",
"details": {
"sub_option_ids": [
701
]
}
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
422 — period outside the whitelist or a body validation error
Example — invalid_period
{
"success": false,
"error": {
"code": "invalid_period",
"message": "Gecersiz abonelik donemi.",
"details": {
"provided": "weekly",
"allowed_values": [
"monthly",
"quarterly",
"semiannually",
"annually",
"biennially",
"triennially"
]
}
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
Example — validation_failed
{
"success": false,
"error": {
"code": "validation_failed",
"message": "Siparis request body gecersiz.",
"details": {
"fields": {
"product_id": "integer ve >0 olmalidir"
}
}
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
500 — WHMCS AddOrder upstream error (order not created)
------------------------------------------------------------------------------
GET /orders/{id}
Single order detail (reseller isolation enforced)
------------------------------------------------------------------------------
operationId: getOrder
Authentication: BasicAuth
For an `unknown_state` record, this call checks WHMCS `GetOrders` for the client
within a 15-minute window. A single matching order is linked as `pending_payment`.
If the window expires with no match, the local record becomes `provision_failed`
(`notice=order_not_confirmed`). `AddOrder` is not repeated.
Parameters:
- id (path, integer, required) [min 1]
Responses:
200 — Order detail
→ see schema: OrderItem
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — Order not found (another reseller's record also returns 404)
Example:
{
"success": false,
"error": {
"code": "order_not_found",
"message": "Siparis bulunamadi."
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
------------------------------------------------------------------------------
POST /orders/{id}/settle
Settle a pending payment from credit (InvoicePaid)
------------------------------------------------------------------------------
operationId: settleOrder
Authentication: BasicAuth
Attempts to pay the WHMCS invoice of a pending (`pending_payment` / `payment_failed`)
order from the reseller balance. Triggered when the customer pays the invoice in the
reseller's WHMCS (InvoicePaid hook). If the balance was insufficient at order time,
the charge is collected here after the reseller tops up the balance → VPS setup is
queued (`pending_provision`).
**Idempotent:** For an order that is already paid (`payment_applied=true`), WHMCS is
not touched at all; the current state is returned with `already_applied=true`.
The `Idempotency-Key` header is optional; if sent, the same key returns the same response.
**Concurrent settlement:** If another settlement for the same order is in progress,
409 `settle_in_progress` (Retry-After 5) is returned. A record whose ApplyCredit
result is uncertain (transport error) is resolved after 5 minutes using the WHMCS
invoice status: if `Paid` it is treated as paid, if `Unpaid` it is retried.
**Result states (`status`):**
- `pending_provision` — credit applied, VPS setup pending
- `pending_payment` — balance still insufficient (`notice=insufficient_credit`),
can be retried immediately
- `payment_failed` — temporary WHMCS error (5xx); retry after 5 minutes
- `unknown_state` / `provision_failed` — no charge is made, `already_applied=false`
**Isolation:** Another reseller's order id returns 404 `order_not_found`.
Parameters:
- id (path, integer, required) [min 1]
`mod_reseller_provisions.id` (the id returned by POST /orders)
Responses:
200 — Result of the settlement attempt (success, insufficient, or already paid)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (SettleOrderResult, optional)
Example — applied: Credit applied
{
"success": true,
"data": {
"id": 1024,
"order_id": 9401,
"invoice_id": 8401,
"currency": "TRY",
"status": "pending_provision",
"payment_applied": true,
"balance_after": 10,
"notice": null,
"already_applied": false
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
Example — alreadyPaid: Already paid (no-op)
{
"success": true,
"data": {
"id": 1024,
"order_id": 9402,
"invoice_id": 8402,
"currency": "TRY",
"status": "pending_provision",
"payment_applied": true,
"balance_after": null,
"notice": null,
"already_applied": true
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
Example — insufficient: Balance still insufficient
{
"success": true,
"data": {
"id": 1024,
"order_id": 9403,
"invoice_id": 8403,
"currency": "TRY",
"status": "pending_payment",
"payment_applied": false,
"balance_after": null,
"notice": "insufficient_credit",
"already_applied": false
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — Order not found (another reseller's record also returns 404)
Example:
{
"success": false,
"error": {
"code": "order_not_found",
"message": "Siparis bulunamadi."
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
==============================================================================
[Services]
==============================================================================
VPS service detail (WHMCS + Virtualizor combined), real-time metrics and OS templates for rebuild. All endpoints sit behind `ServiceOwnershipMiddleware` — a reseller can only access its own services.
------------------------------------------------------------------------------
GET /services
Reseller's services — bulk list (cursor or page + search)
------------------------------------------------------------------------------
operationId: listServices
Authentication: BasicAuth
Returns all of the reseller's services page by page. Designed for cron status
sync: 5000 services = 25 requests (limit=200). Reads from the service source and
does NOT go to Virtualizor — use `GET /services/{id}/status` for the server's
on/off state.
**Pagination:** `after` cursor (last seen `service_id`). The first request is
`after=0`; continue with `?after={next_after}` until `next_after` in the response
is null. Cursor pagination does not shift even if new services are added.
**Page mode (admin table):** If `page` or `q` is given, the list is sorted NEWEST
FIRST, returning up to `limit` (default 50) items plus `total` /
`total_pages`. `q` does a partial match on hostname, main IP and additional IPs
(`server123` → `r-server123-qwqe`); if numeric, an exact match on the service id
also counts. `match_ids` are OR-ed into the search — the reseller sends services it
found on its own side (e.g. by customer e-mail).
`after` and `ids` are not used in this mode.
**status:** The API's own values (`active`, `suspended`...); text specific to the
source system (WHMCS today) is not returned.
**Ownership:** Only the calling reseller's services are returned; another reseller's
id in the `ids` filter is silently skipped.
**Rate limit:** `services_read` bucket (150 req/min, shared with `GET /services/{id}`).
Parameters:
- limit (query, integer, optional) [default: 100; min 1; max 200]
- after (query, integer, optional) [default: 0; min 0]
Cursor — services AFTER this service_id
- ids (query, string, optional) [Example: "7777,7778"]
Comma-separated list of service_ids (max 200)
- page (query, integer, optional) [min 1]
Page mode — starts at 1, newest first
- q (query, string, optional) [maxLength 100; Example: "server123"]
Page mode — hostname / IP partial, id exact match
- match_ids (query, string, optional) [Example: "7777,7778"]
Page mode — service_ids OR-ed into the search (max 500)
Responses:
200 — Service page
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (ServiceListResponse, optional)
Example:
{
"success": true,
"data": {
"items": [
{
"service_id": 7777,
"product_id": 101,
"product_name": "VPS X4",
"status": "active",
"domain": "web01.bayi.example",
"dedicated_ip": "203.0.113.42",
"billing_cycle": "Monthly",
"first_payment_amount": 99,
"recurring_amount": 99,
"next_due_date": "2026-11-24",
"reg_date": "2026-04-24"
}
],
"currency": "TRY",
"next_after": 7777
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-10-04T12:00:00Z"
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
422 — Invalid `ids`, `match_ids` or `q` parameter
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "invalid_input",
"message": "ids virgulle ayrilmis pozitif tam sayilar olmali (en fazla 200).",
"details": {
"field": "ids"
}
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-10-04T12:00:00Z"
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
503 — Service source temporarily unreadable — retry after Retry-After
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "service_list_unavailable",
"message": "Hizmet listesi su an okunamiyor, biraz sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-10-04T12:00:00Z"
}
}
------------------------------------------------------------------------------
GET /services/{id}
VPS service detail (WHMCS + Virtualizor combined)
------------------------------------------------------------------------------
operationId: getServiceById
Authentication: BasicAuth
Combines the WHMCS-side information of the reseller's VPS service (domain, IP,
billing cycle, next due date, namespace) with Virtualizor-side runtime metrics
(hostname, IP list, virt type, running state).
**VPS_ID resolution:** The official Virtualizor WHMCS module stores the VPS_ID in a
WHMCS custom field — `tblcustomfields` (fieldname=`vpsid` or display-named
`vpsid|...`, type='product', relid=PRODUCT_ID) +
`tblcustomfieldsvalues` (fieldid=customfield.id, relid=SERVICE_ID,
value=VPSID). The name before the pipe is matched. If the custom field is not defined or
the value is empty, `vps_id=null` is returned and the `virt` payload is null
(whitelabel packages or services not yet provisioned).
**Graceful degradation:** On a Virtualizor master upstream error (timeout,
5xx, auth failure), 200 is returned instead of 502; `virt=null` and
`virt_unavailable=true`. The reseller at least sees the WHMCS information.
**Rate limit:** `services_read` bucket (150 req/min, shared with `GET /services`).
Parameters:
- id (path, integer, required) [min 1]
WHMCS `tblhosting.id` (service_id)
Responses:
200 — Service detail returned (virt may be null if virt_unavailable=true)
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (ServiceDetail, optional)
Example:
{
"success": true,
"data": {
"service_id": 7777,
"product_id": 101,
"server_id": 12,
"vps_id": 1234,
"domain": "web01.bayi.example",
"dedicated_ip": "203.0.113.42",
"nameservers": [
"ns1.rabisu.com",
"ns2.rabisu.com"
],
"billing_cycle": "monthly",
"first_payment_amount": 99,
"recurring_amount": 99,
"next_due_date": "2026-05-24",
"domain_status": "Active",
"reg_date": "2026-04-24",
"virt": {
"hostname": "web01.bayi.example",
"ips": [
"203.0.113.42"
],
"virt_type": "kvm",
"suspended": false,
"os_name": "almalinux-8-x86_64",
"default_user": "root",
"cores": 2,
"ram_mb": 4096,
"disk_gb": 40,
"bandwidth_gb": 30720,
"bandwidth_used_gb": 12.5,
"location": "Germany"
},
"virt_unavailable": false
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
403 — Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "forbidden",
"message": "Bu kaynaga erisim yetkiniz yok."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — Service not found (no record in tblhosting)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "service_not_found",
"message": "Servis bulunamadi.",
"details": {
"service_id": 7777
}
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
------------------------------------------------------------------------------
DELETE /services/{id}
Terminate the service via the WHMCS module hook (asynchronous)
------------------------------------------------------------------------------
operationId: terminateService
Authentication: BasicAuth
`WhmcsApiClient::moduleTerminate` is called. The WHMCS provisioning queue runs the Virtualizor `delvs` job async (~60s queue + ~30s delvs). For this reason the response returns **HTTP 202 Accepted**; the reseller then tracks it with GET /services/{id}/status.
**Idempotency-Key:** REQUIRED (without the header, `400 missing_idempotency_key`). Destructive op + double-click protection. A repeat request with the same key within 24 hours returns the cached response — a 2nd delvs is not queued.
**Rate limit:** Default bucket (60 rpm).
**Body:** `{"confirm": true}` STRICT bool === true. Truthy values (`1`, `"true"`, `"yes"`) are rejected → `400 invalid_terminate_request`.
**vps_id null:** SKIP (allowed). A cleanup scenario for pending/whitelabel services — WHMCS moduleTerminate does not look at vps_id, it works by serviceid.
**Side effect:** `mod_reseller_provisions.status='terminated'` is set + the `service.terminated` event (`status='skipped'`) is written to the webhook queue.
Parameters:
- id (path, integer, required) [min 1]
- Idempotency-Key (header, string(uuid), required)
REQUIRED. Same key cached for 24h.
Request body (application/json, required):
- confirm (boolean, required) [values: true]
STRICT bool === true. Truthy values are rejected.
Example:
{
"confirm": true
}
Responses:
202 — Termination scheduled (async — WHMCS queue + Virtualizor delvs)
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (TerminateScheduledResult, optional)
Example:
{
"success": true,
"data": {
"status": "termination_scheduled",
"service_id": 12345,
"vps_id": 67890,
"terminated_at": "2026-04-25T06:25:00+00:00",
"estimated_completion_seconds": 120
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
400 — Invalid terminate request (`invalid_terminate_request` or `missing_idempotency_key`)
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
403 — Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "forbidden",
"message": "Bu kaynaga erisim yetkiniz yok."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — Service not found
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
502 — WHMCS API upstream error
------------------------------------------------------------------------------
GET /services/{id}/status
Real-time VPS metrics (CPU/RAM/disk/net)
------------------------------------------------------------------------------
operationId: getServiceStatus
Authentication: BasicAuth
LIVE status and metrics via Virtualizor admin `act=vs&vs_status=` (queries the
node at that moment). If this call fails or does not return the expected structure,
the periodic `act=vps_stats` is used. CPU percentage comes from enduser `act=cpu`.
**Rate limit:** `services_status` bucket — 300 req/min, separate per reseller.
ISOLATED from the other buckets.
**management=basic:** `409 management_unavailable` (the panel is not in the API).
**Error behavior:** If Virtualizor is down, 502 is returned (NO graceful
degradation — a partial response is meaningless for real-time metrics).
**Cache:** 15 s per VPS (`STATUS_CACHE_TTL_SECONDS` on the server). A second request
for the same VPS within this period does not go to Virtualizor. Power, rebuild, suspend,
unsuspend and terminate operations clear the cache and disable it completely for the
next 180 s, so an intermediate state during a transition (e.g. still running after stop)
does not stay cached and delay the panel.
Parameters:
- id (path, integer, required) [min 1]
Responses:
200 — Real-time metrics
Response headers: X-RateLimit-Limit: The key's effective limit for the services_status bucket | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (ServiceStatus, optional)
Example:
{
"success": true,
"data": {
"service_id": 7777,
"vps_id": 1234,
"running": true,
"cpu_percent": 12.5,
"ram_used_mb": 768,
"ram_total_mb": 2048,
"disk_used_mb": 5500,
"disk_total_mb": 40960,
"net_in_bytes": 102400,
"net_out_bytes": 51200,
"bandwidth_total_bytes": 1256550400
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
403 — Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "forbidden",
"message": "Bu kaynaga erisim yetkiniz yok."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — Service not found OR no Virtualizor mapping
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "service_not_found",
"message": "Servis bulunamadi.",
"details": {
"service_id": 7777
}
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
502 — Virtualizor master upstream error (timeout / 5xx)
→ see schema: ErrorResponse
------------------------------------------------------------------------------
GET /services/{id}/credentials
Access details (username/password/ip/hostname/panel_url)
------------------------------------------------------------------------------
operationId: getServiceCredentials
Authentication: BasicAuth
Returns the root access details of the reseller's VPS. `password` is decrypted via
the WHMCS `DecryptPassword` API action (tblhosting.password is stored encrypted).
If it cannot be decrypted (empty in DB, no WHMCS API permission, transport error),
`password_available=false` + an empty `password` is returned — in that case the reseller
module MUST NOT overwrite the existing password.
**Usage:** After the `service.created` webhook, the reseller module calls this endpoint
and writes the result to its own WHMCS `tblhosting` record (password + dedicatedip);
this way it appears in the admin/client area + the `{$service_password}` mail merge
field.
**management=basic:** For a service whose panel the API cannot manage, the customer
connects directly with these details; `panel_url` = the WHMCS server's hostname
(cPanel :2083, Plesk :8443). For a fully managed service `panel_url` is null.
**SECURITY:** The returned `password` is the plaintext root password; ownership
(api_key → reseller → service) is verified, and it is masked in logs.
**Rate limit:** Default bucket (60 req/min). **Idempotency:** none (read).
Parameters:
- id (path, integer, required) [min 1]
Responses:
200 — VPS access details
Combination of the following (allOf):
→ see schema: ApiResponse
- data (object, optional)
- service_id (integer, optional) [Example: 7777]
- vps_id (integer, optional, nullable) [Example: 1234]
- username (string, optional) [Example: "root"]
- password (string, optional) [Example: "S3cr3t-Root-Pw"]
Plaintext root password. Empty if password_available=false.
- password_available (boolean, optional) [Example: true]
Whether the password could be decrypted from WHMCS.
- ip (string, optional) [Example: "203.0.113.42"]
- hostname (string, optional) [Example: "web01.bayi.example"]
- service_type (string, optional) [values: "vps" | "dedicated" | "hosting"; Example: "vps"]
- management (string, optional) [values: "full" | "basic"; Example: "full"]
- panel_url (string, optional, nullable)
management=basic only — the panel address the customer logs in to.
403 — Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "forbidden",
"message": "Bu kaynaga erisim yetkiniz yok."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — Resource not found (or hidden from the reseller). To prevent inventory/resource leakage between resellers, "not found" and "not accessible" return a single response.
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "not_found",
"message": "Aradiginiz kaynak bulunamadi."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
------------------------------------------------------------------------------
GET /services/{id}/os-templates
OS templates allowed for rebuild on this VPS (service-specific filter)
------------------------------------------------------------------------------
operationId: listServiceOsTemplates
Authentication: BasicAuth
Selection list for the VPS rebuild operation. **ENH-001 (live test 2026-05-19):**
the list is now service-specific — the `ostemplates` field from the Virtualizor
`act=rebuild&vpsid=X` form-load call is parsed. This is the list filtered by the media
group assigned to the VPS in Virtualizor. Previously a global list
(`act=ostemplates`, 255+ OS) was returned, and when the reseller picked the wrong OS and
rebuilt, Virtualizor returned the "The OS you submitted is invalid" error.
Now only allowed OSes are shown.
**NOTE:** The initial order (`POST /orders`) does NOT USE this endpoint. During
provisioning, the WHMCS Virtualizor module assigns the OS from its own config options. This
endpoint is only for the rebuild flow.
**Cache:** APCu, key `os_templates:v2:vps:{vpsId}` (per-VPS), TTL 300 seconds.
Since different VPSes can be in different media groups, a global key is NOT A SOLUTION.
Two VPSes in the same media group do not share this cache — practical impact is zero
(the OS list is updated about once a month).
**Cache invalidation:** After the operator adds a new OS image, it appears within at most
5 min. An admin CLI hook for urgent invalidation will come (Phase 4).
**Rate limit:** Default bucket (60 req/min).
**management=basic:** `409 management_unavailable`.
**vps_id null:** returns 422 `service_not_provisioned` — rebuild is not possible anyway
for a service awaiting provisioning.
Parameters:
- id (path, integer, required) [min 1]
Responses:
200 — OS template list
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (OsTemplateList, optional)
Example:
{
"success": true,
"data": {
"templates": [
{
"id": 270,
"name": "CentOS Stream 9",
"virt_type": "kvm"
},
{
"id": 280,
"name": "Debian 12",
"virt_type": "kvm"
},
{
"id": 290,
"name": "Ubuntu 24.04",
"virt_type": "kvm"
}
]
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
403 — Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "forbidden",
"message": "Bu kaynaga erisim yetkiniz yok."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — Resource not found (or hidden from the reseller). To prevent inventory/resource leakage between resellers, "not found" and "not accessible" return a single response.
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "not_found",
"message": "Aradiginiz kaynak bulunamadi."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
422 — The VPS is still awaiting provisioning (vps_id null). Since a rebuild cannot be done, the OS list cannot be fetched either. The reseller module should show a "waiting for OS list" message until provisioning completes.
Combination of the following (allOf):
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "service_not_provisioned",
"message": "Bu servis henuz olusturulmamis.",
"details": {
"service_id": 7777
}
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
------------------------------------------------------------------------------
POST /services/{id}/power/{action}
VPS power operation (start/stop/restart/poweroff)
------------------------------------------------------------------------------
operationId: powerService
Authentication: BasicAuth
Changes the power state of the reseller's VPS. The `action` URL parameter accepts
`start`, `stop`, `restart` or `poweroff`; any other value returns 404 from the
Slim route regex.
**Idempotency-Key REQUIRED.** If the header is missing, `400 missing_idempotency_key`
is returned. Power actions must be processed idempotently for double-click protection;
the reseller module must generate a NEW UUID v4 ON EVERY CLICK.
The same key + same body replays the cached response for 24 hours
(with the `X-Idempotent-Replay: true` header).
**Rate limit:** `services_changes` bucket (120 req/min).
**vps_id null:** If the service is not yet linked to Virtualizor (`tblcustomfieldsvalues`
empty or undefined), `422 service_not_provisioned` is returned (`409 management_unavailable`
for a `management=basic` service) and NO call is made to Virtualizor.
Parameters:
- id (path, integer, required) [min 1]
- action (path, string, required) [values: "start" | "stop" | "restart" | "poweroff"]
- Idempotency-Key (header, string, required) [maxLength 64]
A NEW UUID v4 generated by the reseller module on every click (RFC 4122).
A resent same key returns the cached response.
Responses:
200 — Power action processed
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds) | X-Idempotent-Replay: `true` on a cache-hit replay. Not sent for fresh processing.
Combination of the following (allOf):
→ see schema: ApiResponse
- data (PowerActionResult, optional)
Example:
{
"success": true,
"data": {
"status": "power_action_executed",
"action": "start",
"vps_id": 12345,
"executed_at": "2026-04-25T06:01:00+00:00"
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
400 — Idempotency-Key missing or invalid power action
Example — missing_idempotency_key
{
"success": false,
"error": {
"code": "missing_idempotency_key",
"message": "POST /services/{id}/power/{action} icin Idempotency-Key header zorunludur.",
"details": {
"header": "Idempotency-Key",
"endpoint": "POST /services/{id}/power/{action}"
}
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
403 — Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "forbidden",
"message": "Bu kaynaga erisim yetkiniz yok."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
422 — VPS not yet provisioned (vps_id custom field empty)
Example:
{
"success": false,
"error": {
"code": "service_not_provisioned",
"message": "VPS not yet provisioned or vpsid custom field missing",
"details": {
"service_id": 12345
}
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
502 — Virtualizor upstream error
------------------------------------------------------------------------------
POST /services/{id}/rebuild
VPS OS reinstall (asynchronous, 202 Accepted)
------------------------------------------------------------------------------
operationId: rebuildService
Authentication: BasicAuth
Reinstalls the VPS with the selected OS template. ALL data on the disk is
deleted. Asynchronous job — the Virtualizor `rebuildvps` operation takes 5-30 minutes;
the API immediately returns 202 Accepted and the reseller module then tracks it with
`GET /services/{id}/status`.
**SECURITY:** `confirm: true` (strict bool) is REQUIRED in the body. If `false`
or missing, `400 confirmation_required` is returned and NO call is made to
Virtualizor (client-side guard).
**Idempotency-Key REQUIRED.**
**Rate limit:** `services_changes` bucket.
**vps_id null:** `422 service_not_provisioned`.
**management=basic:** `409 management_unavailable`.
Parameters:
- id (path, integer, required) [min 1]
- Idempotency-Key (header, string, required) [maxLength 64]
Request body (application/json, required):
- os_id (integer, required) [min 1]
Target OS template ID. Selected from the `/services/{id}/os-templates` list.
- confirm (boolean, required) [values: true]
Confirmation that data will be deleted. `true` is REQUIRED; if `false` or missing it returns `400 confirmation_required`. Strict bool — `1`/`'true'` are not accepted.
- root_password (string, optional) [minLength 8; maxLength 64]
**Optional** new root password. The reseller module can send the password that comes from WHMCS or that the user sets in the UI.
If not sent, the API GENERATES a secure (16 char, alphanumeric) password and returns it once in the response `data.root_password` field. The reseller MUST SHOW this value to the user — it cannot be retrieved later (Virtualizor does not store it).
**Character restrictions:**
- ASCII printable only (0x20-0x7E)
- Quote, double-quote, backtick, backslash and dollar characters are FORBIDDEN (shell/quote escape risk).
Responses:
202 — Rebuild scheduled (asynchronous job started)
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds) | X-Idempotent-Replay: `true` on a cache-hit replay.
Combination of the following (allOf):
→ see schema: ApiResponse
- data (RebuildScheduledResult, optional)
Example:
{
"success": true,
"data": {
"status": "rebuild_scheduled",
"os_id": 270,
"vps_id": 12345,
"estimated_duration_seconds": 600,
"root_password": "Xkj9aF2pBm7nQrV3"
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
400 — Idempotency-Key missing / confirm=false / body validation error
Example — confirmation_required
{
"success": false,
"error": {
"code": "confirmation_required",
"message": "VPS kurtarma islemi veri kaybina yol acar. Devam etmek icin `confirm: true` parametresini gondermelisiniz.",
"details": {
"vps_id": 12345,
"os_id": 270
}
}
}
Example — missing_idempotency_key
{
"success": false,
"error": {
"code": "missing_idempotency_key",
"message": "POST /services/{id}/rebuild icin Idempotency-Key header zorunludur."
}
}
Example — invalid_rebuild_request
{
"success": false,
"error": {
"code": "invalid_rebuild_request",
"message": "`os_id` must be a positive integer."
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
403 — Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "forbidden",
"message": "Bu kaynaga erisim yetkiniz yok."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
422 — VPS not provisioned OR the selected os_id is not allowed in this VPS's media group.
**os_not_allowed (security):** Even though the GET /os-templates list is media-group-filtered, the rebuild action is validated server-side — if an os_id not in the list (forged) is sent, NO call is made to Virtualizor and 422 is returned.
Example — service_not_provisioned
{
"success": false,
"error": {
"code": "service_not_provisioned",
"message": "VPS not yet provisioned or vpsid custom field missing",
"details": {
"service_id": 12345
}
}
}
Example — os_not_allowed
{
"success": false,
"error": {
"code": "os_not_allowed",
"message": "Secilen isletim sistemi bu sunucu icin kullanilabilir degil.",
"details": {
"service_id": 12345,
"os_id": 999
}
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
502 — Virtualizor upstream error
------------------------------------------------------------------------------
POST /services/{id}/vnc-token
Short-lived (60s) NoVNC connection info
------------------------------------------------------------------------------
operationId: vncTokenService
Authentication: BasicAuth
Used to connect directly from the browser to the `wss://{host}:{port}/{websockify_path}` URL
(port = Virtualizor enduser novnc proxy port, e.g. 4083; NOT the RAW VNC/RFB port).
The API NEVER PROXIES this websocket stream — it only returns connection details
(host/port/password/expires_at).
**Idempotency-Key NOT ACCEPTED.** Even if the header is sent it is IGNORED
(IdempotencyMiddleware is not attached to the route). Reason: every call generates a NEW
password in Virtualizor; a cached old password expires after 60s and the reseller
would get an "invalid password" error.
**Rate limit:** Default bucket (60 req/min) — not high-frequency.
**vps_id null:** `422 service_not_provisioned`.
**management=basic:** `409 management_unavailable`.
**Response:**
- `expires_at`: UTC ISO8601 computed by the server (now + 60s)
- `ttl_seconds`: 60 (fixed, easy for the client to parse)
- `password`: short-lived NoVNC password (LogMasker masks the `vnc_password` field)
- `host`/`port`/`websockify_path`: node details the reseller's browser connects to
Parameters:
- id (path, integer, required) [min 1]
Responses:
200 — VNC connection info (valid for 60s)
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (VncTokenResult, optional)
Example:
{
"success": true,
"data": {
"vps_id": 12345,
"host": "node01.rabisu.com",
"port": 4083,
"websockify_path": "novnc/?virttoken=12345",
"password": "Xkj9_short_lived",
"expires_at": "2026-04-25T06:01:00+00:00",
"ttl_seconds": 60
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
403 — Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "forbidden",
"message": "Bu kaynaga erisim yetkiniz yok."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
422 — VPS not yet provisioned
Example:
{
"success": false,
"error": {
"code": "service_not_provisioned",
"message": "VPS not yet provisioned or vpsid custom field missing",
"details": {
"service_id": 12345
}
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
502 — Virtualizor upstream error
------------------------------------------------------------------------------
POST /services/{id}/password
Change the VPS root password
------------------------------------------------------------------------------
operationId: changeServicePassword
Authentication: BasicAuth
Changes the root password via a Virtualizor `act=editvs` round-trip
(official WHMCS module pattern: first GET the full config, then POST it back with
`editvps=1` + `rootpass`).
**IMPORTANT:** For the password to take EFFECT on the VPS, most virtualization types
require a power cycle (off/on). This endpoint ONLY writes the new password to
Virtualizor; the reseller module orchestrates `poweroff` + `start` itself after
the change.
**Idempotency-Key:** OPTIONAL (writing the same password again is harmless;
not destructive like rebuild).
**Rate limit:** services_changes bucket.
**Security:** The password is NEITHER LOGGED NOR returned in the response.
**vps_id null:** `422 service_not_provisioned`.
**management=basic:** `409 management_unavailable`.
Parameters:
- id (path, integer, required) [min 1]
- Idempotency-Key (header, string(uuid), optional)
Optional — if provided, 24h replay protection.
Request body (application/json, required):
- password (string, required) [minLength 8; maxLength 64; Example: "YeniGuclu_Sifre2026"]
New root password. Printable ASCII only (0x20-0x7E); quote, backtick, backslash and dollar characters are forbidden.
Responses:
200 — Password changed (a power cycle may still be required)
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Example:
{
"success": true,
"data": {
"status": "password_changed",
"vps_id": 12345,
"changed_at": "2026-05-31T18:00:00+00:00"
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
400 — Invalid password (length/characters) or body
Example:
{
"success": false,
"error": {
"code": "invalid_change_password_request",
"message": "`password` length must be between 8 and 64 characters.",
"details": {}
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
403 — Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "forbidden",
"message": "Bu kaynaga erisim yetkiniz yok."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
422 — VPS not yet provisioned
Example:
{
"success": false,
"error": {
"code": "service_not_provisioned",
"message": "VPS not yet provisioned or vpsid custom field missing",
"details": {
"service_id": 12345
}
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
502 — Virtualizor upstream error (no editvs done flag)
------------------------------------------------------------------------------
POST /services/{id}/suspend
Suspend the service via the WHMCS module hook
------------------------------------------------------------------------------
operationId: suspendService
Authentication: BasicAuth
Calls WhmcsApiClient::moduleSuspend. WHMCS triggers its own virtualizor
module, and the queue cron turns it into a Virtualizor `suspendvs` job.
In our DB, `mod_reseller_provisions.status='suspended'`
+ `notice='Suspended via API: '` is set.
**Idempotency-Key:** OPTIONAL (if the header is sent, the middleware applies).
Suspend is already idempotent (if already suspended, WHMCS is a no-op).
**Rate limit:** Default bucket (60 rpm) — lifecycle is not high-frequency.
**vps_id null:** `422 service_not_provisioned` (a service that is not provisioned
cannot be suspended). For a `management=basic` service vps_id is not looked up;
the WHMCS module applies it.
**Body:** `{"reason": "..."}` optional (1-255 chars). Default:
`"Suspended via Reseller API"`. So it can be in sync with the reason shown
in the reseller's WHMCS.
**Side effect:** A `service.suspended` event (`status='skipped'`) is written to the
`mod_reseller_webhooks_queue` table. In the Phase 2 MVP there is NO delivery;
the v2 worker pushes these events to reseller webhook URLs.
Parameters:
- id (path, integer, required) [min 1]
- Idempotency-Key (header, string(uuid), optional)
Optional — if provided, 24h replay protection.
Request body (application/json):
- reason (string, optional) [minLength 1; maxLength 255; Example: "Non-payment"]
Example:
{
"reason": "Non-payment"
}
Responses:
200 — Service suspended
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (SuspendResult, optional)
Example:
{
"success": true,
"data": {
"status": "suspended",
"service_id": 12345,
"vps_id": 67890,
"reason": "Non-payment",
"suspended_at": "2026-04-25T06:23:00+00:00"
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
403 — Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "forbidden",
"message": "Bu kaynaga erisim yetkiniz yok."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — Service not found
422 — VPS not yet provisioned
Example:
{
"success": false,
"error": {
"code": "service_not_provisioned",
"message": "VPS not yet provisioned or vpsid custom field missing",
"details": {
"service_id": 12345
}
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
502 — WHMCS API upstream error (whmcs_upstream_error)
------------------------------------------------------------------------------
POST /services/{id}/unsuspend
Unsuspend the service via the WHMCS module hook
------------------------------------------------------------------------------
operationId: unsuspendService
Authentication: BasicAuth
Calls WhmcsApiClient::moduleUnsuspend. In our DB,
`mod_reseller_provisions.status='active'` + `notice='Unsuspended via API'`
is set.
**Idempotency-Key:** OPTIONAL.
**Rate limit:** Default bucket (60 rpm).
**vps_id null:** `422 service_not_provisioned`.
**management=basic:** vps_id is not looked up; the WHMCS module applies it.
**Body:** None.
**Side effect:** A `service.unsuspended` event (`status='skipped'`)
is written to the webhook queue.
Parameters:
- id (path, integer, required) [min 1]
- Idempotency-Key (header, string(uuid), optional)
Responses:
200 — Service active again
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (UnsuspendResult, optional)
Example:
{
"success": true,
"data": {
"status": "active",
"service_id": 12345,
"vps_id": 67890,
"unsuspended_at": "2026-04-25T06:24:00+00:00"
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
403 — Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "forbidden",
"message": "Bu kaynaga erisim yetkiniz yok."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — Service not found
422 — VPS not yet provisioned
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
502 — WHMCS API upstream error
------------------------------------------------------------------------------
POST /services/{id}/upgrade
Upgrade the service's config options
------------------------------------------------------------------------------
operationId: upgradeService
Authentication: BasicAuth
Upgrades the service's configurable options (`resource`-role groups like RAM/CPU/disk) to new values. The WHMCS `UpgradeProduct` action is called with `type=configoptions`; the prorata difference is calculated on the WHMCS side.
**Two modes:**
- `quote_only=true` → with WHMCS `calconly=1` returns ONLY a price quote (no order/invoice is created, `quote=true`).
- `quote_only=false` (default) → the real upgrade is applied. A difference invoice is created, and the reseller's credit is applied automatically (same as the OrderService ApplyCredit pattern: `pending_provision` / `pending_payment` / `payment_failed`).
**Lock guard:** Only `role=resource` groups (RAM/CPU/disk) can be changed via upgrade. Other groups (`fixed`, old `location`, or those with no metadata → safe default locked) CANNOT BE CHANGED; if a selection in these groups is changed it returns `422 location_locked`. Leaving it at the same value is valid.
**Full config (merge):** The FULL config is always sent to WHMCS (all of the service's current selections + the reseller's deltas). Because WHMCS resets an unsent config option to the product's default (1st) value (which would give the wrong location + wrong prorata), no selection — including location — is reset.
**Downgrade forbidden:** If WHMCS returns negative prorata (credit/refund) it returns `409 downgrade_not_allowed`.
**Conflict:** If there is a previous unpaid upgrade invoice for the service, or WHMCS reports `upgradeinprogress`, `409 upgrade_conflict`.
**Idempotency-Key:** REQUIRED (POST — 24h replay protection).
**Rate limit:** `services_changes` bucket (120 rpm).
**Body:** `config_options` = `{ "": }` (cannot be empty, int=>int). `quote_only` optional bool (default false).
Parameters:
- id (path, integer, required) [min 1]
- Idempotency-Key (header, string(uuid), required)
REQUIRED — 24h replay protection.
Request body (application/json, required):
- config_options (object, required)
WHMCS config option ID → selection/quantity map (cannot be empty).
- quote_only (boolean, optional) [default: false]
If true, price quote only (calconly); the upgrade is not applied.
Example:
{
"config_options": {
"10": 4,
"11": 2048
},
"quote_only": false
}
Responses:
200 — Upgrade applied or quote returned (depending on quote_only)
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (UpgradeServiceResult, optional)
Example — quote: Quote only (quote_only=true)
{
"success": true,
"data": {
"service_id": 12345,
"quote": true,
"currency": "TRY",
"price": "TRY 45,00",
"price_amount": 45,
"days_until_renewal": 18,
"config_options": {
"10": 4,
"11": 2048
},
"order_id": null,
"invoice_id": null,
"status": null,
"payment_applied": false,
"balance_after": null,
"notice": null
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
Example — applied: Actual upgrade (credit applied)
{
"success": true,
"data": {
"service_id": 12345,
"quote": false,
"currency": "TRY",
"price": "TRY 45,00",
"price_amount": 45,
"days_until_renewal": 18,
"config_options": {
"10": 4,
"11": 2048
},
"order_id": 9310,
"invoice_id": 8410,
"status": "pending_provision",
"payment_applied": true,
"balance_after": 155,
"notice": null
},
"meta": {
"trace_id": "...",
"timestamp": "..."
}
}
400 — Invalid upgrade request (invalid_upgrade_request) or missing Idempotency-Key
Example:
{
"success": false,
"error": {
"code": "invalid_upgrade_request",
"message": "config_options bos olamaz",
"details": {}
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
403 — Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "forbidden",
"message": "Bu kaynaga erisim yetkiniz yok."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — Service not found
409 — Downgrade forbidden (downgrade_not_allowed) or upgrade conflict (upgrade_conflict)
Example — downgrade
{
"success": false,
"error": {
"code": "downgrade_not_allowed",
"message": "Downgrade desteklenmiyor",
"details": {
"price": "TRY -12,00"
}
}
}
Example — conflict
{
"success": false,
"error": {
"code": "upgrade_conflict",
"message": "Servis icin odenmemis onceki upgrade faturasi mevcut",
"details": {}
}
}
422 — Locked config option group cannot be changed (location_locked)
Example:
{
"success": false,
"error": {
"code": "location_locked",
"message": "Bu config option grubu upgrade ile degistirilemez (lokasyon veya sabit grup)",
"details": {
"locked_group_ids": [
7
]
}
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
502 — WHMCS API upstream error (whmcs_upstream_error)
==============================================================================
[Webhooks]
==============================================================================
Reseller webhook endpoint registration management (Phase 3.W.3). The reseller
registers to receive a signed POST on an HTTP endpoint on their own server when
subscribed events occur (e.g. service.suspended, product.price_changed).
SUBSCRIPTION PATTERNS (`event_types`):
- `*` → all events (catch-all)
- `prefix.*` → namespace wildcard (service.*, product.*) — single segment
- exact → full event name (service.suspended)
VALID EVENTS (V1): service.created, service.suspended,
service.unsuspended, service.terminated, product.price_changed,
product.stock_changed, product.disabled, credit.added. An unknown event
type returns 422.
`service.created` (Phase 3.W.4): sent when provisioning of the ordered VPS is
completed on the Rabisu side and it becomes active (WHMCS domainstatus 'Pending'
→ 'Active'; detected by cron polling). With this event the reseller learns
IMMEDIATELY that the service is ready (GET /orders/{id} polling remains as a fallback).
Payload: {provision_id, service_id, order_id, product_id, vps_id,
status='active', occurred_at, schema_version}. `provision_id` = the `id` in the
POST /orders response (reseller correlation key).
`credit.added` (Phase 3.B): sent when credit is added to the reseller (manual
credit by admin or invoice refund). Payload: {reseller_id, amount, currency,
reason (manual_credit|refund), description, related_invoice_id, new_balance,
occurred_at}. This event goes ONLY to the relevant reseller (not broadcast).
Source: WHMCS tblcredit polling (bin/credit-event-emitter.php).
NOTE: apply_credit (order payment) does NOT produce this event — it is written
in real time by OrderService to the GET /auth/balance/movements audit.
SECRET: The plain HMAC `secret` in the POST response is shown ONLY once.
If lost, the endpoint must be deleted and re-created.
SIGNATURE: The dispatcher adds two headers to every delivery:
`X-Rabisu-Signature-V2: t=,v1=` — HMAC-SHA256(secret,
"{t}.{X-Rabisu-Event-Type}.{raw body}"). The receiver must verify |now - t| <= 300 s
and the signed event type (replay + type-swap protection).
`X-Rabisu-Signature: sha256=` — body only; for legacy receivers,
NO replay protection, do not use in new integrations.
CIRCUIT BREAKER: 5 consecutive failed deliveries automatically deactivate
the endpoint (is_active=0). The reseller re-activates it with `PATCH {is_active: true}`.
------------------------------------------------------------------------------
GET /webhooks
List the reseller's webhook registrations
------------------------------------------------------------------------------
operationId: listWebhooks
Authentication: BasicAuth
Returns ALL endpoints belonging to the reseller (api_key) — including inactive ones (is_active=0, closed by the circuit breaker). So the reseller can see an inactive endpoint and reactivate it via PATCH.
Responses:
200 — Webhook list
Combination of the following (allOf):
→ see schema: ApiResponse
- data (object, optional)
- items (array, required)
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
------------------------------------------------------------------------------
POST /webhooks
Register a new webhook endpoint
------------------------------------------------------------------------------
operationId: createWebhook
Authentication: BasicAuth
Registers an HTTP endpoint on the reseller's own server, subscribing it to the selected events. The `secret` plain HMAC secret returned in the response is shown ONLY once.
The target URL is strict: only `https`, user info (user:pass@) forbidden, private/internal IPs rejected (SSRF protection).
Request body (application/json, required):
→ see schema: CreateWebhookRequest
Example:
{
"target_url": "https://hooks.bayi.com/rabisu",
"event_types": [
"service.suspended",
"product.*"
],
"description": "Production webhook"
}
Responses:
201 — Endpoint created (secret returned once)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (WebhookCreateResult, optional)
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
409 — Active webhook limit exceeded (webhook_limit_exceeded)
→ see schema: ErrorResponse
422 — Validation error (invalid URL / unknown event)
→ see schema: ErrorResponse
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
------------------------------------------------------------------------------
GET /webhooks/{id}
Single webhook detail
------------------------------------------------------------------------------
operationId: getWebhook
Authentication: BasicAuth
Responses:
200 — Webhook detail
Combination of the following (allOf):
→ see schema: ApiResponse
- data (WebhookEndpoint, optional)
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — No record or belongs to another reseller (webhook_not_found)
→ see schema: ErrorResponse
------------------------------------------------------------------------------
PATCH /webhooks/{id}
Partially update a webhook (reactivate / event_types / description)
------------------------------------------------------------------------------
operationId: updateWebhook
Authentication: BasicAuth
An unsent field is unchanged (partial update). When `is_active: true` is sent, the endpoint is reactivated and `consecutive_failures` is reset (a clean start for the circuit breaker). If `event_types` is sent, the subscription list is REPLACED entirely (not merged).
Request body (application/json, required):
→ see schema: UpdateWebhookRequest
Example:
{
"is_active": true,
"event_types": [
"product.price_changed",
"product.stock_changed"
]
}
Responses:
200 — Updated webhook
Combination of the following (allOf):
→ see schema: ApiResponse
- data (WebhookEndpoint, optional)
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — No record or belongs to another reseller (webhook_not_found)
→ see schema: ErrorResponse
422 — Validation error (empty body / unknown event)
→ see schema: ErrorResponse
------------------------------------------------------------------------------
DELETE /webhooks/{id}
Delete a webhook (soft delete)
------------------------------------------------------------------------------
operationId: deleteWebhook
Authentication: BasicAuth
Soft delete — the record is not removed, `is_active=0` is set (audit + circuit breaker history preserved). The dispatcher no longer delivers to this endpoint.
Responses:
200 — Deleted (soft)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (object, optional)
- id (integer, required) [Example: 12]
- deleted (boolean, required) [Example: true]
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — No record or belongs to another reseller (webhook_not_found)
→ see schema: ErrorResponse
==============================================================================
[ModuleReleases]
==============================================================================
Reseller WHMCS module self-update. The module asks for the latest version with
`GET .../latest` and downloads the signed zip via `download_path`. Before installing
the zip, `sha256` and `signature` (ed25519 detached signature of the zip bytes, base64)
must be verified with the Rabisu public key bundled in the module. Release files
are placed on the server manually; the API only reads them.
------------------------------------------------------------------------------
GET /module-releases/{module}/latest
Latest valid release of the module
------------------------------------------------------------------------------
operationId: getLatestModuleRelease
Authentication: BasicAuth
Returns the highest version among the valid manifests under
`MODULE_RELEASES_DIR/{module}/` using `version_compare` (0.6.10 > 0.6.9). Invalid
manifests (broken JSON, version/module mismatch, unsafe file name, missing
zip, size/sha256/signature error) are skipped. If there is no valid release, 404
`release_not_found`.
Default rate limit bucket (`default`, 60/min).
Parameters:
- module (path, string, required) [pattern ^[a-z0-9-]{1,40}$]
Module identifier (directory name), e.g. `bayi-whmcs`
Responses:
200 — Latest release summary
Response headers: X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
Combination of the following (allOf):
→ see schema: ApiResponse
- data (ModuleRelease, optional)
Example:
{
"success": true,
"data": {
"module": "bayi-whmcs",
"version": "0.6.6",
"released_at": "2026-10-04",
"notes": "- Sunucunuz hazir e-postasi\n- Webhook secret gizli alan",
"size": 123456,
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"signature": "x0Jb3F...base64 (64 bayt ed25519 imza)...Ag==",
"download_path": "/api/v1/module-releases/bayi-whmcs/0.6.6/download"
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-10-04T12:00:00Z"
}
}
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — No valid release (`release_not_found`) — no module directory, no manifest
or invalid manifest. The reason is not distinguished in the public response.
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "release_not_found",
"message": "Modul surumu bulunamadi.",
"details": {
"module": "bayi-whmcs",
"version": null
}
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-10-04T12:00:00Z"
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
------------------------------------------------------------------------------
GET /module-releases/{module}/{version}/download
Download the signed module zip
------------------------------------------------------------------------------
operationId: downloadModuleRelease
Authentication: BasicAuth
Returns the zip from the manifest as a binary stream (NO JSON envelope). The client
must not install before verifying the body's SHA-256 digest against `X-Content-SHA256` /
`latest.sha256` and the ed25519 signature against `latest.signature`.
No release or invalid manifest → 404 `release_not_found` (JSON).
Default rate limit bucket (`default`, 60/min).
Parameters:
- module (path, string, required) [pattern ^[a-z0-9-]{1,40}$]
Module identifier (directory name), e.g. `bayi-whmcs`
- version (path, string, required) [pattern ^[0-9]+\.[0-9]+\.[0-9]+$]
Version (`MAJOR.MINOR.PATCH`)
Responses:
200 — Zip file
Response headers: Content-Length: Zip size (bytes) | Content-Disposition: Download file name | X-Content-SHA256: SHA-256 digest of the zip bytes (lowercase hex) | Cache-Control | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining: Number of requests remaining in the current window | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
(application/zip)
string(binary)
401 — Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response headers: WWW-Authenticate: RFC 7617 Basic Auth challenge
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Kimlik dogrulama basarisiz."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-25T01:00:00Z"
}
}
404 — No valid release (`release_not_found`) — no module directory, no manifest
or invalid manifest. The reason is not distinguished in the public response.
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "release_not_found",
"message": "Modul surumu bulunamadi.",
"details": {
"module": "bayi-whmcs",
"version": null
}
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-10-04T12:00:00Z"
}
}
429 — Per-minute limit exceeded
Response headers: Retry-After: Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3) | X-RateLimit-Limit: The per-minute limit defined for this key | X-RateLimit-Remaining | X-RateLimit-Reset: Unix epoch of the start of the next window (UTC seconds)
→ see schema: ErrorResponse
Example:
{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Dakika basina maksimum 60 istek limiti asildi. Lutfen 12 saniye sonra tekrar deneyin."
},
"meta": {
"trace_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-04-24T12:00:00Z"
}
}
==============================================================================
[Admin]
==============================================================================
Server-to-server admin channel (`X-Admin-Token`, NOT BasicAuth). When a customer clicks "Become a reseller", the Rabisu WHMCS master module uses these endpoints to generate/list API keys for that customer. Cannot be accessed with reseller API keys.
------------------------------------------------------------------------------
GET /admin/keys
List a reseller's active API keys (NO secret)
------------------------------------------------------------------------------
operationId: adminListKeys
Authentication: AdminToken
Returns the active (is_active=1) API keys for the specified `reseller_id`. The secret hash or plaintext is NEVER returned — only metadata.
Parameters:
- reseller_id (query, integer, required)
WHMCS `tblclients.id`.
Responses:
200 — Active key list
Combination of the following (allOf):
→ see schema: ApiResponse
- data (object, optional)
- reseller_id (integer, required) [Example: 42]
- count (integer, required) [Example: 1]
- keys (array