============================================================================== 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, required) - id (integer, optional) [Example: 7] - reseller_id (integer, optional) [Example: 42] - name (string, optional) [Example: "Bayi paneli"] - api_key (string, optional) [Example: "rsk_live_5H2ABCD..."] - created_at (string, optional, nullable) - last_used_at (string, optional, nullable) - expires_at (string, optional, nullable) 401 — X-Admin-Token missing or wrong (unauthorized) → see schema: ErrorResponse 403 — Admin API not configured (admin_disabled) → see schema: ErrorResponse 422 — reseller_id missing/invalid (invalid_input) → see schema: ErrorResponse ------------------------------------------------------------------------------ POST /admin/keys Generate a new API key for a reseller (secret returned ONCE) ------------------------------------------------------------------------------ operationId: adminCreateKey Authentication: AdminToken When a customer clicks "Become a Reseller", the Rabisu WHMCS master module calls this endpoint to generate an API key + secret for that customer (reseller). NOT HTTP Basic Auth — protected by the `X-Admin-Token` header (server-to-server). **SECURITY:** - `admin` CANNOT be granted in `permissions` (422 forbidden) — this channel only issues reseller-scoped keys; it cannot issue an admin key that bypasses ownership checks. - `api_secret` (plaintext) is returned only once, in this response; only a bcrypt hash is stored in the DB. If lost, a new key must be generated. - `webhook_secret` (HMAC) is also returned only once, in this response. It is pasted into the Webhook Secret field of the reseller module. `POST /webhooks` does not regenerate this secret. Request body (application/json, required): - reseller_id (integer, required) [Example: 42] WHMCS `tblclients.id` — the reseller the key belongs to. - name (string, optional) [Example: "Bayi paneli"] Key label (if empty, `Reseller #`). - permissions (array, optional) Scope list. Default `["*"]`. `admin` forbidden. - ip_whitelist (array, optional) Allowed IP list (if empty/omitted, no restriction). - rate_limit_rpm (integer, optional) [Example: 120] Per-key per-minute limit override (>0). If omitted, default. - expires_at (string, optional) [Example: "2027-01-01T00:00:00Z"] Key expiry date (RFC 3339 / MySQL datetime). If omitted, never. - auto_apply_credit (boolean, optional) [Example: true] POST /orders automatic balance charge toggle. Example: { "reseller_id": 42, "name": "Bayi paneli", "permissions": [ "*" ] } Responses: 201 — Key generated (secret ONCE) Combination of the following (allOf): → see schema: ApiResponse - data (object, optional) - id (integer, required) [Example: 7] - reseller_id (integer, required) [Example: 42] - name (string, required) [Example: "Bayi paneli"] - api_key (string, required) [Example: "rsk_live_5H2ABCD..."] - api_secret (string, required) [Example: "rsks_live_9K3XYZ..."] Plaintext secret — returned ONLY here. - webhook_secret (string, required) [Example: "d2ViaG9va19zZWNyZXQ"] Webhook HMAC secret — returned ONLY here. POST /webhooks does not regenerate it. - permissions (array, required) - ip_whitelist (array, optional, nullable) 401 — X-Admin-Token missing or wrong (unauthorized) → see schema: ErrorResponse 403 — Admin API not configured (ADMIN_API_TOKEN empty → admin_disabled) → see schema: ErrorResponse 422 — Invalid input — `reseller_id` missing/invalid (invalid_input) or `admin` in `permissions` (forbidden). → see schema: ErrorResponse 500 — Key could not be generated (internal_error) → see schema: ErrorResponse ------------------------------------------------------------------------------ POST /admin/keys/{id}/webhook-secret Issue a webhook secret to a legacy key (if missing, one time) ------------------------------------------------------------------------------ operationId: adminIssueWebhookSecret Authentication: AdminToken For a key created before Become a Reseller, if `webhook_secret_encrypted` is empty, generates an HMAC secret and returns the plaintext only in this response. If one exists, `webhook_secret` is null. Parameters: - id (path, integer, required) Request body (application/json, required): - reseller_id (integer, required) Responses: 200 — Generated or already existed Combination of the following (allOf): → see schema: ApiResponse 404 — Key not found → see schema: ErrorResponse ------------------------------------------------------------------------------ POST /admin/keys/{id}/rotate Rotate the reseller API key secret (secret returned ONCE) ------------------------------------------------------------------------------ operationId: adminRotateKey Authentication: AdminToken The public part of `api_key` DOES NOT CHANGE; only the secret is rotated. The old secret becomes invalid IMMEDIATELY (immediate rotate — 24h grace / dual-secret v2 backlog). The APCu auth cache is invalidated. The `reseller_id` in the body is an ownership guard — another reseller's key returns 404 `key_not_found` (isolation, no leak). Parameters: - id (path, integer, required) mod_reseller_api_keys.id Request body (application/json, required): - reseller_id (integer, required) [Example: 42] The reseller the key belongs to (WHMCS tblclients.id). Example: { "reseller_id": 42 } Responses: 200 — Secret rotated (plaintext ONCE) Combination of the following (allOf): → see schema: ApiResponse - data (object, optional) - id (integer, required) [Example: 7] - reseller_id (integer, required) [Example: 42] - name (string, required) [Example: "Bayi paneli"] - api_key (string, required) [Example: "rsk_live_5H2ABCD..."] - api_secret (string, required) [Example: "rsks_live_9K3XYZ..."] New plaintext secret — returned ONLY here. 401 — X-Admin-Token missing or wrong (unauthorized) → see schema: ErrorResponse 403 — Admin API not configured (admin_disabled) → see schema: ErrorResponse 404 — No key, revoked/expired, or belongs to another reseller (key_not_found) → see schema: ErrorResponse 422 — reseller_id missing/invalid (invalid_input) → see schema: ErrorResponse ------------------------------------------------------------------------------ POST /admin/keys/{id}/revoke Revoke the reseller API key (soft delete) ------------------------------------------------------------------------------ operationId: adminRevokeKey Authentication: AdminToken Immediately deactivates the key (`revoked_at` set) + invalidates the APCu auth cache. The record is preserved for audit. The `reseller_id` in the body is an ownership guard — another reseller's key returns 404 `key_not_found`. Parameters: - id (path, integer, required) mod_reseller_api_keys.id Request body (application/json, required): - reseller_id (integer, required) [Example: 42] The reseller the key belongs to (WHMCS tblclients.id). Example: { "reseller_id": 42 } Responses: 200 — Key revoked Combination of the following (allOf): → see schema: ApiResponse - data (object, optional) - id (integer, required) [Example: 7] - revoked (boolean, required) [Example: true] 401 — X-Admin-Token missing or wrong (unauthorized) → see schema: ErrorResponse 403 — Admin API not configured (admin_disabled) → see schema: ErrorResponse 404 — No key, revoked/expired, or belongs to another reseller (key_not_found) → see schema: ErrorResponse 422 — reseller_id missing/invalid (invalid_input) → see schema: ErrorResponse ============================================================================== PART 3 — DATA SCHEMAS (components/schemas) ============================================================================== ------------------------------------------------------------------------------ ServiceLifecycleStatus (string) ------------------------------------------------------------------------------ Service lifecycle status — the API's own values, independent of the source system. This is NOT the server's on/off (power) state. string [values: "pending" | "active" | "suspended" | "terminated" | "cancelled" | "fraud" | "unknown"; Example: "active"] ------------------------------------------------------------------------------ ServiceListItem (object) ------------------------------------------------------------------------------ - service_id (integer, required) [Example: 7777] - product_id (integer, required) [Example: 101] - product_name (string, optional) [Example: "VPS X4"] - status (ServiceLifecycleStatus, required) - domain (string, required) [Example: "web01.bayi.example"] - dedicated_ip (string, required) [Example: "203.0.113.42"] - billing_cycle (string, required) [Example: "Monthly"] - first_payment_amount (number(float), optional) [Example: 120] First payment (reseller's purchase price, in `currency`) - recurring_amount (number(float), optional) [Example: 99] Recurring amount (reseller's purchase price, in `currency`) - discount (allOf, optional, nullable) If the reseller's discount tier covers this service's product, the tier name + rate; otherwise null. Combination of the following (allOf): → see schema: ResellerDiscount - discounted_recurring_amount (number(float), optional, nullable) [Example: 79.2] Amount payable on the next renewal invoice (`recurring_amount` discounted, rounded to the cent). Null when not covered. - next_due_date (string(date), required, nullable) [Example: "2026-11-24"] - reg_date (string(date), required, nullable) [Example: "2026-04-24"] ------------------------------------------------------------------------------ ServiceListResponse (object) ------------------------------------------------------------------------------ In cursor mode `next_after` is returned; in page mode (`page`/`q`) instead `total`, `page`, `per_page`, `total_pages` are returned. - items (array, required) - currency (string, required, nullable) [Example: "TRY"] Currency of the amounts (the reseller's Rabisu account currency) - next_after (integer, optional, nullable) [Example: 7777] (Cursor mode) `after` value for the next page; null = end of list - total (integer, optional) [Example: 1240] (Page mode) Total services matching the filter - page (integer, optional) [Example: 1] (Page mode) Returned page - per_page (integer, optional) [Example: 50] (Page mode) Items per page - total_pages (integer, optional) [Example: 25] (Page mode) Total pages ------------------------------------------------------------------------------ CreateWebhookRequest (object) ------------------------------------------------------------------------------ - target_url (string(uri), required) [Example: "https://hooks.bayi.com/rabisu"] HTTPS endpoint (https required). Private/internal IPs are rejected (SSRF). - event_types (array, required) Subscription patterns: `*`, `prefix.*` (service.*, product.*, credit.*) or an exact event name (e.g. credit.added). An unknown type returns 422. - description (string, optional, nullable) [Example: "Uretim webhook"] Free-form description (optional) ------------------------------------------------------------------------------ UpdateWebhookRequest (object) ------------------------------------------------------------------------------ Partial update — an unsent field is unchanged. At least one field must be sent (otherwise 422). - is_active (boolean, optional) [Example: true] `true` → reactivate (consecutive_failures reset). `false` → deactivate (same effect as DELETE). - event_types (array, optional) Replaces the subscription list ENTIRELY (replace) - description (string, optional, nullable) ------------------------------------------------------------------------------ WebhookEndpoint (object) ------------------------------------------------------------------------------ - id (integer, required) [Example: 12] - target_url (string(uri), required) [Example: "https://hooks.bayi.com/rabisu"] - event_types (array, required) - description (string, optional, nullable) [Example: "Uretim webhook"] - is_active (boolean, required) [Example: true] - consecutive_failures (integer, required) [Example: 0] Consecutive failed-delivery counter (auto-deactivated at 5) - last_delivery_at (string(date-time), optional, nullable) [Example: "2026-05-29T12:00:00Z"] - last_failure_at (string(date-time), optional, nullable) - created_at (string(date-time), required) [Example: "2026-05-29T10:00:00Z"] - updated_at (string(date-time), required) [Example: "2026-05-29T10:00:00Z"] ------------------------------------------------------------------------------ WebhookCreateResult (object) ------------------------------------------------------------------------------ - endpoint (WebhookEndpoint, required) - secret (string, optional) [Example: "Zm9vYmFyYmF6cXV4..."] On a legacy key (no Become a Reseller webhook secret), the plain HMAC secret — returned only in this response. Keys created after Become a Reseller do not have this field; the secret is given once there. - secret_notice (string, required) [Example: "Bu secret yalnizca bir kez gosterilir, guvenli sakla."] ------------------------------------------------------------------------------ ModuleRelease (object) ------------------------------------------------------------------------------ - module (string, required) [Example: "bayi-whmcs"] - version (string, required) [pattern ^[0-9]+\.[0-9]+\.[0-9]+$; Example: "0.6.6"] - released_at (string, required, nullable) [Example: "2026-10-04"] Release date from the manifest (free text, usually YYYY-MM-DD) - notes (string, required) [Example: "- Sunucunuz hazir e-postasi\n- Webhook secret gizli alan"] Release notes (lines separated by `\n`); empty if not in the manifest - size (integer, required) [Example: 123456] Zip size (bytes) - sha256 (string, required) [pattern ^[0-9a-f]{64}$] SHA-256 digest of the zip bytes (lowercase hex) - signature (string, required) ed25519 detached signature of the zip bytes (base64) - download_path (string, required) [Example: "/api/v1/module-releases/bayi-whmcs/0.6.6/download"] Download path (relative to the API host) ------------------------------------------------------------------------------ ApiResponse (object) ------------------------------------------------------------------------------ - success (boolean, required) [values: true] - data (object, required) Endpoint-specific payload (sub-schemas override) - meta (Meta, required) ------------------------------------------------------------------------------ ErrorResponse (object) ------------------------------------------------------------------------------ - success (boolean, required) [values: false] - error (object, required) - code (string, required) [Example: "invalid_credentials"] Snake_case slug (rate_limit_exceeded, invalid_credentials, etc.) - message (string, required) [Example: "Gecersiz kimlik bilgileri."] Human-readable message (may be shown to the end user) - details (object, optional) Optional — endpoint-specific extra fields (validation errors, retry_after, etc.) - meta (Meta, required) ------------------------------------------------------------------------------ Meta (object) ------------------------------------------------------------------------------ - trace_id (string(uuid), required) [Example: "550e8400-e29b-41d4-a716-446655440000"] Request-scoped UUIDv4 — also returned in the response as the `X-Request-ID` header. Set by `TraceIdMiddleware`; used for correlation across all log lines. - timestamp (string(date-time), required) [Example: "2026-04-24T12:00:00Z"] Response generation time (UTC, ISO 8601) ------------------------------------------------------------------------------ ProductItem (object) ------------------------------------------------------------------------------ - id (integer, required) [Example: 101] - service_type (string, required) [values: "vps" | "dedicated" | "hosting"; Example: "vps"] Service type (Rabisu Master). The reseller picks the customer screen based on this. - management (string, required) [values: "full" | "basic"; Example: "full"] `full` = the API manages this product's panel; `basic` = only access details (credentials) are provided, panel operations return 409 `management_unavailable`. - name (string, required) [Example: "VPS Basic"] - group_id (integer, required) [Example: 1] WHMCS `tblproducts.gid` - group_name (string, required) [Example: "VPS Sunucular"] WHMCS `tblproductgroups.name`. Empty string if the group is not found. - description (string, required) [Example: "1 CPU / 2 GB RAM / 40 GB SSD"] - pricing (ProductPricing, required) - discount (allOf, required, nullable) If the reseller's discount tier covers this product, the tier name + rate; otherwise null. `pricing` stays as the list price. Combination of the following (allOf): → see schema: ResellerDiscount - discounted_pricing (allOf, required, nullable) The (discounted) price the reseller pays; same structure as `pricing`, each amount is `round(list * (1 - percent/100), 2)`. Null when not covered. On the Rabisu invoice the product line (configurable options included) is billed at this rate; per-line rounding may cause a 0.01 difference. Combination of the following (allOf): → see schema: ProductPricing - stock_active (boolean, required) [Example: true] Whether the product is currently OPEN for ordering. If false, the UI can show it as "Out of stock / under maintenance". At the ordering stage StockService re-checks. Note: carries the same value as `stock_available` (legacy alias). - stock_available (boolean, required) [Example: true] The field the reseller module (Phase 3) cron uses in the `tblproducts.stockcontrol` sync. Currently identical to `stock_active`; in the future it will become false once `quantity_left` is exhausted. - quantity_left (integer, required, nullable) Remaining stock quantity. Always NULL in Phase 1 (unlimited). In Phase 3 the reseller module will sync this with WHMCS `tblproducts.qty` and lower it to a positive integer. - stock_updated_at (string(date-time), required, nullable) [Example: "2026-04-24T11:30:05+00:00"] Last modified time of the `/ozl/active.json` file (ISO 8601, UTC). NULL if the file does not exist (fail-open — StockService assumes unlimited). The Phase 3 reseller module uses this field as `last_synced_at` to do incremental sync. ------------------------------------------------------------------------------ ProductListResponse (object) ------------------------------------------------------------------------------ - stock (object, required) - global_active (boolean, required) [Example: true] - active_location_ids (array, required, nullable) NULL = no location restriction (all active) - updated_at (string(date-time), required, nullable) [Example: "2026-04-24T11:30:05+00:00"] Last modified time of `/ozl/active.json` (ISO 8601 UTC). Carries the same value as each product's `stock_updated_at` field. - products (array, required) ------------------------------------------------------------------------------ ProductPricingCycle (object) ------------------------------------------------------------------------------ Price for a single billing cycle. Cycles of `-1` (cycle disabled) are NOT included in the output at all (only offered cycles are listed). - recurring (number(float), required) [Example: 10] Recurring fee (currency unit `currency_code`). - setup (number(float), required) [Example: 0] Setup fee for the relevant cycle (0 if none). ------------------------------------------------------------------------------ ProductPricingCurrency (object) ------------------------------------------------------------------------------ - currency_code (string, required) [Example: "USD"] - prefix (string, required) [Example: "$"] - suffix (string, required) [Example: ""] - cycles (object, required) cycle name -> price (monthly|quarterly|semiannually|annually|biennially|triennially) ------------------------------------------------------------------------------ ProductPricing (object) ------------------------------------------------------------------------------ Price map by currency code (CURRENCY-AGNOSTIC): all currencies defined in WHMCS `tblcurrencies` are returned. WHMCS is multi-currency native — NO currency conversion is done; each currency's price is kept independently. Once Rabisu soon becomes USD-only this map narrows to a single currency (the contract does not change). Example: { "USD": { "currency_code": "USD", "prefix": "$", "suffix": "", "cycles": { "monthly": { "recurring": 10, "setup": 0 } } }, "TRY": { "currency_code": "TRY", "prefix": "", "suffix": " TL", "cycles": { "monthly": { "recurring": 400, "setup": 0 } } } } ------------------------------------------------------------------------------ ResellerDiscount (object) ------------------------------------------------------------------------------ The reseller's discount tier (Rabisu Master module 1.4.0, `mod_rabisu_master_tiers`). An additional discount on the list price; on the Rabisu invoice the covered product line (configurable options included) is billed at this discounted rate: new orders, renewals and upgrades. - tier (string, required) [Example: "Altin"] Tier name. - percent (number(float), required) [Example: 20] Discount percentage (0 < percent < 100). ------------------------------------------------------------------------------ ConfigSubOption (object) ------------------------------------------------------------------------------ - id (integer, required) [Example: 701] WHMCS `tblproductconfigoptionssub.id` - name (string, required) [Example: "Frankfurt"] - stock_active (boolean, required) [Example: false] Whether this sub-option (e.g. an individual location / OS version) is IN STOCK for reseller sale — Rabisu Master module (`mod_rabisu_master_configoption_stock`). If `false`, the reseller module hides this option in the catalog and, if selected in an order, returns 409 `config_option_out_of_stock`. For a sub-option with no record / if the master module is not installed, `true` (safe default). INDEPENDENT of the WHMCS `hidden` flag — it only closes reseller sale. - pricing (ProductPricing, required) - discounted_pricing (allOf, required, nullable) If the product has a `discount`, the discounted price of the sub-option (same rate); otherwise null. Combination of the following (allOf): → see schema: ProductPricing ------------------------------------------------------------------------------ ConfigOption (object) ------------------------------------------------------------------------------ Configurable option group + its options. LOCATION is also modeled as a configurable option in Virtualizor; so the location-based price difference naturally comes within this tree (NO special field). - group_id (integer, required) [Example: 7] WHMCS `tblproductconfiggroups.id` - group_name (string, required) [Example: "Lokasyon"] - role (string, required) [values: "resource" | "fixed"; Example: "fixed"] Group role (2 roles) — comes from the Rabisu Master WHMCS module (`mod_rabisu_master_configgroup_meta`). `resource` = upgradeable via upgrade (RAM/CPU/disk), `fixed` = locked/immutable (INCLUDING LOCATION, does not change on upgrade). For a group with no record / if the master module is not installed, `fixed` (safe default). The old `location` value is also returned as `fixed` (locked). The reseller does not mark it manually. - id (integer, required) [Example: 70] WHMCS `tblproductconfigoptions.id` - name (string, required) [Example: "Sunucu Lokasyonu"] - type (integer, required) [Example: 1] WHMCS `optiontype` (1=dropdown, 2=radio, 3=yesno, 4=quantity) - type_label (string, required) [values: "dropdown" | "radio" | "yesno" | "quantity" | "unknown"; Example: "dropdown"] - qty_min (integer, required) [Example: 0] - qty_max (integer, required) [Example: 0] - options (array, required) ------------------------------------------------------------------------------ ProductDetail (allOf) ------------------------------------------------------------------------------ `GET /products/{id}` response — `ProductItem` fields + `config_options` (the full configurable tree, with per-currency price for each sub-option). To keep the list endpoint lightweight, `config_options` is returned ONLY in the detail. Combination of the following (allOf): → see schema: ProductItem - config_options (array, required) ------------------------------------------------------------------------------ CreateOrderRequest (object) ------------------------------------------------------------------------------ - product_id (integer, required) [min 1; Example: 101] WHMCS `tblproducts.id` - period (string, required) [values: "monthly" | "quarterly" | "semiannually" | "annually" | "biennially" | "triennially"; Example: "monthly"] Subscription period — corresponds to the WHMCS `tblhosting.billingcycle` value. - extra (object, optional) Passthrough fields for the WHMCS `AddOrder` action (hostname, configoption1..N, customfield, rootpw, etc.). Only scalar/null values are accepted; NO nested object. ------------------------------------------------------------------------------ CreateOrderResponse (object) ------------------------------------------------------------------------------ - id (integer, required) [Example: 77] `mod_reseller_provisions.id` — GET /orders/{id} uses this id - order_id (integer, required) [Example: 9001] WHMCS `tblorders.id` - invoice_id (integer, required) [Example: 8001] WHMCS `tblinvoices.id` - invoice_total (number(float), required, nullable) [Example: 99] Invoice total amount. In some setups WHMCS does not return the `orderamount`/`invoiceamount` fields in the AddOrder response — in that case null comes. The reseller module can query the null case via `GetInvoice` (optional). - currency (string, required) [Example: "TRY"] The reseller's WHMCS account currency (tblclients.currency); `BALANCE_DEFAULT_CURRENCY` if it cannot be read. - status (string, required) [values: "pending_provision" | "pending_payment" | "payment_failed"; Example: "pending_provision"] One of the 3 outcomes of the `ApplyCredit` flow: - `pending_provision` — sufficient balance, the WHMCS hook triggered the queue cron; the VPS is being installed. - `pending_payment` — insufficient balance; the invoice is unpaid in WHMCS, the reseller can pay manually. - `payment_failed` — ApplyCredit 5xx/timeout; admin will intervene (alarm log). - payment_applied (boolean, required) [Example: true] true if ApplyCredit succeeded (invoice PAID) - balance_after (number(float), required, nullable) [Example: 26] Reseller balance after ApplyCredit; NULL on failure - notice (string, required, nullable) [values: "insufficient_credit" | "auto_apply_credit_disabled" | null] An informational note visible to the reseller. - `insufficient_credit`: Insufficient balance, ApplyCredit was attempted but rejected. The invoice stays unpaid in WHMCS. - `auto_apply_credit_disabled`: Because the reseller's `auto_apply_credit` toggle is OFF, the ApplyCredit call was NOT made at all. The reseller will pay the invoice manually. The toggle is enabled via the admin CLI: `php bin/api-key-update.php --auto-apply-credit=1`. - `null`: Nothing to report (e.g. `pending_provision`). - due_date (string(date), required, nullable) Invoice due date (WHMCS `tblinvoices.duedate`). NULL in Phase 1 if WHMCS does not return it; will be filled via a WHMCS GetInvoice call in Phase 2. ------------------------------------------------------------------------------ OrderItem (object) ------------------------------------------------------------------------------ - id (integer, required) [Example: 77] - order_id (integer, required, nullable) [Example: 9001] - service_id (integer, required, nullable) [Example: 7001] WHMCS `tblhosting.id` — populated if the WHMCS hook created it - invoice_id (integer, required, nullable) [Example: 8001] - product_id (integer, required) [Example: 101] - status (string, required) [values: "pending_payment" | "pending_provision" | "active" | "suspended" | "terminated" | "payment_failed" | "provision_failed" | "pending" | "unknown_state"; Example: "pending_provision"] - payment_applied (boolean, required) [Example: true] - notice (string, required, nullable) [values: "insufficient_credit" | "auto_apply_credit_disabled" | "order_unknown_state" | "reconciled" | "order_not_confirmed" | null] - created_at (string, required) [Example: "2026-04-24 12:00:00"] - updated_at (string, required) [Example: "2026-04-24 12:00:00"] ------------------------------------------------------------------------------ SettleOrderResult (object) ------------------------------------------------------------------------------ - id (integer, required) [Example: 1024] `mod_reseller_provisions.id` - order_id (integer, required) [Example: 9401] - invoice_id (integer, required) [Example: 8401] - currency (string, required) [Example: "TRY"] The reseller's WHMCS account currency (tblclients.currency); `BALANCE_DEFAULT_CURRENCY` if it cannot be read. - status (string, required) [values: "pending_payment" | "pending_provision" | "payment_failed"; Example: "pending_provision"] - payment_applied (boolean, required) [Example: true] Whether this call (or a previous one) applied the credit - balance_after (number(float), required, nullable) [Example: 10] The new balance if credit was applied in this call; otherwise null - notice (string, required, nullable) [values: "insufficient_credit" | "no_invoice" | null] - already_applied (boolean, required) [Example: false] If true the order was already paid, WHMCS was not touched (idempotent no-op). ------------------------------------------------------------------------------ OrderListResponse (object) ------------------------------------------------------------------------------ - items (array, required) ------------------------------------------------------------------------------ BalanceResponse (object) ------------------------------------------------------------------------------ - reseller_id (integer, required) [Example: 1024] WHMCS `tblclients.id` - credit (number(float), required) [Example: 125.5] Current credit balance. 0.0 if the client is not found in WHMCS. - currency (string, required) [Example: "TRY"] The reseller's WHMCS account currency (tblclients.currency); `BALANCE_DEFAULT_CURRENCY` if it cannot be read. - cached (boolean, required) [Example: false] true on an APCu cache hit (same value until TTL expires) ------------------------------------------------------------------------------ CreditMovement (object) ------------------------------------------------------------------------------ A single balance movement (append-only audit record). UPDATE/DELETE are forbidden by a DB trigger — corrections are made with a "compensating" row. - id (integer(int64), required) [Example: 4821] Movement record ID (ascending — for tie-breaker ordering) - amount (number(float), required) [Example: -99] Positive = addition (credit loaded), Negative = outflow (payment from credit) - currency (string, required) [Example: "TRY"] ISO 4217 (TRY, USD, EUR) - reason (string, required) [Example: "apply_credit"] Movement reason. Known values: `apply_credit` (order payment), `refund`, `manual_credit`, `webhook_credit_added`. - description (string, optional, nullable) [Example: "Siparis #5012 / fatura #8841 icin bakiyeden otomatik odeme"] Free-form description (WHMCS admin note or system message) - related_invoice_id (integer, optional, nullable) [Example: 8841] Related WHMCS `tblinvoices.id` (if any) - related_order_id (integer, optional, nullable) [Example: 5012] Related WHMCS `tblorders.id` (if any) - new_balance (number(float), required) [Example: 26.5] Balance snapshot after the movement - occurred_at (string(date-time), required) [Example: "2026-05-29T13:05:11Z"] The movement's actual time (WHMCS side) - created_at (string(date-time), required) [Example: "2026-05-29T13:05:11Z"] The time the API record was written ------------------------------------------------------------------------------ AuthMeResponse (object) ------------------------------------------------------------------------------ - api_key_id (integer(int64), required) [Example: 42] - reseller_id (integer, required) [Example: 1024] WHMCS `tblclients.id` - name (string, required) [Example: "Production Server"] Key label (given by the reseller) - permissions (array, required) - client_ip (string, required) [Example: "203.0.113.42"] The real client IP extracted via the trusted proxy resolver - last_used_at (string(date-time), optional, nullable) [Example: "2026-04-24T11:59:59Z"] The last time this key was used (RFC 3339) - expires_at (string(date-time), optional, nullable) NULL = never - rate_limit_rpm (integer, optional, nullable) [Example: 100] Legacy single-number override; affects only the `default` bucket. NULL = bucket default - rate_limits (object, optional) EFFECTIVE per-minute limits per bucket (default + reseller-specific) - auto_apply_credit (boolean, required) [Example: true] Determines whether the WHMCS `ApplyCredit` call is made automatically in the POST /orders flow. - `true` (default): when the order is created, a charge from balance is attempted in a SINGLE call. Sufficient balance → `pending_provision`; insufficient → `pending_payment` + `notice=insufficient_credit`; 5xx/timeout → `payment_failed`. - `false`: ApplyCredit is not called at all. The order always returns `pending_payment` + `notice=auto_apply_credit_disabled`; the reseller pays the invoice manually from the Rabisu panel or by bank transfer. A flag the reseller can toggle according to its own accounting preferences. The toggle is changed via the admin CLI: `php bin/api-key-update.php --auto-apply-credit=0|1` After the change the APCu auth cache is automatically invalidated, and the next request sees the fresh value. ------------------------------------------------------------------------------ ServiceDetail (object) ------------------------------------------------------------------------------ Payload combining WHMCS-side service info (`tblhosting`) with the Virtualizor-side runtime summary (`act=listvs`). If `vps_id=null` or on a Virtualizor upstream error, `virt=null` and `virt_unavailable=true` are returned — graceful degradation. - service_id (integer, required) [Example: 7777] WHMCS `tblhosting.id` - product_id (integer, required) [Example: 101] WHMCS `tblhosting.packageid` - server_id (integer, required) [Example: 12] WHMCS `tblhosting.server` (Virtualizor master node id) - vps_id (integer, required, nullable) [Example: 1234] Virtualizor `vpsid` (numeric). Written to a custom field by the official Virtualizor WHMCS module (`tblcustomfieldsvalues`, field name `vpsid` or `vpsid|...`). Null if the custom field is undefined or the value is empty — whitelabel packages / services not yet provisioned. - domain (string, required) [Example: "web01.bayi.example"] - dedicated_ip (string, required) [Example: "203.0.113.42"] The dedicated main IP in WHMCS (may differ from the Virtualizor `ips`) - nameservers (array, required) ns1/ns2 combined list (empty strings are stripped) - billing_cycle (string, required) [Example: "monthly"] WHMCS billing cycle (monthly, quarterly, semiannually, annually, ...) - first_payment_amount (number(float), required) [Example: 99] - recurring_amount (number(float), required) [Example: 99] - discount (allOf, optional, nullable) If the reseller's discount tier covers this service's product, the tier name + rate; otherwise null. Combination of the following (allOf): → see schema: ResellerDiscount - discounted_recurring_amount (number(float), optional, nullable) [Example: 79.2] Amount payable on the next renewal invoice (`recurring_amount` discounted, rounded to the cent). Null when not covered. - next_due_date (string(date), required, nullable) [Example: "2026-05-24"] WHMCS `nextduedate`. '0000-00-00' or empty returns null. - domain_status (string, required) [values: "Pending" | "Active" | "Suspended" | "Terminated" | "Cancelled" | "Fraud" | "Completed"; Example: "Active"] Source system (WHMCS) value — for backward compatibility. New clients should use `status`. - status (ServiceLifecycleStatus, optional) - reg_date (string(date), required, nullable) [Example: "2026-04-24"] - virt (object, required, nullable) Virtualizor `act=vs` runtime summary. null if vps_id is null or there is an upstream error. The `running` field is NOT HERE — because in the Virtualizor admin API `act=vs` response the runtime flag was not returned reliably (BUG-008 live test 2026-05-19), use the `GET /services/{id}/status` endpoint for the instantaneous running state. - hostname (string, required) [Example: "web01.bayi.example"] - os_name (string, optional) [Example: "almalinux-8-x86_64"] VPS operating system name (listvs `os_name`). Empty if the field is absent. - default_user (string, optional) [Example: "root"] Default admin username by OS — "Administrator" for Windows, "root" for everything else (Linux). Shown in the reseller customer panel as the root access username (NOT the WHMCS email). - cores (integer, optional) [Example: 2] vCPU core count (listvs `cores`). 0 if the field is absent. - ram_mb (integer, optional) [Example: 4096] Total RAM (MB, listvs `ram`). 0 if the field is absent. - disk_gb (integer, optional) [Example: 40] Total disk capacity (GB, listvs `space`). 0 if the field is absent. - bandwidth_gb (number(float), optional) [Example: 30720] Monthly bandwidth quota (GB, listvs `bandwidth`). 0 if the field is absent. - bandwidth_used_gb (number(float), optional) [Example: 12.5] Used bandwidth (GB, listvs `used_bandwidth`). 0 if the field is absent. - location (string, optional) [Example: "Germany"] The VPS's physical location — the name of the Virtualizor server group the server belongs to (`act=servergroups` sg_name; e.g. "Germany", "Turkey"). The serid -> sg_name map is cached in APCu for 300s. If the location cannot be resolved (Virtualizor unreachable / no group) it returns empty. Shown in the reseller customer panel next to the hostname as a country flag + label. - ips (array, required) All IPv4/IPv6 addresses assigned on the Virtualizor side - virt_type (string, required) [Example: "kvm"] Virtualization type (kvm, openvz, lxc, proxk, ...) - suspended (boolean, required) [Example: false] - service_type (string, optional) [values: "vps" | "dedicated" | "hosting"; Example: "vps"] Service type (the product's Rabisu Master type). - management (string, optional) [values: "full" | "basic"; Example: "full"] If `basic`, panel operations (status/power/rebuild/vnc-token/password) return 409 `management_unavailable`; credentials are shown to the customer. - virt_unavailable (boolean, required) [Example: false] If true, the Virtualizor master upstream did not respond (timeout/5xx), vps_id could not be resolved, or the service is management=basic. The UI may show a "VPS details cannot be retrieved right now" warning in this case. ------------------------------------------------------------------------------ ServiceStatus (object) ------------------------------------------------------------------------------ Real-time VPS metrics (Virtualizor `act=vpsstat`). NO cache. Served under the `services_status` rate limit bucket. - service_id (integer, required) [Example: 7777] - vps_id (integer, required) [Example: 1234] - running (boolean, required) [Example: true] - cpu_percent (number(float), required) [Example: 12.5] Instantaneous CPU usage between 0.0-100.0 (VPS-relative — relative to its own cores). Pulled from enduser `act=cpu` -> cpu.percent; admin used_cpu is NOT USED because it is NODE-relative and misleading. - ram_used_mb (integer, required) [min 0; Example: 768] - ram_total_mb (integer, required) [min 0; Example: 2048] - disk_used_mb (integer, required) [min 0; Example: 5500] - disk_total_mb (integer, required) [min 0; Example: 40960] - net_in_bytes (integer(int64), required) [min 0; Example: 102400] INSTANT inbound network traffic (bytes) — admin `vs_status.net_in` (delta over the poll interval). Live chart source; updated on every poll. - net_out_bytes (integer(int64), required) [min 0; Example: 51200] INSTANT outbound network traffic (bytes) — admin `vs_status.net_out`. Live chart. - bandwidth_total_bytes (integer(int64), required) [min 0; Example: 1256550400] TOTAL monthly network traffic (bytes, combined in+out) — admin `vs_status.used_bandwidth` (GB → bytes). The reseller UI shows it once on first load; instant net_in/net_out are updated by the live poll. ------------------------------------------------------------------------------ OsTemplateList (object) ------------------------------------------------------------------------------ OS templates suitable for rebuild. APCu 5-min cache (`os_templates:v1:global`) — shared across all resellers, independent of reseller_id. - templates (array, required) ------------------------------------------------------------------------------ OsTemplate (object) ------------------------------------------------------------------------------ - id (integer, required) [Example: 270] Virtualizor OS template id (`osid`) - name (string, required) [Example: "CentOS Stream 9"] - virt_type (string, required) [Example: "kvm"] Which virtualization type it can be used for (kvm, openvz, ...) ------------------------------------------------------------------------------ PowerActionResult (object) ------------------------------------------------------------------------------ - status (string, required) [values: "power_action_executed"] - action (string, required) [values: "start" | "stop" | "restart" | "poweroff"] - vps_id (integer, required) [min 1; Example: 12345] - executed_at (string(date-time), required) [Example: "2026-04-25T06:01:00+00:00"] The moment the server sent the action to Virtualizor (UTC ISO8601). ------------------------------------------------------------------------------ RebuildScheduledResult (object) ------------------------------------------------------------------------------ The async rebuild job was scheduled successfully. Actual processing takes 5-30 min; the reseller module then tracks it with `GET /services/{id}/status`. - status (string, required) [values: "rebuild_scheduled"] - os_id (integer, required) [min 1; Example: 270] - vps_id (integer, required) [min 1; Example: 12345] - estimated_duration_seconds (integer, required) [Example: 600] Estimated rebuild time (seconds). Fixed 600s (10-min mid-estimate). The reseller UI should set its countdown / polling window based on this value. - root_password (string, optional, nullable) [Example: "Xkj9aF2pBm7nQrV3"] New root password after rebuild. **It is one of two sources:** 1. If the reseller sent `root_password` in the request body — that is returned (echo, reseller-set password). 2. If there is no `root_password` in the body — the API GENERATES a secure (16-char alphanumeric) password and returns it here. In both cases this value can be obtained ONLY IN THIS 1 RESPONSE; it cannot be retrieved again later (Virtualizor does not store it). It must be shown to the user in the reseller UI. **Behavior:** - KVM rebuild: the password is assigned as the VPS reboots (onboot). - LXC/OpenVZ rebuild: the password is assigned immediately. **Logging:** LogMasker automatically masks the `root_password` field (`***MASKED***` appears in logs). ------------------------------------------------------------------------------ VncTokenResult (object) ------------------------------------------------------------------------------ Short-lived (60s) NoVNC connection info. The reseller browser connects DIRECTLY to the `host:port/websockify_path` URL; the API does not proxy. - vps_id (integer, required) [min 1; Example: 12345] - host (string, required) [Example: "node01.rabisu.com"] Virtualizor node hostname - port (integer, required) [min 1; max 65535; Example: 4083] Virtualizor client panel (enduser) novnc proxy port: `VIRTUALIZOR_DEFAULT_NOVNC_PORT` (default 4083; 443 if the panel is on 80/443). NOT the RAW VNC/RFB port (5902) — a wss connection to that port gives WS 1006. The browser must send `Sec-WebSocket-Protocol: binary` (otherwise Virtualizor websockify returns 400). - websockify_path (string, required) [Example: "novnc/?virttoken=12345"] Tokenized relative path (the browser connects via `wss://host:port/{path}`). Format: `novnc/?virttoken=`. - password (string, required) [Example: "Xkj9_short_lived"] Short-lived NoVNC password (60s). LogMasker never writes the `vnc_password` field to logs unmasked. - expires_at (string(date-time), required) [Example: "2026-04-25T06:01:00+00:00"] The last validity moment computed by the server (UTC ISO8601, now+60s). - keymap (string, optional) [Example: "tr"] The VPS's Virtualizor VNC keyboard layout (`tr`, `en-us`...); empty if not set. A hint for the default layout when typing text as keystrokes in the console. - ttl_seconds (integer, required) [values: 60; Example: 60] Fixed 60s — so the client can easily count down instead of parsing `expires_at`. ------------------------------------------------------------------------------ SuspendResult (object) ------------------------------------------------------------------------------ WHMCS moduleSuspend succeeded — status='suspended' was set in our provision DB. - status (string, required) [values: "suspended"] - service_id (integer, required) [min 1; Example: 12345] - vps_id (integer, required, nullable) [min 1; Example: 67890] - reason (string, required) [Example: "Non-payment"] - suspended_at (string(date-time), required) [Example: "2026-04-25T06:23:00+00:00"] ------------------------------------------------------------------------------ UnsuspendResult (object) ------------------------------------------------------------------------------ WHMCS moduleUnsuspend succeeded — status='active' was set in our provision DB (suspended_at preserved for audit). - status (string, required) [values: "active"] - service_id (integer, required) [min 1; Example: 12345] - vps_id (integer, required, nullable) [min 1; Example: 67890] - unsuspended_at (string(date-time), required) [Example: "2026-04-25T06:24:00+00:00"] ------------------------------------------------------------------------------ UpgradeServiceResult (object) ------------------------------------------------------------------------------ Result of POST /services/{id}/upgrade. If `quote=true` it is only a prorata quote (order/invoice/payment fields null). `quote=false` real upgrade: difference invoice + credit apply flow (same as OrderService). - service_id (integer, required) [min 1; Example: 12345] - quote (boolean, required) [Example: false] If true, quote only (calconly); the upgrade was not applied. - currency (string, required) [Example: "TRY"] The reseller's WHMCS account currency (tblclients.currency); `BALANCE_DEFAULT_CURRENCY` if it cannot be read. - price (string, optional, nullable) [Example: "TRY 45,00"] WHMCS's formatted prorata amount (verbatim for display). - price_amount (number(float), optional, nullable) [Example: 45] Best-effort parsed prorated amount (list price). - discount (allOf, optional, nullable) If the reseller's discount tier covers this service's product, the tier name + rate; otherwise null. Combination of the following (allOf): → see schema: ResellerDiscount - discounted_price_amount (number(float), optional, nullable) [Example: 36] Prorated amount payable (discounted); the upgrade invoice is billed at this rate on Rabisu. Null when not covered. - days_until_renewal (integer, optional, nullable) [Example: 18] - config_options (object, required) Applied/quoted config option map. - order_id (integer, optional, nullable) [Example: 9310] WHMCS order id on a real upgrade (null on a quote). - invoice_id (integer, optional, nullable) [Example: 8410] Difference invoice id (null on a quote or on an invoice-less upgrade). - status (string, optional, nullable) [values: "pending_provision" | "pending_payment" | "payment_failed" | "active"; Example: "pending_provision"] Real upgrade result status (null on a quote). - payment_applied (boolean, required) [Example: true] Whether credit was applied automatically. - balance_after (number(float), optional, nullable) [Example: 155] Remaining balance if credit was applied. - notice (string, optional, nullable) [values: "insufficient_credit" | "auto_apply_credit_disabled"] Reason if credit could not be applied. ------------------------------------------------------------------------------ TerminateScheduledResult (object) ------------------------------------------------------------------------------ WHMCS moduleTerminate succeeded — the provisioning queue will do the Virtualizor delvs async (queue cron + delvs ~120s). status='terminated' was set in our provision DB. - status (string, required) [values: "termination_scheduled"] - service_id (integer, required) [min 1; Example: 12345] - vps_id (integer, optional, nullable) [Example: 67890] May be null for pending/whitelabel services. - terminated_at (string(date-time), required) [Example: "2026-04-25T06:25:00+00:00"] - estimated_completion_seconds (integer, required) [values: 120; Example: 120]