API para añadir un dominio web

Añade un dominio a una aplicación WebPush VIP. El SDK, el Service Worker y el permiso del usuario se configuran por separado.

Usa Basic Auth con AppKey y MasterSecret en el centro de datos correcto. domain es obligatorio, usa la validación de guardado de portalweb como base y exige https:// explícito y solo minúsculas. Se admiten dominios e IPv4 con o sin puerto numérico; IPv6 se rechaza. Las reglas confirmadas aceptan también el puerto 65536: 65535 no es un límite de admisión. Se siguen rechazando 0 y los ceros iniciales. Se permite una / raíz final, equivalente a la forma sin barra al comprobar duplicados. Se rechazan segmentos como /page, consultas, fragmentos, espacios, localhost con subdominios y variantes con punto final, HTTP y comodines. IPv4 solo se comprueba por formato, sin restricciones de uso ni comprobaciones de DNS, accesibilidad o certificados. La entrada válida se guarda sin cambios. request_id es opcional, de hasta 128 bytes; las reglas de devolución se explican abajo.

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

            

Los duplicados enviados de forma secuencial no consumen cuota adicional. La comparación ignora mayúsculas, barras finales y el puerto predeterminado 443. Los dominios nuevos conservan el host validado en minúsculas y el puerto enviado. Los existentes conservan su forma almacenada y estado de integración. Los duplicados devuelven HTTP 400 con los datos existentes. La API utiliza la cuota de la consola. Envía las solicitudes de forma secuencial y evita cambios simultáneos en la consola; las escrituras concurrentes pueden sobrescribirse. La configuración sigue el proceso habitual de la consola y puede tardar en aplicarse. Las operaciones de API se registran en los registros del servicio, sin entrada en el historial de operaciones de la consola. Tras un tiempo de espera o 5xx, reintenta el mismo dominio. No se ofrecen eliminación, modificación, altas por lotes ni compra de cuota. Esta API reutiliza la cuota QPS de la aplicación configurada en deviceapi; si no está configurada, usa el valor predeterminado del sistema. El recuento es independiente por AppKey y API; las llamadas duplicadas también consumen QPS. Al superar el límite, devuelve HTTP 400 con el código 23010 (Rate limit exceeded for the API). Reintenta más tarde con espera progresiva.

Validación de solicitudes, códigos de error y request_id

El cuerpo de la solicitud admite hasta 4 KiB. domain debe ser una cadena no vacía. Un valor ausente, null, vacío, numérico, booleano, matriz u objeto, JSON mal formado o múltiple, un cuerpo demasiado grande o request_id de más de 128 bytes devuelve HTTP 400 / 21003 Invalid request sin request_id. Una cadena no vacía cuyo formato de dominio sea inválido devuelve HTTP 400 / 27600 INVALID_DOMAIN.

Tras validar la estructura, un request_id válido y no vacío se devuelve sin cambios en las respuestas de negocio, incluidos 27600, 27601 y el error de límite QPS 23010. El campo se omite si falta o está vacío. Un encabezado Basic inválido rechazado antes de analizar el cuerpo tampoco devuelve request_id.

El límite usa app_qps de la aplicación y recurre al valor predeterminado del negocio si falta o vale 0; no existe un umbral fijo universal. El recuento es independiente por AppKey + /v4/web/domains. Los duplicados consumen QPS y el límite se comprueba antes de buscar dominios duplicados. Al superarlo se devuelve HTTP 400 / 23010 Rate limit exceeded for the API, no HTTP 429. Reintenta con espera progresiva.

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