# Residential mit Guthaben kaufen `POST /account/api/v1/residential/orders/create` ## Autorisierung `Authorization: Bearer YOUR_ARNPROXY_API_KEY` `Accept: application/json` Erforderliche Berechtigung: `purchases` `Content-Type: application/json` `Idempotency-Key` · 16–100 Buchstaben, Ziffern, _ oder -. Für denselben Vorgang speichern und wiederverwenden. ## Parameter | Name | Typ | Erforderlich / Bedingt | Standardwert | Beschreibung | |---|---|---|---|---| | `Idempotency-Key` (header) | string | Erforderlich | — | 16–100 Buchstaben/Ziffern/_/-. Für Vorgang und Status denselben Wert behalten; nicht mit anderem Inhalt wiederverwenden. | | `mode` (body) | string | Erforderlich | — | new erstellt ein Paket; topup fügt einem eigenen Paket GB hinzu. | | `time_id` (body) | integer | Erforderlich | — | Laufzeit-/GB-Plan-ID aus passendem Katalog/options, keine Tages- oder GB-Anzahl. | | `location_id` (body) | integer | Bedingt | — | Nur für mode=new erforderlich; bei topup verboten. | | `package_id` (body) | integer | Bedingt | — | Nur für mode=topup erforderlich; bei new verboten. | | `promo_code` (body) | string | Optional | `""` | Optionaler Aktionscode, höchstens 100 Bytes. Zwischen Preisabfrage und Kauf/Verlängerung unverändert lassen. | | `currency` (body) | string | Erforderlich | — | TRY oder USD aus demselben Angebot; muss zur Kontowährung passen. | | `expected_total_minor` (body) | integer | Erforderlich | — | total_minor desselben Angebots als Ganzzahl, kein Dezimalbetrag/Text; mindestens 1. | | `expected_selection_hash` (body) | string | Erforderlich | — | selection_hash desselben Angebots: 64 kleine Hexadezimalzeichen. | | `terms` (body) | boolean | Erforderlich | — | Zur ausdrücklichen Zustimmung muss der JSON-Wahrheitswert true gesendet werden, nicht die Zeichenfolge "true". | ## Anfrageinhalt Ersetzen Sie YOUR_/FROM_ durch Werte aus Katalog, Angebot oder Umfang. Beispiele lassen die Zustimmung auf false; bestätigen Sie echte Vorgänge nur bewusst. ```json { "mode": "topup", "package_id": "YOUR_PACKAGE_ID", "time_id": "FROM_RESIDENTIAL_CATALOG", "promo_code": "", "currency": "FROM_QUOTE", "expected_total_minor": "FROM_QUOTE_TOTAL_MINOR", "expected_selection_hash": "FROM_QUOTE_SELECTION_HASH", "terms": false } ``` ## Weitere Anwendungsbeispiele IDs und Preise sind beispielhaft; verwenden Sie echte Werte aus dem Katalog und demselben Angebot. JSON-IDs und expected_total_minor müssen Zahlen sein. Beispiele verwenden bewusst terms=false. Senden Sie terms=true nur nach ausdrücklicher Zustimmung zur kostenpflichtigen Aktion. ### Residential: neues Paket oder GB-Aufladung · mode=new Bei Residential-Bestellungen wählen Kunden keinen Verwendungszweck. Für ein neues Paket weist der Server automatisch denselben festen Zweck wie beim Website-Kauf zu; senden Sie weder purpose_id noch subpurpose_id oder other_purpose. Eine Traffic-Aufladung behält den bisherigen Zweck bei. ```json { "mode": "new", "location_id": 20, "time_id": 201, "promo_code": "", "currency": "TRY", "expected_total_minor": 1000, "expected_selection_hash": "0000000000000000000000000000000000000000000000000000000000000000", "terms": false } ``` ### Residential: neues Paket oder GB-Aufladung · mode=topup Bei Residential-Bestellungen wählen Kunden keinen Verwendungszweck. Für ein neues Paket weist der Server automatisch denselben festen Zweck wie beim Website-Kauf zu; senden Sie weder purpose_id noch subpurpose_id oder other_purpose. Eine Traffic-Aufladung behält den bisherigen Zweck bei. ```json { "mode": "topup", "package_id": 10001, "time_id": 201, "promo_code": "", "currency": "TRY", "expected_total_minor": 1000, "expected_selection_hash": "0000000000000000000000000000000000000000000000000000000000000000", "terms": false } ``` ## Anfragebeispiel ### curl ```curl printf 'Authorization: Bearer %s\n' "$ARNPROXY_API_KEY" | curl --silent --show-error --header @- \ --header 'Accept: application/json' \ --connect-timeout 10 --max-time 30 \ --header 'Idempotency-Key: YOUR_SAVED_OPERATION_KEY' \ --request POST --header 'Content-Type: application/json' \ --data-binary @request.json \ 'https://www.arnproxy.com/account/api/v1/residential/orders/create' ``` ### python ```python import os, requests headers = {"Authorization": "Bearer " + os.environ["ARNPROXY_API_KEY"]} headers["Idempotency-Key"] = "YOUR_SAVED_OPERATION_KEY" import json with open("request.json", encoding="utf-8") as f: payload = json.load(f) response = requests.post( "https://www.arnproxy.com/account/api/v1/residential/orders/create", headers=headers, json=payload, timeout=(10, 30), allow_redirects=False ) print(response.status_code, response.text) # No automatic write retry. ``` ### javascript ```javascript const headers = { Authorization: `Bearer ${process.env.ARNPROXY_API_KEY}` }; headers['Idempotency-Key'] = 'YOUR_SAVED_OPERATION_KEY'; const { readFile } = await import('node:fs/promises'); headers['Content-Type'] = 'application/json'; const body = await readFile('request.json', 'utf8'); const response = await fetch("https://www.arnproxy.com/account/api/v1/residential/orders/create", { method: 'POST', headers, redirect: 'error', signal: AbortSignal.timeout(30000), body }); console.log(response.status, await response.text()); // A write timeout is ambiguous; query its saved operation. ``` ### php ```php true, CURLOPT_HTTPHEADER => $headers, CURLOPT_FOLLOWLOCATION => false, CURLOPT_SSL_VERIFYPEER => true, CURLOPT_SSL_VERIFYHOST => 2, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 30, CURLOPT_POST => true, CURLOPT_POSTFIELDS => file_get_contents('request.json'), ]); $result = curl_exec($ch); if ($result === false) { // Do not repeat a write; use the original operation key. throw new RuntimeException('Transport result unknown'); } echo curl_getinfo($ch, CURLINFO_HTTP_CODE).PHP_EOL.$result; curl_close($ch); ``` ### go ```go package main import ( "fmt" "io" "net/http" "os" "time" ) func main() { client := &http.Client{Timeout: 30*time.Second, CheckRedirect: func(req *http.Request, via []*http.Request) error { return http.ErrUseLastResponse }} var body io.Reader file, err := os.Open("request.json"); if err != nil { panic(err) } defer file.Close(); body = file req, err := http.NewRequest("POST", "https://www.arnproxy.com/account/api/v1/residential/orders/create", body) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer "+os.Getenv("ARNPROXY_API_KEY")) req.Header.Set("Idempotency-Key", "YOUR_SAVED_OPERATION_KEY") req.Header.Set("Content-Type", "application/json") res, err := client.Do(req); if err != nil { panic(err) } defer res.Body.Close() data, err := io.ReadAll(res.Body); if err != nil { panic(err) } fmt.Println(res.StatusCode, string(data)) } ``` ### csharp ```csharp using System; using System.IO; using System.Net.Http; using System.Net.Http.Headers; using System.Text; using var handler = new HttpClientHandler { AllowAutoRedirect = false }; using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) }; using var request = new HttpRequestMessage(HttpMethod.Post, "https://www.arnproxy.com/account/api/v1/residential/orders/create"); request.Headers.Authorization = new AuthenticationHeaderValue( "Bearer", Environment.GetEnvironmentVariable("ARNPROXY_API_KEY")); request.Headers.Add("Idempotency-Key", "YOUR_SAVED_OPERATION_KEY"); request.Content = new StringContent( await File.ReadAllTextAsync("request.json"), Encoding.UTF8, "application/json"); using var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); // Never automatically retry an ambiguous write. ``` ### java ```java import java.net.URI; import java.net.http.*; import java.nio.charset.StandardCharsets; import java.nio.file.*; // Inside your application method: var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder(URI.create("https://www.arnproxy.com/account/api/v1/residential/orders/create")) .header("Authorization", "Bearer " + System.getenv("ARNPROXY_API_KEY")) .header("Accept", "application/json") .header("Idempotency-Key", System.getenv("ARNPROXY_OPERATION_KEY")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString( Files.readString(Path.of("request.json"), StandardCharsets.UTF_8))) .build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); ``` ## Antworten · HTTP 201, 200 ```json { "ok": true, "data": { "state": "accepted", "mode": "topup", "delivery_state_at_acceptance": "queued", "currency": "TRY", "total": "15.00", "total_minor": 1500, "gb": 1, "days": 30, "target_package_id": 20001, "order": { "id": 20002, "number": "1000020002", "location_id": 20, "time_id": 201, "last_service_date": "2030-02-01" }, "accepted_at": "2030-01-01T12:00:00+00:00", "automatic_renewal": false, "source": "existing_website_residential_delivery", "replayed": false }, "meta": { "request_id": "000000000000000000000001", "phase": "public_v1", "source": "arnproxy_records" } } ``` | Name | Typ | Bedingt | Beschreibung | |---|---|---|---| | `ok` | boolean | — | Erfolgskennzeichen; bei false error.code prüfen. | | `data` | object | — | Vorgangsspezifisches Ergebnis; Beispiele sind synthetisch und dienen der Veranschaulichung. | | `data.state` | string | — | Datensatz-/Vorgangsstatus. accepted bedeutet nicht geliefert, completed keinen Verbindungstest. | | `data.mode` | string | — | Vorgangsspezifischer Wert für mode. Rückgabetyp beibehalten und Verhaltenshinweise beachten. | | `data.delivery_state_at_acceptance` | string | — | Vorgangsspezifischer Wert für delivery state at acceptance. Rückgabetyp beibehalten und Verhaltenshinweise beachten. | | `data.currency` | string | — | Kontowährung der Transaktion: TRY oder USD. | | `data.total` | string | — | Geldbetrag; Text-/Ganzzahldarstellung für Genauigkeit beibehalten. | | `data.total_minor` | integer | — | Ganzzahl in kleinster Währungseinheit: 1000 bedeutet 10.00 TRY/USD. | | `data.gb` | integer | — | Trafficmenge; Listen-/Einstellungsvorgänge kaufen keinen Traffic. | | `data.days` | integer | — | Laufzeit in Tagen, getrennt vom Trafficvolumen des GB-Plans. | | `data.target_package_id` | integer | — | Vorgangsspezifischer Wert für target package id. Rückgabetyp beibehalten und Verhaltenshinweise beachten. | | `data.order` | object | — | Vorgangsspezifischer Wert für order. Rückgabetyp beibehalten und Verhaltenshinweise beachten. | | `data.order.id` | integer | — | Zugehörige ARNPROXY-Datensatz-ID statt interner Anbieter-ID verwenden. | | `data.order.number` | string | — | Angezeigte Bestellnummer, nicht mit Feldern für id austauschbar. | | `data.order.location_id` | integer | — | Lokale Katalog-ID für Standort oder Produkttyp. | | `data.order.time_id` | integer | — | Lokale Laufzeit-/GB-Plan-ID, keine Anzahl von Tagen oder GB. | | `data.order.last_service_date` | string | — | Letzter Diensttag: aktuell, vorherig oder prognostiziert. Eine Prognose führt keine Verlängerung aus. | | `data.accepted_at` | string | — | Zeitstempel im vom API gelieferten Format; Beispieldaten sind synthetisch. | | `data.automatic_renewal` | boolean | — | Vorgangsspezifischer Wert für automatic renewal. Rückgabetyp beibehalten und Verhaltenshinweise beachten. | | `data.source` | string | — | Datenquelle; lokale Datensätze und Live-Anbieterabfragen sind unterschiedliche Nachweise. | | `data.replayed` | boolean | — | Gespeichertes Ergebnis desselben Vorgangs, kein Beweis für neue Abbuchung/Aktion. | | `meta` | object | — | Metadaten zu Anfragezuordnung und Datenquelle. | | `meta.request_id` | string | — | Kennung dieser HTTP-Anfrage, kein Vorgangsschlüssel oder Bestell-ID. | | `meta.phase` | string | — | Vorgangsspezifischer Wert für phase. Rückgabetyp beibehalten und Verhaltenshinweise beachten. | | `meta.source` | string | — | Datenquelle; lokale Datensätze und Live-Anbieterabfragen sind unterschiedliche Nachweise. | ## Verhalten & wichtige Hinweise - Paket-/Listen-IDs sind ARNPROXY-Datensatz-IDs, keine Anbieterkennungen. Veralteter Snapshot gewährt keinen Zugriff; gegebenenfalls residential_package_refresh nutzen. - mode=new erstellt ein Paket, mode=topup fügt GB hinzu. Zuerst residential_catalog/quote abfragen. Guthabenannahme und Hintergrundlieferung sind getrennt; denselben Vorgangsschlüssel verfolgen. - Timeout/5xx beweist keinen Schreibfehler. Ursprünglichen Idempotency-Key für den Status verwenden. Nicht mit neuem Schlüssel wiederholen; GET sendet die Änderung nicht erneut. - Bei Residential-Bestellungen wählen Kunden keinen Verwendungszweck. Für ein neues Paket weist der Server automatisch denselben festen Zweck wie beim Website-Kauf zu; senden Sie weder purpose_id noch subpurpose_id oder other_purpose. Eine Traffic-Aufladung behält den bisherigen Zweck bei. - Für die Kompatibilität können gültige ältere Felder subpurpose_id/other_purpose bei mode=new akzeptiert werden, ändern aber nicht den automatisch zugewiesenen Zweck neuer Bestellungen. Neue Integrationen lassen sie weg. Bei mode=topup sind sie nicht unterstützt. Bereits angenommene Anfragen mit gleichem Idempotency-Key und gleicher Anfrage verfolgen; nicht mit neuem Schlüssel erneut kaufen. - Ist die automatische Zweckkonfiguration nicht verfügbar, erscheint RESIDENTIAL_DEFAULT_PURPOSE_UNAVAILABLE (HTTP 503), ohne Bestellung oder Guthabenabbuchung. Ein Administrator muss die Konfiguration prüfen. Authentifizierung und Validierung können eine Anfrage vor der Ausführung ablehnen. Beachten Sie die Fehlerreferenz und bewahren Sie request_id für den Support auf. Senden Sie niemals Schlüssel oder Passwörter. [Fehler & Limits](https://docs.arnproxy.com/de/api-v1/errors) [Denselben Vorgang verfolgen: Residential-Lieferstatus](https://docs.arnproxy.com/de/api-v1/residential/orders/status)