# Создать заказ регистрации домена `POST /domains` **operationId:** `registerDomain` Требуемые scopes: orders.create, domains.register. Это alias OrderController::store, а не очередь reseller_domain_operation. Предварительно создайте контакты (contacts.write), запросите quote (quotes.create) с resource_type=domain_zone, operation=register, quantity=1, period_unit=year, period_count=1..10. Payload quote содержит domain_name, четыре contact_uuids и, при необходимости, nameservers 2..6, purpose, external_id, notes, whois_privacy_enabled. Контакты должны быть active и принадлежать клиенту, провайдеру и окружению; зона должна соответствовать имени. Для managed передайте customer_uuid; aggregate использует назначенного клиента. Quote должен быть active, не просрочен, создан этим API-ключом и ещё не использован. external_id запроса идентифицирует заказ; external_id в payload quote идентифицирует услугу. В external checkout заказ рассчитывается и запускается из оптового баланса; platform checkout требует отдельной оплаты счёта. test не расходует live-баланс, но требует отдельного тестового маршрута регистратора. HTTP 201 возвращает Order, не Domain и не Operation. Отслеживайте заказ через /orders/{orderUuid}, услугу /services/{serviceUuid} и домен через список; нужны orders.read/services.read/domains.read. Задача register_domain недоступна через /operations. Цена 500000 в примере условна. При неопределённой регистрации не оформляйте второй заказ; требуется сверка существующего. Контроллер общий с /orders: фактически может принять также товарные позиции, при наличии дополнительных scopes (например hosting.order); для доменной интеграции отправляйте только domain_zone/register. Обязателен Idempotency-Key (1..160 символов). Повтор с тем же ключом должен сохранять метод, путь, query и точные байты JSON. HTTP replay обычно хранится 24 часа и возвращает первоначальный ответ, а не актуальную задачу; проверяйте GET /operations/{operationUuid}. Ключ доменной задачи нельзя переиспользовать после истечения HTTP TTL. Лимит общий для всех запросов одного API-ключа (rate_limit_per_minute, значение по умолчанию при выдаче ключа 120, индивидуальное значение может отличаться). Окно счётчика 60 секунд. Учитывайте X-RateLimit-Limit и X-RateLimit-Remaining; при 429 дождитесь Retry-After секунд и добавьте jitter. Polling и повторы также расходуют лимит; лимиты реестра независимы. **Scopes:** `orders.create`, `domains.register` **x-prerequisite-scopes:** ```json [ { "scope": "quotes.create", "when": "Для выпуска quote до вызова этого endpoint." }, { "scope": "contacts.write", "when": "Если контактные профили ещё не созданы." }, { "scope": "domains.read", "when": "Для последующего чтения домена/операции." } ] ``` **x-prerequisite-request-example:** ```json { "description": "Предварительный запрос POST /quotes (другой endpoint, scope quotes.create, отдельный Idempotency-Key). UUID из data.uuid полученного quote передайте в quote_uuid текущей операции. Не используйте здесь демонстрационные UUID или имя без замены.", "method": "POST", "path": "/quotes", "body": { "customer_uuid": "019a1234-1000-7000-8000-000000000002", "items": [ { "resource_type": "domain_zone", "resource_uuid": "019a1234-1000-7000-8000-000000000004", "operation": "register", "period_unit": "year", "period_count": 1, "quantity": 1, "currency": "KZT", "payload": { "domain_name": "example.kz", "contact_uuids": { "owner": "019a1234-1000-7000-8000-000000000003", "admin": "019a1234-1000-7000-8000-000000000003", "tech": "019a1234-1000-7000-8000-000000000003", "billing": "019a1234-1000-7000-8000-000000000003" }, "nameservers": [ { "hostname": "ns1.example.net" }, { "hostname": "ns2.example.net" } ], "external_id": "crm-domain-1001" } } ] } } ``` ## Параметры ### Idempotency-Key Расположение: `header`. Обязательный. Обязателен для POST/PUT/PATCH/DELETE, включая check, sync, test, rotate-secret. После trim 1..160 символов. Один ключ на логическую операцию и API-ключ. Повторите те же method/path/query и байты JSON. TTL HTTP replay по умолчанию 24 часа от первого резервирования; не продлевается. Не переиспользуйте ключ для новой операции, доменная задача дополнительно сохраняет связь с ним. | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | string | Да | minLength: 1; maxLength: 160 | | **Пример** ```json "webhook-create-20261005-0001" ``` ## Тело запроса Обязательное. JSON body; Content-Type: application/json. ### application/json | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | object | Да | required: ["quote_uuid"] | Создаёт заказ по ранее полученной котировке, а не по произвольной цене. Тот же ключ, покупатель и среда обязательны. Поддерживаются только operation=order/register. Тело одинаково для /orders, /domains и /hosting/orders; последние два маршрута добавляют scopes, но не фильтруют типы строк. Схема: CoreCreateOrderRequest | | `$.quote_uuid` | string | Да | format: "uuid" | UUID неистёкшей, неиспользованной котировки текущего ключа. | | `$.customer_uuid` | string / null | Нет | format: "uuid" | Покупатель котировки; обязателен в managed. | | `$.external_id` | string / null | Нет | maxLength: 255 | ID заказа внешнего биллинга; уникален у реселлера внутри test/live. | #### Регистрация для managed-клиента по ранее выданному quote ```json { "quote_uuid": "019a1234-1000-7000-8000-000000000006", "customer_uuid": "019a1234-1000-7000-8000-000000000002", "external_id": "crm-order-1001" } ``` ::: code-group ```bash [cURL] API_BASE_URL='https://api.b.websoft.kz/api/reseller/v1' : "${RESELLER_API_TOKEN:?Set RESELLER_API_TOKEN in your environment}" : "${IDEMPOTENCY_KEY:?Set one persisted unique key per logical request}" curl --request POST "$API_BASE_URL/domains" \ --connect-timeout 5 --max-time 20 --fail-with-body \ --header "Authorization: Bearer $RESELLER_API_TOKEN" \ --header 'Accept: application/json' \ --header "Idempotency-Key: $IDEMPOTENCY_KEY" \ --header 'Content-Type: application/json' \ --data-raw '{ "quote_uuid": "019a1234-1000-7000-8000-000000000006", "customer_uuid": "019a1234-1000-7000-8000-000000000002", "external_id": "crm-order-1001" }' ``` ```php [PHP 8+] 'POST', CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true, CURLOPT_FOLLOWLOCATION => false, CURLOPT_CONNECTTIMEOUT => 5, CURLOPT_TIMEOUT => 20, CURLOPT_SSL_VERIFYPEER => true, CURLOPT_SSL_VERIFYHOST => 2, CURLOPT_POSTFIELDS => $body, CURLOPT_HEADERFUNCTION => static function (CurlHandle $curl, string $line) use (&$responseHeaders): int { if (str_starts_with($line, 'HTTP/')) { $responseHeaders = []; } elseif (str_contains($line, ':')) { [$name, $value] = explode(':', $line, 2); $responseHeaders[strtolower(trim($name))] = trim($value); } return strlen($line); }, ])) { throw new RuntimeException('Cannot configure cURL.'); } $raw = curl_exec($handle); if ($raw === false) { throw new RuntimeException('Transport failure; result may be unknown. cURL code: ' . curl_errno($handle)); } $status = (int) curl_getinfo($handle, CURLINFO_RESPONSE_CODE); } finally { unset($handle); } $requestId = $responseHeaders['x-request-id'] ?? null; $retryAfter = $responseHeaders['retry-after'] ?? null; $data = null; if ($raw !== '' && !in_array($status, [204, 205], true)) { try { $data = json_decode($raw, true, 512, JSON_THROW_ON_ERROR); } catch (JsonException $error) { if ($status >= 200 && $status < 300) { throw new RuntimeException('Unexpected non-JSON success response.', 0, $error); } } } if ($status < 200 || $status >= 300) { // Inspect $data['error']; queue 429 using $retryAfter, never create a new write key blindly. throw new RuntimeException('HTTP ' . $status . '; request_id=' . ($requestId ?? '-') . '; retry_after=' . ($retryAfter ?? '-')); } // $data contains the decoded response; 202 means accepted, not completed. echo 'HTTP ' . $status . PHP_EOL; ``` ```js [JavaScript / Node.js] // Node.js 22+; save as request.mjs. No third-party dependencies. function requiredEnv(name) { const value = process.env[name]; if (!value || /[\r\n]/u.test(value)) throw new Error('Set a valid environment variable: ' + name); return value; } const baseUrl = (process.env.API_BASE_URL || "https://api.b.websoft.kz/api/reseller/v1").replace(/\/$/u, ''); let path = "/domains"; const url = baseUrl + path; const body = `{ "quote_uuid": "019a1234-1000-7000-8000-000000000006", "customer_uuid": "019a1234-1000-7000-8000-000000000002", "external_id": "crm-order-1001" }`; const response = await fetch(url, { method: "POST", redirect: 'manual', signal: AbortSignal.timeout(20_000), headers: { Authorization: 'Bearer ' + requiredEnv('RESELLER_API_TOKEN'), Accept: 'application/json', 'Idempotency-Key': requiredEnv('IDEMPOTENCY_KEY'), "Content-Type": "application/json", }, body, }); const requestId = response.headers.get('x-request-id'); const retryAfter = response.headers.get('retry-after'); const raw = await response.text(); let data = null; if (raw && ![204, 205].includes(response.status)) { try { data = JSON.parse(raw); } catch (cause) { if (response.ok) throw new Error('Unexpected non-JSON success response.', { cause }); } } if (!response.ok) { // Inspect data?.error; schedule 429 using retryAfter. Do not generate another write key. throw new Error('HTTP ' + response.status + '; request_id=' + requestId + '; retry_after=' + retryAfter); } // A timeout may have an unknown result. No automatic mutation retry in this example. // data contains the response; 202 means accepted, not completed. console.log('HTTP', response.status); ``` ```python [Python] # Python 3.10+; standard library only. import json import os from urllib.error import HTTPError from urllib.parse import quote from urllib.request import HTTPRedirectHandler, Request, build_opener def required_env(name): value = os.environ.get(name, "") if not value or "\r" in value or "\n" in value: raise RuntimeError("Set a valid environment variable: " + name) return value class NoRedirect(HTTPRedirectHandler): def redirect_request(self, req, fp, code, msg, headers, newurl): return None base_url = os.environ.get("API_BASE_URL", "https://api.b.websoft.kz/api/reseller/v1").rstrip("/") path = "/domains" url = base_url + path headers = { "Authorization": "Bearer " + required_env("RESELLER_API_TOKEN"), "Accept": "application/json", "Idempotency-Key": required_env("IDEMPOTENCY_KEY"), "Content-Type": "application/json", } body = "{\n \"quote_uuid\": \"019a1234-1000-7000-8000-000000000006\",\n \"customer_uuid\": \"019a1234-1000-7000-8000-000000000002\",\n \"external_id\": \"crm-order-1001\"\n}".encode("utf-8") request = Request(url, data=body, headers=headers, method="POST") opener = build_opener(NoRedirect()) try: response = opener.open(request, timeout=20) except HTTPError as error: response = error # HTTP failure still has a response body and headers. # Network/timeout exceptions propagate: a write may already have been accepted. with response: status = response.status request_id = response.headers.get("X-Request-ID") retry_after = response.headers.get("Retry-After") raw = response.read() data = None if raw and status not in (204, 205): try: data = json.loads(raw) except (ValueError, UnicodeDecodeError): if 200 <= status < 300: raise RuntimeError("Unexpected non-JSON success response.") if not 200 <= status < 300: # Inspect data['error']; schedule 429 with retry_after, keeping the same persisted key. raise RuntimeError(f"HTTP {status}; request_id={request_id}; retry_after={retry_after}") # data contains the response. Do not log secrets/PII; 202 is not completion. print("HTTP", status) ``` ```go [Go] // Go 1.22+; standard library only. Save as main.go and run: go run main.go package main import ( "encoding/json" "fmt" "io" "net/http" "os" "strings" "time" ) func requiredEnv(name string) string { value := os.Getenv(name) if value == "" || strings.ContainsAny(value, "\r\n") { panic("Set a valid environment variable: " + name) } return value } func main() { baseURL := os.Getenv("API_BASE_URL") if baseURL == "" { baseURL = "https://api.b.websoft.kz/api/reseller/v1" } path := "/domains" endpoint := strings.TrimRight(baseURL, "/") + path request, err := http.NewRequest("POST", endpoint, strings.NewReader("{\n \"quote_uuid\": \"019a1234-1000-7000-8000-000000000006\",\n \"customer_uuid\": \"019a1234-1000-7000-8000-000000000002\",\n \"external_id\": \"crm-order-1001\"\n}")) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer " + requiredEnv("RESELLER_API_TOKEN")) request.Header.Set("Accept", "application/json") request.Header.Set("Idempotency-Key", requiredEnv("IDEMPOTENCY_KEY")) request.Header.Set("Content-Type", "application/json") client := &http.Client{ Timeout: 20 * time.Second, CheckRedirect: func(req *http.Request, via []*http.Request) error { return http.ErrUseLastResponse }, } response, err := client.Do(request) if err != nil { panic("Transport failure; operation result may be unknown") } defer response.Body.Close() raw, err := io.ReadAll(response.Body) if err != nil { panic("Response read failed; operation result may be unknown") } requestID := response.Header.Get("X-Request-ID") retryAfter := response.Header.Get("Retry-After") var data any if len(raw) > 0 && response.StatusCode != 204 && response.StatusCode != 205 { decoder := json.NewDecoder(strings.NewReader(string(raw))) decoder.UseNumber() // Preserve integer money/identifiers without float rounding. if err := decoder.Decode(&data); err != nil && response.StatusCode >= 200 && response.StatusCode < 300 { panic("Unexpected non-JSON success response") } } if response.StatusCode < 200 || response.StatusCode >= 300 { // Inspect data; schedule 429 using retryAfter. Never create a new key blindly. panic(fmt.Sprintf("HTTP %d; request_id=%s; retry_after=%s", response.StatusCode, requestID, retryAfter)) } // data holds the JSON value; 202 means accepted, not completed. Do not log secrets. fmt.Println("HTTP", response.StatusCode) } ``` ```java [Java] // Java 17+; standard library only. Save as RequestExample.java. // Run: java RequestExample.java import java.net.URI; import java.net.URLEncoder; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.time.Duration; public class RequestExample { private static String requiredEnv(String name) { String value = System.getenv(name); if (value == null || value.isEmpty() || value.contains("\r") || value.contains("\n")) { throw new IllegalStateException("Set a valid environment variable: " + name); } return value; } private static String envOr(String name, String fallback) { String value = System.getenv(name); return value == null || value.isEmpty() ? fallback : value; } public static void main(String[] args) throws Exception { String baseUrl = envOr("API_BASE_URL", "https://api.b.websoft.kz/api/reseller/v1").replaceAll("/+$", ""); String path = "/domains"; URI uri = URI.create(baseUrl + path); String body = "{\n \"quote_uuid\": \"019a1234-1000-7000-8000-000000000006\",\n \"customer_uuid\": \"019a1234-1000-7000-8000-000000000002\",\n \"external_id\": \"crm-order-1001\"\n}"; HttpRequest request = HttpRequest.newBuilder(uri) .timeout(Duration.ofSeconds(20)) .header("Authorization", "Bearer " + requiredEnv("RESELLER_API_TOKEN")) .header("Accept", "application/json") .header("Idempotency-Key", requiredEnv("IDEMPOTENCY_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8)) .build(); HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(5)) .followRedirects(HttpClient.Redirect.NEVER) .build(); // Reuse HttpClient in production. A timeout may mean an unknown write result. HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8)); int status = response.statusCode(); String requestId = response.headers().firstValue("X-Request-ID").orElse(""); String retryAfter = response.headers().firstValue("Retry-After").orElse(""); String responseBody = (status == 204 || status == 205) ? "" : response.body(); if (status < 200 || status >= 300) { // Decode responseBody with your JSON library; schedule 429 using retryAfter. throw new IllegalStateException("HTTP " + status + "; request_id=" + requestId + "; retry_after=" + retryAfter); } // Java SE has no JSON object mapper: pass responseBody to your project's JSON parser. // Do not parse an empty 204 body; 202 means accepted, not completed. System.out.println("HTTP " + status); } } ``` ```csharp [C# / .NET] // C# / .NET 8+ console app; standard library only. Save as Program.cs. using System; using System.Net.Http; using System.Text; using System.Text.Json; static string RequiredEnv(string name) { string? value = Environment.GetEnvironmentVariable(name); if (string.IsNullOrEmpty(value) || value.Contains('\r') || value.Contains('\n')) throw new InvalidOperationException("Set a valid environment variable: " + name); return value; } string baseUrl = (Environment.GetEnvironmentVariable("API_BASE_URL") ?? "https://api.b.websoft.kz/api/reseller/v1").TrimEnd('/'); string path = "/domains"; using var handler = new HttpClientHandler { AllowAutoRedirect = false }; using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(20) }; // Reuse HttpClient (or IHttpClientFactory) in production, not one client per request. using var request = new HttpRequestMessage(new HttpMethod("POST"), baseUrl + path); request.Headers.Add("Authorization", "Bearer " + RequiredEnv("RESELLER_API_TOKEN")); request.Headers.Add("Accept", "application/json"); request.Headers.Add("Idempotency-Key", RequiredEnv("IDEMPOTENCY_KEY")); request.Content = new StringContent("{\n \"quote_uuid\": \"019a1234-1000-7000-8000-000000000006\",\n \"customer_uuid\": \"019a1234-1000-7000-8000-000000000002\",\n \"external_id\": \"crm-order-1001\"\n}", Encoding.UTF8, "application/json"); // Transport exceptions may have an unknown result; do not issue a new mutation automatically. using var response = await client.SendAsync(request); int status = (int)response.StatusCode; string requestId = response.Headers.TryGetValues("X-Request-ID", out var ids) ? string.Join(",", ids) : ""; string retryAfter = response.Headers.TryGetValues("Retry-After", out var delays) ? string.Join(",", delays) : ""; string raw = await response.Content.ReadAsStringAsync(); JsonElement? data = null; if (raw.Length > 0 && status != 204 && status != 205) { try { using var document = JsonDocument.Parse(raw); data = document.RootElement.Clone(); } catch (JsonException) { if (response.IsSuccessStatusCode) throw; } } if (!response.IsSuccessStatusCode) { // Inspect data; schedule 429 using retryAfter and preserve the same key/body. throw new HttpRequestException($"HTTP {status}; request_id={requestId}; retry_after={retryAfter}"); } // data contains JSON, or null for 204. HTTP 202 is not completion. Console.WriteLine($"HTTP {status}"); ``` ::: #### Регистрация в aggregate-режиме ```json { "quote_uuid": "019a1234-1000-7000-8000-000000000006", "external_id": "crm-order-1001" } ``` ::: code-group ```bash [cURL] API_BASE_URL='https://api.b.websoft.kz/api/reseller/v1' : "${RESELLER_API_TOKEN:?Set RESELLER_API_TOKEN in your environment}" : "${IDEMPOTENCY_KEY:?Set one persisted unique key per logical request}" curl --request POST "$API_BASE_URL/domains" \ --connect-timeout 5 --max-time 20 --fail-with-body \ --header "Authorization: Bearer $RESELLER_API_TOKEN" \ --header 'Accept: application/json' \ --header "Idempotency-Key: $IDEMPOTENCY_KEY" \ --header 'Content-Type: application/json' \ --data-raw '{ "quote_uuid": "019a1234-1000-7000-8000-000000000006", "external_id": "crm-order-1001" }' ``` ```php [PHP 8+] 'POST', CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true, CURLOPT_FOLLOWLOCATION => false, CURLOPT_CONNECTTIMEOUT => 5, CURLOPT_TIMEOUT => 20, CURLOPT_SSL_VERIFYPEER => true, CURLOPT_SSL_VERIFYHOST => 2, CURLOPT_POSTFIELDS => $body, CURLOPT_HEADERFUNCTION => static function (CurlHandle $curl, string $line) use (&$responseHeaders): int { if (str_starts_with($line, 'HTTP/')) { $responseHeaders = []; } elseif (str_contains($line, ':')) { [$name, $value] = explode(':', $line, 2); $responseHeaders[strtolower(trim($name))] = trim($value); } return strlen($line); }, ])) { throw new RuntimeException('Cannot configure cURL.'); } $raw = curl_exec($handle); if ($raw === false) { throw new RuntimeException('Transport failure; result may be unknown. cURL code: ' . curl_errno($handle)); } $status = (int) curl_getinfo($handle, CURLINFO_RESPONSE_CODE); } finally { unset($handle); } $requestId = $responseHeaders['x-request-id'] ?? null; $retryAfter = $responseHeaders['retry-after'] ?? null; $data = null; if ($raw !== '' && !in_array($status, [204, 205], true)) { try { $data = json_decode($raw, true, 512, JSON_THROW_ON_ERROR); } catch (JsonException $error) { if ($status >= 200 && $status < 300) { throw new RuntimeException('Unexpected non-JSON success response.', 0, $error); } } } if ($status < 200 || $status >= 300) { // Inspect $data['error']; queue 429 using $retryAfter, never create a new write key blindly. throw new RuntimeException('HTTP ' . $status . '; request_id=' . ($requestId ?? '-') . '; retry_after=' . ($retryAfter ?? '-')); } // $data contains the decoded response; 202 means accepted, not completed. echo 'HTTP ' . $status . PHP_EOL; ``` ```js [JavaScript / Node.js] // Node.js 22+; save as request.mjs. No third-party dependencies. function requiredEnv(name) { const value = process.env[name]; if (!value || /[\r\n]/u.test(value)) throw new Error('Set a valid environment variable: ' + name); return value; } const baseUrl = (process.env.API_BASE_URL || "https://api.b.websoft.kz/api/reseller/v1").replace(/\/$/u, ''); let path = "/domains"; const url = baseUrl + path; const body = `{ "quote_uuid": "019a1234-1000-7000-8000-000000000006", "external_id": "crm-order-1001" }`; const response = await fetch(url, { method: "POST", redirect: 'manual', signal: AbortSignal.timeout(20_000), headers: { Authorization: 'Bearer ' + requiredEnv('RESELLER_API_TOKEN'), Accept: 'application/json', 'Idempotency-Key': requiredEnv('IDEMPOTENCY_KEY'), "Content-Type": "application/json", }, body, }); const requestId = response.headers.get('x-request-id'); const retryAfter = response.headers.get('retry-after'); const raw = await response.text(); let data = null; if (raw && ![204, 205].includes(response.status)) { try { data = JSON.parse(raw); } catch (cause) { if (response.ok) throw new Error('Unexpected non-JSON success response.', { cause }); } } if (!response.ok) { // Inspect data?.error; schedule 429 using retryAfter. Do not generate another write key. throw new Error('HTTP ' + response.status + '; request_id=' + requestId + '; retry_after=' + retryAfter); } // A timeout may have an unknown result. No automatic mutation retry in this example. // data contains the response; 202 means accepted, not completed. console.log('HTTP', response.status); ``` ```python [Python] # Python 3.10+; standard library only. import json import os from urllib.error import HTTPError from urllib.parse import quote from urllib.request import HTTPRedirectHandler, Request, build_opener def required_env(name): value = os.environ.get(name, "") if not value or "\r" in value or "\n" in value: raise RuntimeError("Set a valid environment variable: " + name) return value class NoRedirect(HTTPRedirectHandler): def redirect_request(self, req, fp, code, msg, headers, newurl): return None base_url = os.environ.get("API_BASE_URL", "https://api.b.websoft.kz/api/reseller/v1").rstrip("/") path = "/domains" url = base_url + path headers = { "Authorization": "Bearer " + required_env("RESELLER_API_TOKEN"), "Accept": "application/json", "Idempotency-Key": required_env("IDEMPOTENCY_KEY"), "Content-Type": "application/json", } body = "{\n \"quote_uuid\": \"019a1234-1000-7000-8000-000000000006\",\n \"external_id\": \"crm-order-1001\"\n}".encode("utf-8") request = Request(url, data=body, headers=headers, method="POST") opener = build_opener(NoRedirect()) try: response = opener.open(request, timeout=20) except HTTPError as error: response = error # HTTP failure still has a response body and headers. # Network/timeout exceptions propagate: a write may already have been accepted. with response: status = response.status request_id = response.headers.get("X-Request-ID") retry_after = response.headers.get("Retry-After") raw = response.read() data = None if raw and status not in (204, 205): try: data = json.loads(raw) except (ValueError, UnicodeDecodeError): if 200 <= status < 300: raise RuntimeError("Unexpected non-JSON success response.") if not 200 <= status < 300: # Inspect data['error']; schedule 429 with retry_after, keeping the same persisted key. raise RuntimeError(f"HTTP {status}; request_id={request_id}; retry_after={retry_after}") # data contains the response. Do not log secrets/PII; 202 is not completion. print("HTTP", status) ``` ```go [Go] // Go 1.22+; standard library only. Save as main.go and run: go run main.go package main import ( "encoding/json" "fmt" "io" "net/http" "os" "strings" "time" ) func requiredEnv(name string) string { value := os.Getenv(name) if value == "" || strings.ContainsAny(value, "\r\n") { panic("Set a valid environment variable: " + name) } return value } func main() { baseURL := os.Getenv("API_BASE_URL") if baseURL == "" { baseURL = "https://api.b.websoft.kz/api/reseller/v1" } path := "/domains" endpoint := strings.TrimRight(baseURL, "/") + path request, err := http.NewRequest("POST", endpoint, strings.NewReader("{\n \"quote_uuid\": \"019a1234-1000-7000-8000-000000000006\",\n \"external_id\": \"crm-order-1001\"\n}")) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer " + requiredEnv("RESELLER_API_TOKEN")) request.Header.Set("Accept", "application/json") request.Header.Set("Idempotency-Key", requiredEnv("IDEMPOTENCY_KEY")) request.Header.Set("Content-Type", "application/json") client := &http.Client{ Timeout: 20 * time.Second, CheckRedirect: func(req *http.Request, via []*http.Request) error { return http.ErrUseLastResponse }, } response, err := client.Do(request) if err != nil { panic("Transport failure; operation result may be unknown") } defer response.Body.Close() raw, err := io.ReadAll(response.Body) if err != nil { panic("Response read failed; operation result may be unknown") } requestID := response.Header.Get("X-Request-ID") retryAfter := response.Header.Get("Retry-After") var data any if len(raw) > 0 && response.StatusCode != 204 && response.StatusCode != 205 { decoder := json.NewDecoder(strings.NewReader(string(raw))) decoder.UseNumber() // Preserve integer money/identifiers without float rounding. if err := decoder.Decode(&data); err != nil && response.StatusCode >= 200 && response.StatusCode < 300 { panic("Unexpected non-JSON success response") } } if response.StatusCode < 200 || response.StatusCode >= 300 { // Inspect data; schedule 429 using retryAfter. Never create a new key blindly. panic(fmt.Sprintf("HTTP %d; request_id=%s; retry_after=%s", response.StatusCode, requestID, retryAfter)) } // data holds the JSON value; 202 means accepted, not completed. Do not log secrets. fmt.Println("HTTP", response.StatusCode) } ``` ```java [Java] // Java 17+; standard library only. Save as RequestExample.java. // Run: java RequestExample.java import java.net.URI; import java.net.URLEncoder; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.time.Duration; public class RequestExample { private static String requiredEnv(String name) { String value = System.getenv(name); if (value == null || value.isEmpty() || value.contains("\r") || value.contains("\n")) { throw new IllegalStateException("Set a valid environment variable: " + name); } return value; } private static String envOr(String name, String fallback) { String value = System.getenv(name); return value == null || value.isEmpty() ? fallback : value; } public static void main(String[] args) throws Exception { String baseUrl = envOr("API_BASE_URL", "https://api.b.websoft.kz/api/reseller/v1").replaceAll("/+$", ""); String path = "/domains"; URI uri = URI.create(baseUrl + path); String body = "{\n \"quote_uuid\": \"019a1234-1000-7000-8000-000000000006\",\n \"external_id\": \"crm-order-1001\"\n}"; HttpRequest request = HttpRequest.newBuilder(uri) .timeout(Duration.ofSeconds(20)) .header("Authorization", "Bearer " + requiredEnv("RESELLER_API_TOKEN")) .header("Accept", "application/json") .header("Idempotency-Key", requiredEnv("IDEMPOTENCY_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8)) .build(); HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(5)) .followRedirects(HttpClient.Redirect.NEVER) .build(); // Reuse HttpClient in production. A timeout may mean an unknown write result. HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8)); int status = response.statusCode(); String requestId = response.headers().firstValue("X-Request-ID").orElse(""); String retryAfter = response.headers().firstValue("Retry-After").orElse(""); String responseBody = (status == 204 || status == 205) ? "" : response.body(); if (status < 200 || status >= 300) { // Decode responseBody with your JSON library; schedule 429 using retryAfter. throw new IllegalStateException("HTTP " + status + "; request_id=" + requestId + "; retry_after=" + retryAfter); } // Java SE has no JSON object mapper: pass responseBody to your project's JSON parser. // Do not parse an empty 204 body; 202 means accepted, not completed. System.out.println("HTTP " + status); } } ``` ```csharp [C# / .NET] // C# / .NET 8+ console app; standard library only. Save as Program.cs. using System; using System.Net.Http; using System.Text; using System.Text.Json; static string RequiredEnv(string name) { string? value = Environment.GetEnvironmentVariable(name); if (string.IsNullOrEmpty(value) || value.Contains('\r') || value.Contains('\n')) throw new InvalidOperationException("Set a valid environment variable: " + name); return value; } string baseUrl = (Environment.GetEnvironmentVariable("API_BASE_URL") ?? "https://api.b.websoft.kz/api/reseller/v1").TrimEnd('/'); string path = "/domains"; using var handler = new HttpClientHandler { AllowAutoRedirect = false }; using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(20) }; // Reuse HttpClient (or IHttpClientFactory) in production, not one client per request. using var request = new HttpRequestMessage(new HttpMethod("POST"), baseUrl + path); request.Headers.Add("Authorization", "Bearer " + RequiredEnv("RESELLER_API_TOKEN")); request.Headers.Add("Accept", "application/json"); request.Headers.Add("Idempotency-Key", RequiredEnv("IDEMPOTENCY_KEY")); request.Content = new StringContent("{\n \"quote_uuid\": \"019a1234-1000-7000-8000-000000000006\",\n \"external_id\": \"crm-order-1001\"\n}", Encoding.UTF8, "application/json"); // Transport exceptions may have an unknown result; do not issue a new mutation automatically. using var response = await client.SendAsync(request); int status = (int)response.StatusCode; string requestId = response.Headers.TryGetValues("X-Request-ID", out var ids) ? string.Join(",", ids) : ""; string retryAfter = response.Headers.TryGetValues("Retry-After", out var delays) ? string.Join(",", delays) : ""; string raw = await response.Content.ReadAsStringAsync(); JsonElement? data = null; if (raw.Length > 0 && status != 204 && status != 205) { try { using var document = JsonDocument.Parse(raw); data = document.RootElement.Clone(); } catch (JsonException) { if (response.IsSuccessStatusCode) throw; } } if (!response.IsSuccessStatusCode) { // Inspect data; schedule 429 using retryAfter and preserve the same key/body. throw new HttpRequestException($"HTTP {status}; request_id={requestId}; retry_after={retryAfter}"); } // data contains JSON, or null for 204. HTTP 202 is not completion. Console.WriteLine($"HTTP {status}"); ``` ::: ## Ответы ### Условия ошибок и восстановление | HTTP | Код | Когда возникает | Что делать | | --- | --- | --- | --- | | 401 | `unauthenticated` | Нет действительного Bearer API-ключа. | Проверьте ключ, срок действия и окружение; не повторяйте бесконечно. | | 403 | `forbidden` | Нет требуемого scope, провайдер/ключ/доступ запрещён. | Проверьте настройки провайдера и scopes ключа. | | 429 | `rate_limit_exceeded` | Исчерпан общий лимит ключа. | Выждите Retry-After; повторы выполняйте с backoff и jitter. | | 500 | `internal_error` | Необработанный сбой инфраструктуры или внешнего драйвера. | Сохраните request_id. Для изменения сначала проверьте существующую задачу; не генерируйте новый ключ вслепую. Формат ответа reverse proxy может отличаться от API. | | 404 | `resource_not_found` | UUID не найден у этого провайдера/окружения, либо запись удалена/скрыта migration hold. | Проверьте UUID, test/live и принадлежность. Не пытайтесь получить ресурс чужого провайдера. | | 422 | `validation_failed` | Quote истёк/использован/другого окружения; неверная операция, срок, зона, неактивные/чужие контакты; повтор external_id; недостаточно оптового баланса. | Исправьте причину, при необходимости пополните баланс и получите новый quote. Проверьте исходный заказ перед повтором. | | 409 | `conflict` | Ключ уже используется другим запросом или исходный запрос ещё выполняется. | Не изменяйте тело при повторе. Проверьте исходную операцию; используйте новый ключ только для нового намеренного действия. | | 422 | `validation_failed` | Невалидный JSON-пayload/поле или отсутствует Idempotency-Key. | Исправьте данные по error.details; для изменённого запроса создайте новый ключ. | | 404 | `resource_not_found` | Reseller API глобально выключен конфигурацией. | Уточните base URL и включение API у оператора. | ### HTTP 201 Запись создана; проверяйте прикладной status. **Заголовок `Idempotency-Replayed`**: Присутствует со значением true при возврате сохранённого HTTP-ответа. | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | string | Да | const: "true" | | **Content-Type:** `application/json` | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | object | Да | required: ["data"] | Успешный ответ. Схема: CoreOrderEnvelope | | `$.data` | object | Да | required: ["uuid","external_id","customer_uuid","number","status","currency","total_minor","submitted_at","paid_at","completed_at","failed_at","failure_reason","items","invoice","created_at","updated_at"] | Заказ принят не равнозначно домен зарегистрирован. В external checkout выставляется оплаченный счёт и планируется асинхронное исполнение; дальнейшее состояние отслеживайте через заказ/услугу и webhooks. Схема: CoreOrder | | `$.data.uuid` | string | Да | format: "uuid" | UUID объекта. | | `$.data.external_id` | string / null | Да | | ID заказа внешнего биллинга. | | `$.data.customer_uuid` | string / null | Да | format: "uuid" | UUID покупателя. | | `$.data.number` | string | Да | | Номер заказа. | | `$.data.status` | string | Да | enum: "draft", "submitted", "payment_authorized", "registration_processing", "registry_pending", "paid", "active", "completed", "registration_failed", "cancelled", "refunded" | Состояние заказа. submitted: выставлен счёт; paid: оплата зафиксирована; registration_processing/registry_pending: работа с реестром; active/completed: исполнен; registration_failed: регистрация неуспешна. Даты и invoice отражают отдельные стадии, HTTP 201 не терминальный статус. | | `$.data.currency` | string | Да | | Валюта. | | `$.data.total_minor` | integer | Да | format: "int64" | Сумма. В минимальных единицах валюты, без десятичных дробей. | | `$.data.submitted_at` | string / null | Да | format: "date-time" | Подан. | | `$.data.paid_at` | string / null | Да | format: "date-time" | Оплачен. | | `$.data.completed_at` | string / null | Да | format: "date-time" | Завершён. | | `$.data.failed_at` | string / null | Да | format: "date-time" | Ошибка. | | `$.data.failure_reason` | string / null | Да | | Причина ошибки; не используйте текст как стабильный машинный код. | | `$.data.items` | array | Да | | Строки. | | `$.data.items[]` | object | Да | required: ["uuid","type","name","quantity","unit_price_minor","total_minor","currency","service_uuid","service_external_id"] | Строка заказа. Схема: CoreOrderItem | | `$.data.items[].uuid` | string | Да | format: "uuid" | UUID объекта. | | `$.data.items[].type` | string | Да | | Тип услуги, например domain/hosting. | | `$.data.items[].name` | string | Да | | Название. | | `$.data.items[].quantity` | integer | Да | format: "int64" | Количество. | | `$.data.items[].unit_price_minor` | integer | Да | format: "int64" | Цена единицы. В минимальных единицах валюты, без десятичных дробей. | | `$.data.items[].total_minor` | integer | Да | format: "int64" | Итого. В минимальных единицах валюты, без десятичных дробей. | | `$.data.items[].currency` | string | Да | | Валюта. | | `$.data.items[].service_uuid` | string / null | Да | format: "uuid" | UUID созданной услуги. Отличается от domain UUID. | | `$.data.items[].service_external_id` | string / null | Да | | external_id из payload строки котировки. | | `$.data.invoice` | anyOf | Да | | Счёт или null. | | `$.data.invoice (anyOf 1)` | object | Да | required: ["uuid","number","status","currency","total_minor","paid_minor","payment_collected_by_platform"] | Связанный счёт. Схема: CoreInvoice | | `$.data.invoice (anyOf 1).uuid` | string | Да | format: "uuid" | UUID объекта. | | `$.data.invoice (anyOf 1).number` | string | Да | | Номер. | | `$.data.invoice (anyOf 1).status` | string | Да | | Состояние счёта, например issued/paid/cancelled. | | `$.data.invoice (anyOf 1).currency` | string | Да | | Валюта. | | `$.data.invoice (anyOf 1).total_minor` | integer | Да | format: "int64" | Сумма. В минимальных единицах валюты, без десятичных дробей. | | `$.data.invoice (anyOf 1).paid_minor` | integer | Да | format: "int64" | Оплачено. В минимальных единицах валюты, без десятичных дробей. | | `$.data.invoice (anyOf 1).payment_collected_by_platform` | boolean | Да | | false при external checkout: оплату клиента принимает реселлер. paid не означает списание с карты платформой. | | `$.data.invoice (anyOf 2)` | null | Да | | | | `$.data.created_at` | string / null | Да | format: "date-time" | Создан. | | `$.data.updated_at` | string / null | Да | format: "date-time" | Изменён. | #### Заказ при внешнем checkout; сумма только пример, цену берите из quote (201) ```json { "data": { "uuid": "019a1234-1000-7000-8000-000000000008", "external_id": "crm-order-1001", "customer_uuid": "019a1234-1000-7000-8000-000000000002", "number": "ORD-2026-1001", "status": "paid", "currency": "KZT", "total_minor": 500000, "submitted_at": "2026-10-05T08:00:00+00:00", "paid_at": "2026-10-05T08:00:00+00:00", "completed_at": null, "failed_at": null, "failure_reason": null, "items": [ { "uuid": "019a1234-1000-7000-8000-000000000011", "type": "domain", "name": "example.kz", "quantity": 1, "unit_price_minor": 500000, "total_minor": 500000, "currency": "KZT", "service_uuid": "019a1234-1000-7000-8000-000000000005", "service_external_id": "crm-domain-1001" } ], "invoice": { "uuid": "019a1234-1000-7000-8000-000000000009", "number": "INV-2026-1001", "status": "paid", "currency": "KZT", "total_minor": 500000, "paid_minor": 500000, "payment_collected_by_platform": false }, "created_at": "2026-10-05T08:00:00+00:00", "updated_at": "2026-10-05T08:00:00+00:00" } } ``` #### Заказ с оплатой через платформу; регистрация ещё не выполнена (201) ```json { "data": { "uuid": "019a1234-1000-7000-8000-000000000008", "external_id": "crm-order-1001", "customer_uuid": "019a1234-1000-7000-8000-000000000002", "number": "ORD-2026-1001", "status": "submitted", "currency": "KZT", "total_minor": 500000, "submitted_at": "2026-10-05T08:00:00+00:00", "paid_at": null, "completed_at": null, "failed_at": null, "failure_reason": null, "items": [ { "uuid": "019a1234-1000-7000-8000-000000000011", "type": "domain", "name": "example.kz", "quantity": 1, "unit_price_minor": 500000, "total_minor": 500000, "currency": "KZT", "service_uuid": "019a1234-1000-7000-8000-000000000005", "service_external_id": "crm-domain-1001" } ], "invoice": { "uuid": "019a1234-1000-7000-8000-000000000009", "number": "INV-2026-1001", "status": "issued", "currency": "KZT", "total_minor": 500000, "paid_minor": 0, "payment_collected_by_platform": true }, "created_at": "2026-10-05T08:00:00+00:00", "updated_at": "2026-10-05T08:00:00+00:00" } } ``` ### HTTP 401 Отсутствует, неверен, отозван или просрочен Bearer-ключ. **Заголовок `X-Request-ID`**: UUID текущего запроса. Корректный входной X-Request-ID принимается в нижнем регистре, иначе создаётся новый. Не гарантирован для proxy/неизвестного маршрута. | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | string | Да | format: "uuid" | | **Content-Type:** `application/json` | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | object | Да | required: ["error"] | Собственный JSON-конверт API, не RFC 9457. Структура и code не зависят от языка; message и details предназначены человеку. До выбора маршрута и на proxy этот конверт не гарантирован. Схема: ErrorEnvelope | | `$.error` | object | Да | required: ["code","message","details","request_id"] | | | `$.error.code` | string | Да | | Машинный код; не извлекайте причину из message. | | `$.error.message` | string | Да | | Человекочитаемое, частично локализуемое сообщение; не стабильный идентификатор ошибки. | | `$.error.details` | oneOf | Да | | Без подробностей возвращается [], не null и не {}. Валидация: {поле:[сообщения]}. Квота: {retry_after:секунды}. | | `$.error.details (oneOf 1)` | array | Да | maxItems: 0 | | | `$.error.details (oneOf 2)` | object | Да | | | | `$.error.details (oneOf 2).*` | array | Нет | | | | `$.error.details (oneOf 2).*[]` | string | Да | | | | `$.error.details (oneOf 3)` | object | Да | required: ["retry_after"]; Дополнительные поля запрещены | | | `$.error.details (oneOf 3).retry_after` | integer | Да | minimum: 0 | | | `$.error.request_id` | string / null | Да | format: "uuid" | UUID для диагностики или null без контекста. При HTTP replay тело может содержать исходный ID, заголовок X-Request-ID относится к текущей попытке. | #### default (401) ```json { "error": { "code": "unauthenticated", "message": "API credential is missing or invalid.", "details": [], "request_id": "11111111-1111-4111-8111-111111111111" } } ``` ### HTTP 403 Нет scope, IP не разрешён, тариф/режим/статус реселлера запрещает действие либо test-ключ обращается к live-only ресурсу. **Заголовок `X-Request-ID`**: UUID текущего запроса. Корректный входной X-Request-ID принимается в нижнем регистре, иначе создаётся новый. Не гарантирован для proxy/неизвестного маршрута. | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | string | Да | format: "uuid" | | **Content-Type:** `application/json` | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | object | Да | required: ["error"] | Собственный JSON-конверт API, не RFC 9457. Структура и code не зависят от языка; message и details предназначены человеку. До выбора маршрута и на proxy этот конверт не гарантирован. Схема: ErrorEnvelope | | `$.error` | object | Да | required: ["code","message","details","request_id"] | | | `$.error.code` | string | Да | | Машинный код; не извлекайте причину из message. | | `$.error.message` | string | Да | | Человекочитаемое, частично локализуемое сообщение; не стабильный идентификатор ошибки. | | `$.error.details` | oneOf | Да | | Без подробностей возвращается [], не null и не {}. Валидация: {поле:[сообщения]}. Квота: {retry_after:секунды}. | | `$.error.details (oneOf 1)` | array | Да | maxItems: 0 | | | `$.error.details (oneOf 2)` | object | Да | | | | `$.error.details (oneOf 2).*` | array | Нет | | | | `$.error.details (oneOf 2).*[]` | string | Да | | | | `$.error.details (oneOf 3)` | object | Да | required: ["retry_after"]; Дополнительные поля запрещены | | | `$.error.details (oneOf 3).retry_after` | integer | Да | minimum: 0 | | | `$.error.request_id` | string / null | Да | format: "uuid" | UUID для диагностики или null без контекста. При HTTP replay тело может содержать исходный ID, заголовок X-Request-ID относится к текущей попытке. | #### default (403) ```json { "error": { "code": "forbidden", "message": "Source IP address is not allowed.", "details": [], "request_id": "11111111-1111-4111-8111-111111111111" } } ``` #### supportTest (403) ```json { "error": { "code": "forbidden", "message": "Support is available only to live credentials.", "details": [], "request_id": "11111111-1111-4111-8111-111111111111" } } ``` ### HTTP 404 Ресурс недоступен в контексте или весь reseller API отключён. Не отличайте чужое от отсутствующего. **Заголовок `X-Request-ID`**: UUID текущего запроса. Корректный входной X-Request-ID принимается в нижнем регистре, иначе создаётся новый. Не гарантирован для proxy/неизвестного маршрута. | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | string | Да | format: "uuid" | | **Content-Type:** `application/json` | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | object | Да | required: ["error"] | Собственный JSON-конверт API, не RFC 9457. Структура и code не зависят от языка; message и details предназначены человеку. До выбора маршрута и на proxy этот конверт не гарантирован. Схема: ErrorEnvelope | | `$.error` | object | Да | required: ["code","message","details","request_id"] | | | `$.error.code` | string | Да | | Машинный код; не извлекайте причину из message. | | `$.error.message` | string | Да | | Человекочитаемое, частично локализуемое сообщение; не стабильный идентификатор ошибки. | | `$.error.details` | oneOf | Да | | Без подробностей возвращается [], не null и не {}. Валидация: {поле:[сообщения]}. Квота: {retry_after:секунды}. | | `$.error.details (oneOf 1)` | array | Да | maxItems: 0 | | | `$.error.details (oneOf 2)` | object | Да | | | | `$.error.details (oneOf 2).*` | array | Нет | | | | `$.error.details (oneOf 2).*[]` | string | Да | | | | `$.error.details (oneOf 3)` | object | Да | required: ["retry_after"]; Дополнительные поля запрещены | | | `$.error.details (oneOf 3).retry_after` | integer | Да | minimum: 0 | | | `$.error.request_id` | string / null | Да | format: "uuid" | UUID для диагностики или null без контекста. При HTTP replay тело может содержать исходный ID, заголовок X-Request-ID относится к текущей попытке. | #### default (404) ```json { "error": { "code": "resource_not_found", "message": "Not Found", "details": [], "request_id": "11111111-1111-4111-8111-111111111111" } } ``` ### HTTP 409 Конфликт ключа идемпотентности или состояния. Устраните причину. **Заголовок `X-Request-ID`**: UUID текущего запроса. Корректный входной X-Request-ID принимается в нижнем регистре, иначе создаётся новый. Не гарантирован для proxy/неизвестного маршрута. | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | string | Да | format: "uuid" | | **Content-Type:** `application/json` | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | object | Да | required: ["error"] | Собственный JSON-конверт API, не RFC 9457. Структура и code не зависят от языка; message и details предназначены человеку. До выбора маршрута и на proxy этот конверт не гарантирован. Схема: ErrorEnvelope | | `$.error` | object | Да | required: ["code","message","details","request_id"] | | | `$.error.code` | string | Да | | Машинный код; не извлекайте причину из message. | | `$.error.message` | string | Да | | Человекочитаемое, частично локализуемое сообщение; не стабильный идентификатор ошибки. | | `$.error.details` | oneOf | Да | | Без подробностей возвращается [], не null и не {}. Валидация: {поле:[сообщения]}. Квота: {retry_after:секунды}. | | `$.error.details (oneOf 1)` | array | Да | maxItems: 0 | | | `$.error.details (oneOf 2)` | object | Да | | | | `$.error.details (oneOf 2).*` | array | Нет | | | | `$.error.details (oneOf 2).*[]` | string | Да | | | | `$.error.details (oneOf 3)` | object | Да | required: ["retry_after"]; Дополнительные поля запрещены | | | `$.error.details (oneOf 3).retry_after` | integer | Да | minimum: 0 | | | `$.error.request_id` | string / null | Да | format: "uuid" | UUID для диагностики или null без контекста. При HTTP replay тело может содержать исходный ID, заголовок X-Request-ID относится к текущей попытке. | #### default (409) ```json { "error": { "code": "conflict", "message": "A request with this Idempotency-Key is already processing.", "details": [], "request_id": "11111111-1111-4111-8111-111111111111" } } ``` #### changedRequest (409) ```json { "error": { "code": "conflict", "message": "Idempotency-Key was already used with a different request.", "details": [], "request_id": "11111111-1111-4111-8111-111111111111" } } ``` ### HTTP 422 Ошибка данных или обязательного заголовка. details может быть []. **Заголовок `X-Request-ID`**: UUID текущего запроса. Корректный входной X-Request-ID принимается в нижнем регистре, иначе создаётся новый. Не гарантирован для proxy/неизвестного маршрута. | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | string | Да | format: "uuid" | | **Content-Type:** `application/json` | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | object | Да | required: ["error"] | Собственный JSON-конверт API, не RFC 9457. Структура и code не зависят от языка; message и details предназначены человеку. До выбора маршрута и на proxy этот конверт не гарантирован. Схема: ErrorEnvelope | | `$.error` | object | Да | required: ["code","message","details","request_id"] | | | `$.error.code` | string | Да | | Машинный код; не извлекайте причину из message. | | `$.error.message` | string | Да | | Человекочитаемое, частично локализуемое сообщение; не стабильный идентификатор ошибки. | | `$.error.details` | oneOf | Да | | Без подробностей возвращается [], не null и не {}. Валидация: {поле:[сообщения]}. Квота: {retry_after:секунды}. | | `$.error.details (oneOf 1)` | array | Да | maxItems: 0 | | | `$.error.details (oneOf 2)` | object | Да | | | | `$.error.details (oneOf 2).*` | array | Нет | | | | `$.error.details (oneOf 2).*[]` | string | Да | | | | `$.error.details (oneOf 3)` | object | Да | required: ["retry_after"]; Дополнительные поля запрещены | | | `$.error.details (oneOf 3).retry_after` | integer | Да | minimum: 0 | | | `$.error.request_id` | string / null | Да | format: "uuid" | UUID для диагностики или null без контекста. При HTTP replay тело может содержать исходный ID, заголовок X-Request-ID относится к текущей попытке. | #### default (422) ```json { "error": { "code": "validation_failed", "message": "A valid Idempotency-Key header is required.", "details": [], "request_id": "11111111-1111-4111-8111-111111111111" } } ``` #### fields (422) ```json { "error": { "code": "validation_failed", "message": "The name field is required.", "details": { "name": [ "The name field is required." ] }, "request_id": "11111111-1111-4111-8111-111111111111" } } ``` ### HTTP 429 Квота API-ключа исчерпана. Ждите Retry-After. Собственный 429 не содержит X-RateLimit-Limit/Remaining/Reset. **Заголовок `X-Request-ID`**: UUID текущего запроса. Корректный входной X-Request-ID принимается в нижнем регистре, иначе создаётся новый. Не гарантирован для proxy/неизвестного маршрута. | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | string | Да | format: "uuid" | | **Заголовок `Retry-After`**: На 429 API: целые секунды до сброса окна, не дата/Unix timestamp. При 0 добавьте jitter. Proxy может вернуть HTTP-date. | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | string | Да | pattern: "^[0-9]+$" | | ```text Retry-After: 42 ``` **Content-Type:** `application/json` | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | object | Да | required: ["error"] | Собственный JSON-конверт API, не RFC 9457. Структура и code не зависят от языка; message и details предназначены человеку. До выбора маршрута и на proxy этот конверт не гарантирован. Схема: ErrorEnvelope | | `$.error` | object | Да | required: ["code","message","details","request_id"] | | | `$.error.code` | string | Да | | Машинный код; не извлекайте причину из message. | | `$.error.message` | string | Да | | Человекочитаемое, частично локализуемое сообщение; не стабильный идентификатор ошибки. | | `$.error.details` | oneOf | Да | | Без подробностей возвращается [], не null и не {}. Валидация: {поле:[сообщения]}. Квота: {retry_after:секунды}. | | `$.error.details (oneOf 1)` | array | Да | maxItems: 0 | | | `$.error.details (oneOf 2)` | object | Да | | | | `$.error.details (oneOf 2).*` | array | Нет | | | | `$.error.details (oneOf 2).*[]` | string | Да | | | | `$.error.details (oneOf 3)` | object | Да | required: ["retry_after"]; Дополнительные поля запрещены | | | `$.error.details (oneOf 3).retry_after` | integer | Да | minimum: 0 | | | `$.error.request_id` | string / null | Да | format: "uuid" | UUID для диагностики или null без контекста. При HTTP replay тело может содержать исходный ID, заголовок X-Request-ID относится к текущей попытке. | #### default (429) ```json { "error": { "code": "rate_limit_exceeded", "message": "API rate limit exceeded.", "details": { "retry_after": 42 }, "request_id": "11111111-1111-4111-8111-111111111111" } } ``` ### HTTP 500 Этот HTTP-ответ не определяет результат записи. Сначала сверка; повтор только с прежним ключом и точным телом. **Заголовок `X-Request-ID`**: UUID текущего запроса. Корректный входной X-Request-ID принимается в нижнем регистре, иначе создаётся новый. Не гарантирован для proxy/неизвестного маршрута. | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | string | Да | format: "uuid" | | **Content-Type:** `application/json` | Поле | Тип | Обязательно в родителе | Ограничения | Описание | | --- | --- | --- | --- | --- | | `$` | object | Да | required: ["error"] | Собственный JSON-конверт API, не RFC 9457. Структура и code не зависят от языка; message и details предназначены человеку. До выбора маршрута и на proxy этот конверт не гарантирован. Схема: ErrorEnvelope | | `$.error` | object | Да | required: ["code","message","details","request_id"] | | | `$.error.code` | string | Да | | Машинный код; не извлекайте причину из message. | | `$.error.message` | string | Да | | Человекочитаемое, частично локализуемое сообщение; не стабильный идентификатор ошибки. | | `$.error.details` | oneOf | Да | | Без подробностей возвращается [], не null и не {}. Валидация: {поле:[сообщения]}. Квота: {retry_after:секунды}. | | `$.error.details (oneOf 1)` | array | Да | maxItems: 0 | | | `$.error.details (oneOf 2)` | object | Да | | | | `$.error.details (oneOf 2).*` | array | Нет | | | | `$.error.details (oneOf 2).*[]` | string | Да | | | | `$.error.details (oneOf 3)` | object | Да | required: ["retry_after"]; Дополнительные поля запрещены | | | `$.error.details (oneOf 3).retry_after` | integer | Да | minimum: 0 | | | `$.error.request_id` | string / null | Да | format: "uuid" | UUID для диагностики или null без контекста. При HTTP replay тело может содержать исходный ID, заголовок X-Request-ID относится к текущей попытке. | #### default (500) ```json { "error": { "code": "internal_error", "message": "The request could not be completed.", "details": [], "request_id": "11111111-1111-4111-8111-111111111111" } } ``` ## Дополнительные примеры из контракта ### cURL ```bash BASE_URL='https://api.b.websoft.kz/api/reseller/v1' # BASE_URL включает /api/reseller/v1. Подставьте реальные UUID своего окружения. # Для нового намеренного действия задайте новый IDEMPOTENCY_KEY; для повтора сохраните прежний. curl --request POST "$BASE_URL/domains" \ --header "Authorization: Bearer $RESELLER_API_TOKEN" \ --header "Accept: application/json" \ --header "Idempotency-Key: $IDEMPOTENCY_KEY" \ --header "Content-Type: application/json" \ --data-raw '{ "quote_uuid": "019a1234-1000-7000-8000-000000000006", "customer_uuid": "019a1234-1000-7000-8000-000000000002", "external_id": "crm-order-1001" }' ``` ## Машиночитаемый контракт [OpenAPI JSON](/openapi.json) · [OpenAPI YAML](/reseller-api-openapi.yaml) · Markdown этой операции ::: details Источники проверки контракта - `routes/api/reseller/v1.php` - `app/Application/ResellerApi/V1/Controller/OrderController.php` :::