API d’ajout de domaine web

Ajoutez un domaine à une application WebPush VIP. Le SDK, le Service Worker et le consentement utilisateur sont à configurer séparément.

Utilisez Basic Auth avec AppKey et MasterSecret dans le bon centre de données. domain est obligatoire, utilise la validation de stockage de portalweb comme base et exige https:// explicite et des minuscules uniquement. Les domaines et IPv4 sont acceptés avec ou sans port numérique ; IPv6 est refusé. Les règles confirmées autorisent aussi le port 65536 : 65535 n’est pas une limite d’admission. 0 et les zéros initiaux restent refusés. Un / racine final est autorisé et équivaut à la forme sans barre pour les doublons. Les segments comme /page, requêtes, fragments, espaces, localhost avec sous-domaines et variantes avec point final, HTTP et caractères génériques sont refusés. Seule la syntaxe IPv4 est vérifiée, sans restriction d’usage ni contrôle de DNS, d’accessibilité ou de certificat. La saisie valide est conservée. request_id est facultatif, limité à 128 octets ; voir les règles de retour ci-dessous.

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"
}

            

Les doublons envoyés successivement ne consomment pas de quota supplémentaire. La comparaison ignore la casse, les barres finales et le port par défaut 443. Les nouveaux domaines conservent l’hôte validé en minuscules et le port saisi. Les domaines existants conservent leur forme enregistrée et leur état d’intégration. Un doublon renvoie HTTP 400 avec les données existantes. L’API utilise le quota de la console. Envoyez les ajouts successivement et évitez les modifications simultanées dans la console ; les écritures concurrentes peuvent s’écraser. La configuration suit le fonctionnement habituel de la console et peut prendre du temps à se propager. Les opérations API sont consignées dans les journaux du service, sans entrée dans l’historique des opérations de la console. Après un délai dépassé ou 5xx, réessayez le même domaine. Suppression, modification, ajout par lot et achat de quota ne sont pas proposés. Cette API réutilise le quota QPS de l’application configuré dans deviceapi ; sans configuration, la valeur par défaut du système s’applique. Le comptage est distinct par AppKey et API ; les appels en double consomment aussi des QPS. En cas de dépassement, elle renvoie HTTP 400 avec le code 23010 (Rate limit exceeded for the API). Réessayez après un délai progressif.

Validation des requêtes, codes d’erreur et request_id

Le corps est limité à 4 KiB. domain doit être une chaîne non vide. Une valeur absente, null, vide, numérique, booléenne, un tableau ou un objet, un JSON incorrect ou multiple, un corps trop volumineux ou request_id de plus de 128 octets renvoie HTTP 400 / 21003 Invalid request sans request_id. Une chaîne non vide dont le format de domaine est invalide renvoie HTTP 400 / 27600 INVALID_DOMAIN.

Après validation de la structure, un request_id valide et non vide est renvoyé sans modification dans les réponses métier, y compris 27600, 27601 et l’erreur QPS 23010. Le champ est omis s’il est absent ou vide. Un en-tête Basic invalide refusé avant l’analyse du corps ne renvoie pas non plus request_id.

La limite utilise app_qps de l’application, ou la valeur métier par défaut si ce paramètre est absent ou égal à 0 ; aucun seuil fixe ne s’applique à toutes les applications. Le comptage est distinct par AppKey + /v4/web/domains. Les doublons consomment des QPS et la limite est vérifiée avant la recherche de doublons. Le dépassement renvoie HTTP 400 / 23010 Rate limit exceeded for the API, pas HTTP 429. Réessayez avec un délai progressif.

              
              {"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"}}