API zum Hinzufügen einer Website-Domain

Fügen Sie einer VIP-WebPush-Anwendung eine Domain hinzu. SDK, Service Worker und Benutzereinwilligung sind separat einzurichten.

Verwenden Sie Basic Auth mit AppKey und MasterSecret im richtigen Rechenzentrum. domain ist erforderlich, verwendet die Speichervalidierung von portalweb als Grundlage und verlangt ausdrücklich https:// sowie Kleinschreibung. Domains und IPv4 sind mit oder ohne numerischen Port zulässig; IPv6 wird abgelehnt. Nach den bestätigten Abnahmeregeln ist auch Port 65536 zulässig; 65535 ist keine Zulassungsgrenze. 0 und führende Nullen bleiben unzulässig. Ein einzelner abschließender / ist erlaubt und bei Duplikatprüfungen gleichwertig mit der Form ohne Schrägstrich. Pfadsegmente wie /page, Abfragen, Fragmente, Leerraum, localhost samt Subdomains und Varianten mit abschließendem Punkt, HTTP und Platzhalter werden abgelehnt. IPv4 wird nur auf Syntax geprüft, nicht auf Adresszweck, DNS, Erreichbarkeit oder Zertifikate. Gültige Eingaben bleiben unverändert. request_id ist optional und auf 128 Byte begrenzt; Rückgaberegeln siehe unten.

Basic Auth

POST /v4/web/domains

              
              curl -X POST https://webpushapi-sgp.engagelab.com/v4/web/domains \
  -u APP_KEY:MASTER_SECRET \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "https://shop-001.example.com",
    "request_id": "req-001"
  }'

            

HTTP 200:

              
              {
  "request_id": "req-001",
  "domain_id": "wd_<sha256>",
  "domain": "https://shop-001.example.com",
  "integration_status": "pending",
  "config_status": "ready"
}

            

integration_status: pending / integrated. config_status: ready (pending: reserved).

              
              {
  "error": {
    "code": 27601,
    "message": "DOMAIN_ALREADY_EXISTS"
  },
  "request_id": "req-001",
  "domain_id": "wd_<sha256>",
  "domain": "https://shop-001.example.com",
  "integration_status": "pending",
  "config_status": "ready"
}

            

Nacheinander gesendete Duplikate verbrauchen kein zusätzliches Kontingent. Der Vergleich ignoriert Groß-/Kleinschreibung, abschließende Schrägstriche und den Standardport 443. Neue Domains behalten den validierten kleingeschriebenen Host und den eingegebenen Port. Vorhandene Domains behalten Schreibweise und Integrationsstatus. Duplikate liefern HTTP 400 mit vorhandenen Domain-Daten. Die API nutzt das Konsolenkontingent. Senden Sie Anfragen nacheinander und vermeiden Sie gleichzeitige Änderungen in der Konsole; parallele Schreibvorgänge können sich überschreiben. Die Übernahme der Konfiguration folgt dem bisherigen Konsolenverhalten und kann verzögert sein. API-Vorgänge werden in Dienstprotokollen erfasst, ohne Eintrag im Vorgangsverlauf der Konsole. Nach Timeout oder 5xx dieselbe Domain erneut senden. Löschen, Ändern, Stapelverarbeitung und Kontingentkauf werden nicht angeboten. Diese API verwendet das bestehende QPS-Kontingent der Anwendung in deviceapi; ohne Konfiguration gilt der Systemstandard. Die Zählung erfolgt getrennt nach AppKey und API; Duplikate verbrauchen ebenfalls QPS. Bei Überschreitung wird HTTP 400 mit Code 23010 (Rate limit exceeded for the API) zurückgegeben. Wiederholen Sie die Anfrage nach einer Wartezeit mit Backoff.

Anfragevalidierung, Fehlercodes und request_id

Der Anfragekörper ist auf 4 KiB begrenzt. domain muss eine nicht leere Zeichenfolge sein. Fehlende, null-, leere, numerische, boolesche, Array- oder Objektwerte, fehlerhaftes JSON, mehrere JSON-Werte, ein zu großer Körper oder request_id über 128 Byte führen zu HTTP 400 / 21003 Invalid request ohne request_id. Eine nicht leere Zeichenfolge mit ungültigem Domainformat liefert HTTP 400 / 27600 INVALID_DOMAIN.

Nach erfolgreicher Strukturprüfung wird eine gültige, nicht leere request_id in nachfolgenden Geschäftsantworten unverändert zurückgegeben, auch bei 27600, 27601 und QPS-Fehler 23010. Bei fehlendem oder leerem Wert entfällt das Feld. Ein vor dem Einlesen des Körpers abgelehnter ungültiger Basic-Header liefert ebenfalls keine request_id.

Die QPS-Grenze verwendet app_qps der Anwendung; bei fehlendem Wert oder 0 gilt der Geschäftsstandard, kein allgemeiner fester Wert. Die Zählung ist nach AppKey + /v4/web/domains getrennt. Duplikate verbrauchen QPS; die Begrenzung erfolgt vor der Duplikatprüfung. Eine Überschreitung liefert HTTP 400 / 23010 Rate limit exceeded for the API statt HTTP 429. Mit Backoff erneut versuchen.

              
              {"error":{"code":21003,"message":"Invalid request"}}

            

              
              {"request_id":"invalid-domain","error":{"code":27600,"message":"INVALID_DOMAIN"}}

            

              
              {"request_id":"qps-example","error":{"code":23010,"message":"Rate limit exceeded for the API"}}