API de notificación única por lotes

API de push único por lotes

Descripción de la función

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

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

Autenticación

Añadir el campo de autenticación en la cabecera 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 → Configuración de la aplicación → Información de la aplicación

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://pushapi-sgp.engagelab.com/v4/batch/push/regid \ -H "Content-Type: application/json" \ -u "AppKey:MasterSecret" \ -d '{ "requests": [ { "target": "registration_id_1", "platform": "android", "notification": { "android": { "alert": "Hi, Push!", "title": "Send to Android", "builder_id": 1, "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false }, "custom_args": { "business": "info" } }, { "target": "registration_id_2", "platform": "ios", "notification": { "ios": { "alert": "Hi, MTPush!", "sound": "default", "badge": "+1", "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/regid \  
  -H "Content-Type: application/json" \  
  -u "AppKey:MasterSecret" \  
  -d '{  
    "requests": [  
      {  
        "target": "registration_id_1",  
        "platform": "android",  
        "notification": {  
          "android": {  
            "alert": "Hi, Push!",  
            "title": "Send to Android",  
            "builder_id": 1,  
            "extras": { "newsid": 321 
            }  
          }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        },  
        "custom_args": { "business": "info" }  
      },  
      {  
        "target": "registration_id_2",  
        "platform": "ios",  
        "notification": {  
          "ios": {  
            "alert": "Hi, MTPush!",  
            "sound": "default",  
            "badge": "+1",  
            "extras": { "newsid": 321 
            }  
          }  
        },  
        "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://pushapi-sgp.engagelab.com/v4/batch/push/alias \ -H "Content-Type: application/json" \ -u "AppKey:MasterSecret" \ -d '{ "requests": [ { "target": "user_alias_1", "platform": "all", "notification": { "android": { "alert": "Hi, Push!", "title": "Send to Android" }, "ios": { "alert": "Hi, MTPush!", "sound": "default" } }, "options": { "time_to_live": 60, "apns_production": false } }, { "target": "user_alias_2", "platform": "ios", "notification": { "ios": { "alert": "Hi, MTPush!", "sound": "default", "badge": "+1", "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/alias \  
  -H "Content-Type: application/json" \  
  -u "AppKey:MasterSecret" \  
  -d '{  
    "requests": [  
      {  
        "target": "user_alias_1",  
        "platform": "all",  
        "notification": {  
          "android": { "alert": "Hi, Push!", "title": "Send to Android" },  
          "ios": { "alert": "Hi, MTPush!", "sound": "default" }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        }  
      },  
      {  
        "target": "user_alias_2",  
        "platform": "ios",  
        "notification": {  
          "ios": {  
            "alert": "Hi, MTPush!",  
            "sound": "default",  
            "badge": "+1",  
            "extras": { "newsid": 321 }  
          }  
        },  
        "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", "platform": "string", "notification": "object", "message": "object", "options": "object", "custom_args": "object" } ] }

              
              {  
  "requests": [  
    {  
      "target": "string",  
      "platform": "string",  
      "notification": "object",  
      "message": "object",  
      "options": "object",  
      "custom_args": "object"  
    }  
  ]  
}

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

Descripciones 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 destinatario: - 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 API de push único)
`message`	No	object	Mensaje personalizado (misma estructura que la API de push único)
`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 (todas correctas)

{ "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 (limitación 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	Error de autenticación básica	Verificar AppKey/MasterSecret	401
21008	La longitud de AppKey no es de 24 caracteres	Verificar el formato de AppKey	400
21038	La aplicación no tiene permiso de push	Revisar la configuración de la aplicación	400
21043	Sin permiso de push (pago pendiente)	Resolver el problema de facturación	400
23009	IP no incluida 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 limitación 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	Verificar el formato del cuerpo de la solicitud	400
21015	Parámetros de solicitud no válidos	Validar los campos obligatorios	400
21016	Fallo en la validación de parámetros	Verificar los tipos de campo y los rangos de valores	400

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

Notas

Gestión de limitación de frecuencia: devuelve resultados de éxito parcial durante la limitación 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 destinatarios por solicitud.
Gestión de errores: los errores globales (p. ej., fallo de autenticación) finalizan inmediatamente sin resultados parciales.