API de notification unique par lot

API de Push Unitaire en Lot

Description de la Fonction

Utilisée pour l'envoi en lot de messages push unitaires, permettant à plusieurs utilisateurs cibles de recevoir des notifications push en un seul appel. Prend en charge l'envoi via registration_id ou alias :

Envoi via registration_id : POST /v4/batch/push/regid
Envoi via alias : POST /v4/batch/push/alias
Limites de capacité :
- 500 cibles maximum par requête
- Prise en charge du traitement concurrent pour plus d'efficacité
- Retourne des résultats partiels en cas de limitation de débit
- Cette API et l'API de Push partagent le même quota QPS. Utiliser l'API de push en lot pour envoyer à 1 regid ou 1 alias consomme 1 quota QPS de l'API de Push.

Authentification

Ajoutez le champ d'authentification dans l'en-tête HTTP :

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

Afficher ce bloc de code dans la fenêtre flottante

Méthode de génération : base64(username:password)
- username = AppKey de l'application
- password = Master Secret
Chemin d'accès : Console → Paramètres de l'application → Infos de l'application

Points de terminaison

Push en lot via registration_id

POST /v4/batch/push/regid

              
              POST /v4/batch/push/regid

Afficher ce bloc de code dans la fenêtre flottante

Push en lot via alias

POST /v4/batch/push/alias

              
              POST /v4/batch/push/alias

Afficher ce bloc de code dans la fenêtre flottante

Exemples de Requêtes

1. Push en lot via 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
        }
      }
    ]
  }'

Afficher ce bloc de code dans la fenêtre flottante

2. Push en lot via 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
        }
      }
    ]
  }'

Afficher ce bloc de code dans la fenêtre flottante

Paramètres de la Requête

Structure du corps de la requête :

{ "requests": [ { "target": "string", // Obligatoire, cible de l'envoi (registration_id ou alias) "platform": "string", // Obligatoire, plateforme de push (android/ios/all) "notification": "object", // Optionnel, contenu de la notification (voir API de Push) "message": "object", // Optionnel, message personnalisé (voir API de Push), ne peut pas coexister avec notification "options": "object", // Optionnel, options de push (voir API de Push) "custom_args": "object" // Optionnel, paramètres transmis au client } ] }

              
              {
  "requests": [
    {
      "target": "string",     // Obligatoire, cible de l'envoi (registration_id ou alias)
      "platform": "string",   // Obligatoire, plateforme de push (android/ios/all)
      "notification": "object",  // Optionnel, contenu de la notification (voir API de Push)
      "message": "object",     // Optionnel, message personnalisé (voir API de Push), ne peut pas coexister avec notification
      "options": "object",     // Optionnel, options de push (voir API de Push)
      "custom_args": "object"  // Optionnel, paramètres transmis au client
    }
  ]
}

Afficher ce bloc de code dans la fenêtre flottante

Descriptions des paramètres :

Champ	Obligatoire	Type	Description
`requests`	Oui	array	Tableau de requêtes en lot (max 500 éléments, `target` doit être unique par lot)
`target`	Oui	string	Valeur cible : - point de terminaison `/regid` : `registration_id` - point de terminaison `/alias` : `alias`
`platform`	Oui	string	Plateforme de push : `android`, `ios` ou `all`
`notification`	Non	object	Contenu de la notification (même structure que l'API de push unitaire)
`message`	Non	object	Message personnalisé (même structure que l'API de push unitaire)
`options`	Non	object	Options de push (ex. `time_to_live`, `apns_production`)
`custom_args`	Non	object	Paramètres personnalisés transmis

Exemples de Réponses

Réponse réussie (tout réussi)

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

Afficher ce bloc de code dans la fenêtre flottante

Réponse réussie (limitation partielle du débit)

{ "rate_limit_info": { "message": "Certaines requêtes ont été limitées lors du traitement en lot", "rate_limit_occurred": true }, "results": { "170976fa8a0771c2647": { "target": "170976fa8a0771c2647", "success": false, "error": { "code": 23008, "message": "Limite de débit dépassée pour l'API" } }, "170976fa8a9277c25d4": { "target": "170976fa8a9277c25d4", "success": false, "error": { "code": 23008, "message": "Limite de débit dépassée pour l'API" } } } }

              
              {
    "rate_limit_info": {
        "message": "Certaines requêtes ont été limitées lors du traitement en lot",
        "rate_limit_occurred": true
    },
    "results": {
        "170976fa8a0771c2647": {
            "target": "170976fa8a0771c2647",
            "success": false,
            "error": {
                "code": 23008,
                "message": "Limite de débit dépassée pour l'API"
            }
        },
        "170976fa8a9277c25d4": {
            "target": "170976fa8a9277c25d4",
            "success": false,
            "error": {
                "code": 23008,
                "message": "Limite de débit dépassée pour l'API"
            }
        }
    }
}

Afficher ce bloc de code dans la fenêtre flottante

Réponse échouée (erreur globale)

{ "error": { "code": 21004, "message": "échec de l'authentification basique" } }

              
              {
  "error": {
    "code": 21004,
    "message": "échec de l'authentification basique"
  }
}

Afficher ce bloc de code dans la fenêtre flottante

Réponse échouée (erreur de paramètre)

{ "error": { "code": 21003, "message": "La valeur du paramètre est invalide" } }

              
              {
  "error": {
    "code": 21003,
    "message": "La valeur du paramètre est invalide"
  }
}

Afficher ce bloc de code dans la fenêtre flottante

Référence des Codes d'Erreur

Code d'erreur	Description	Résolution	Statut HTTP
Codes d'erreur globaux
21004	Échec de l'authentification basique	Vérifiez AppKey/MasterSecret	401
21008	La longueur de l'AppKey n'est pas de 24 caractères	Vérifiez le format de l'AppKey	400
21038	Pas d'autorisation de push pour l'application	Vérifiez la configuration de l'application	400
21043	Pas d'autorisation de push (paiement en attente)	Résolvez le problème de facturation	400
23009	IP non présente dans la liste blanche	Ajoutez l'IP du serveur à la liste blanche	400
21009	Erreur interne du système (ne pas réessayer)	Contactez le support technique	400
Erreurs de limitation de débit
23008	Limite de débit de l'API atteinte	Réessayez les éléments échoués si succès partiel	400
Erreurs de paramètre
21003	Valeur de paramètre invalide	Vérifiez le format du corps de la requête	400
21015	Paramètres de la requête invalides	Validez les champs obligatoires	400
21016	Échec de la validation des paramètres	Vérifiez les types de champs et les plages de valeurs	400

Tous les codes d'erreur : Create Push API - Response

Remarques

Gestion de la limitation de débit : Retourne des résultats partiels en cas de limitation (msg_id pour les réussites + error pour les échecs).
Vérification des doublons : Toutes les valeurs target ou cid doivent être uniques dans un lot.
Limite de quantité : 500 cibles maximum par requête.
Gestion des erreurs : Les erreurs globales (ex. échec d'authentification) mettent fin immédiatement à la requête sans résultat partiel.