API de notificación única por lotes

API de push único por lotes

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	Plataforma de push: `android`, `ios` o `all`
`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 correcta (límite de frecuencia parcial)

{ "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": "Rate limit exceeded for the API" } }, "170976fa8a9277c25d4": { "target": "170976fa8a9277c25d4", "success": false, "error": { "code": 23008, "message": "Rate limit exceeded for the API" } } } }

              
              {
    "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": "Rate limit exceeded for the API"
            }
        },
        "170976fa8a9277c25d4": {
            "target": "170976fa8a9277c25d4",
            "success": false,
            "error": {
                "code": 23008,
                "message": "Rate limit exceeded for the API"
            }
        }
    }
}

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

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
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: Devuelve resultados de éxito parcial durante el límite de frecuencia (msg_id para los correctos + error para los 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.