API de push único por lotes | WebPush Guía para desarrolladores API REST Español

Los ejemplos utilizan Singapur. Seleccione la URL base del centro de datos de su aplicación antes de realizar solicitudes. Para el envío a grupos, utilice el centro de datos y las credenciales del grupo. Consulte las direcciones en Descripción general de la REST API.

Descripción de la función

Se utiliza para notificaciones push únicas por lotes, lo que permite que varios usuarios objetivo reciban envíos en una sola llamada. Admite el envío mediante registration_id o alias:

Envío mediante registration_id: POST /v4/batch/push/regid
Envío mediante alias: POST /v4/batch/push/alias
Límites de capacidad:
- Máximo de 500 destinos de push por solicitud
- Admite el procesamiento concurrente para mejorar la eficiencia
- Devuelve resultados de éxito parcial durante el límite de frecuencia
- Esta API y la Push API comparten la misma cuota de QPS. El uso de la API de push por lotes para enviar a 1 regid o 1 alias consume 1 unidad de la cuota de QPS de la Push API.

Autenticación

Añadir el campo de autenticación en el encabezado HTTP:

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

Este bloque de código se muestra en una ventana flotante

Método de generación: base64(username:password)
- username = AppKey de la aplicación
- password = Master Secret
Ruta de acceso: Consola → Application Settings → Application Info

Endpoints

Push por lotes mediante registration_id

POST /v4/batch/push/regid

              
              POST /v4/batch/push/regid

Este bloque de código se muestra en una ventana flotante

Push por lotes mediante alias

POST /v4/batch/push/alias

              
              POST /v4/batch/push/alias

Este bloque de código se muestra en una ventana flotante

Ejemplos de solicitud

1. Push por lotes mediante registration_id

curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/regid \ -H "Content-Type: application/json" \ -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \ -d '{ "requests": [ { "target": "registration_id_1", "platform": "web", "notification": { "alert": "Hi,Push !", "web": { "alert": "Hi,Push !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false }, "custom_args": { "business": "info" } }, { "target": "registration_id_2", "platform": "web", "notification": { "alert": "Hi,MTPush !", "web": { "alert": "Hi,MTPush !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/regid \
  -H "Content-Type: application/json" \
  -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
  -d '{
    "requests": [
      {
        "target": "registration_id_1",
        "platform": "web",
        "notification": {
            "alert": "Hi,Push !",
            "web": {
                "alert": "Hi,Push !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        },
        "custom_args": {
          "business": "info"
        }
      },
      {
        "target": "registration_id_2",
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",
            "web": {
                "alert": "Hi,MTPush !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        }
      }
    ]
  }'

Este bloque de código se muestra en una ventana flotante

2. Push por lotes mediante alias

curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/alias \ -H "Content-Type: application/json" \ -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \ -d '{ "requests": [ { "target": "user_alias_1", "platform": "web", "notification": { "alert": "Hi,Push !", "web": { "alert": "Hi,Push !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false } }, { "target": "user_alias_2", "platform": "web", "notification": { "alert": "Hi,MTPush !", "web": { "alert": "Hi,MTPush !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/alias \
  -H "Content-Type: application/json" \
  -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
  -d '{
    "requests": [
      {
        "target": "user_alias_1",
        "platform": "web",
        "notification": {
            "alert": "Hi,Push !",
            "web": {
              "alert": "Hi,Push !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        }
      },
      {
        "target": "user_alias_2",
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",
            "web": {
              "alert": "Hi,MTPush !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        }
      }
    ]
  }'

Este bloque de código se muestra en una ventana flotante

Parámetros de la solicitud

Estructura del cuerpo de la solicitud:

{ "requests": [ { "target": "string", // Obligatorio, destino de push (registration_id o alias) "platform": "string", // Obligatorio, configuración de la plataforma de push (ver la Push API) "notification": "object", // Opcional, contenido de la notificación (ver la Push API) "message": "object", // Opcional, mensaje personalizado (ver la Push API), no puede coexistir con notification "options": "object", // Opcional, opciones de push (ver la Push API) "custom_args": "object" // Opcional, parámetros pasados al cliente } ] }

              
              {  
  "requests": [  
    {  
      "target": "string",     // Obligatorio, destino de push (registration_id o alias)  
      "platform": "string",   // Obligatorio, configuración de la plataforma de push (ver la Push API)
      "notification": "object",  // Opcional, contenido de la notificación (ver la Push API)  
      "message": "object",     // Opcional, mensaje personalizado (ver la Push API), no puede coexistir con notification  
      "options": "object",     // Opcional, opciones de push (ver la Push API)  
      "custom_args": "object"  // Opcional, parámetros pasados al cliente  
    }  
  ]  
}

Este bloque de código se muestra en una ventana flotante

Descripción de parámetros:

Campo	Obligatorio	Tipo	Descripción
`requests`	Sí	array	Array de solicitudes por lotes (máx. 500 elementos; `target` debe ser único por lote)
`target`	Sí	string	Valor del destino: - Endpoint `/regid`: `registration_id` - Endpoint `/alias`: `alias`
`platform`	Sí	string	Para WebPush, use `web` o `all`; en una aplicación WebPush, `all` representa la plataforma Web.
`notification`	No	object	Contenido de la notificación (misma estructura que la Push API)
`message`	No	object	Mensaje personalizado (misma estructura que la Push API)
`options`	No	object	Opciones de push (p. ej., `time_to_live`, `apns_production`)
`custom_args`	No	object	Parámetros personalizados de paso directo (passthrough)

Ejemplos de respuesta

Respuesta correcta (todo correcto)

{ "results": { "registration_id_1": { "target": "registration_id_1", "success": true, "msg_id": 2460001 }, "registration_id_2": { "target": "registration_id_2", "success": true, "msg_id": 2460002 } } }

              
              {
  "results": {
    "registration_id_1": {
      "target": "registration_id_1",
      "success": true,
      "msg_id": 2460001
    },
    "registration_id_2": {
      "target": "registration_id_2",
      "success": true,
      "msg_id": 2460002
    }
  }
}

Este bloque de código se muestra en una ventana flotante

Respuesta HTTP 200 (límite de frecuencia por elemento)

Este ejemplo muestra destinos que superan la cuota disponible una vez iniciado el procesamiento por lotes. El estado HTTP externo es 200; no significa que todos los destinos hayan tenido éxito.

HTTP/1.1 200 OK Content-Type: application/json

              
              HTTP/1.1 200 OK
Content-Type: application/json

Este bloque de código se muestra en una ventana flotante

{ "rate_limit_info": { "message": "Some requests were rate limited during batch processing", "rate_limit_occurred": true }, "results": { "170976fa8a0771c2647": { "target": "170976fa8a0771c2647", "success": false, "error": { "code": 23008, "message": "API rate limit exceeded" } }, "170976fa8a9277c25d4": { "target": "170976fa8a9277c25d4", "success": true, "msg_id": 2460002 } } }

              
              {
    "rate_limit_info": {
        "message": "Some requests were rate limited during batch processing",
        "rate_limit_occurred": true
    },
    "results": {
        "170976fa8a0771c2647": {
            "target": "170976fa8a0771c2647",
            "success": false,
            "error": {
                "code": 23008,
                "message": "API rate limit exceeded"
            }
        },
        "170976fa8a9277c25d4": {
            "target": "170976fa8a9277c25d4",
            "success": true,
            "msg_id": 2460002
        }
    }
}

Este bloque de código se muestra en una ventana flotante

Respuesta fallida (error global)

{ "error": { "code": 21004, "message": "basic auth failed" } }

              
              {  
  "error": {  
    "code": 21004,  
    "message": "basic auth failed"  
  }  
}

Este bloque de código se muestra en una ventana flotante

Respuesta fallida (error de parámetros)

{ "error": { "code": 21003, "message": "Parameter value is invalid" } }

              
              {  
  "error": {  
    "code": 21003,  
    "message": "Parameter value is invalid"  
  }  
}

Este bloque de código se muestra en una ventana flotante

Referencia de códigos de error

Salvo que se indique lo contrario, los estados HTTP de la tabla se aplican a errores de la solicitud completa. Los errores por elemento se devuelven en results[target].error, mientras que el estado HTTP externo sigue siendo 200.

Código de error	Descripción	Resolución	Estado HTTP
Códigos de error globales
21004	Fallo en la autenticación básica	Verificar AppKey/MasterSecret	401
21008	La longitud de la AppKey no es de 24 caracteres	Verificar el formato de la AppKey	400
21038	La aplicación no tiene permiso de push	Verificar la configuración de la aplicación	400
21043	Sin permiso de push (pago pendiente)	Resolver el problema de facturación	400
23009	La IP no está en la lista de permitidos	Añadir la IP del servidor a la lista de permitidos	400
21009	Error interno del sistema (no reintentar)	Contactar con el soporte técnico	400
Errores de límite de frecuencia
23008	Se alcanzó el límite de frecuencia de la API	Reintentar los elementos fallidos si hay éxito parcial	400 (solicitud); 200 (resultados por elemento)
Errores de parámetros
21003	Valor de parámetro no válido	Revisar el formato del cuerpo de la solicitud	400
21015	Parámetros de solicitud no válidos	Validar los campos obligatorios	400
21016	Error de validación de parámetros	Revisar los tipos de campo y los rangos de valores	400

Códigos de error completos: Create Push API - Response

Notas

Gestión del límite de frecuencia: El límite de frecuencia de toda la solicitud devuelve HTTP 400. Una vez iniciado el procesamiento por lotes, los límites por elemento devuelven success=false y error.code=23008 en results con HTTP 200. Reintente solo los elementos fallidos.
Comprobación de duplicados: Todos los valores target o cid deben ser únicos dentro de un lote.
Límite de cantidad: Máximo de 500 destinos por solicitud.
Gestión de errores: Los errores globales (p. ej., fallo de autenticación) finalizan inmediatamente sin resultados parciales.