API de Push Unitaire en Lot | WebPush Guide du développeur API REST Français

Les exemples utilisent Singapour. Sélectionnez l’URL de base du centre de données de votre application avant tout appel. Pour un envoi groupé, utilisez le centre de données et les identifiants du groupe. Consultez les adresses dans Présentation de l’API REST.

Description de la Fonction

Utilisée pour des notifications push unitaires en lot, permettant à plusieurs utilisateurs cibles de recevoir des notifications 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 simultané pour plus d'efficacité
- Retourne des résultats partiellement réussis en cas de limitation de débit
- Cette API et l'API 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 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://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
        }
      }
    ]
  }'

Afficher ce bloc de code dans la fenêtre flottante

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

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 du push (registration_id ou alias) "platform": "string", // Obligatoire, paramètres de la plateforme de push (voir API Push) "notification": "object", // Optionnel, contenu de la notification (voir API Push) "message": "object", // Optionnel, message personnalisé (voir API Push), ne peut pas coexister avec notification "options": "object", // Optionnel, options de push (voir API Push) "custom_args": "object" // Optionnel, paramètres transmis au client } ] }

              
              {
  "requests": [
    {
      "target": "string",     // Obligatoire, cible du push (registration_id ou alias)
      "platform": "string",   // Obligatoire, paramètres de la plateforme de push (voir API Push)
      "notification": "object",  // Optionnel, contenu de la notification (voir API Push)
      "message": "object",     // Optionnel, message personnalisé (voir API Push), ne peut pas coexister avec notification
      "options": "object",     // Optionnel, options de push (voir API 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` unique par lot)
`target`	Oui	string	Valeur cible : - endpoint `/regid` : `registration_id` - endpoint `/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 Push)
`message`	Non	object	Message personnalisé (même structure que l'API Push)
`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 (tous réussis)

{ "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 de débit partielle)

{ "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 atteinte pour l'API" } }, "170976fa8a9277c25d4": { "target": "170976fa8a9277c25d4", "success": false, "error": { "code": 23008, "message": "Limite de débit atteinte 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 atteinte pour l'API"
            }
        },
        "170976fa8a9277c25d4": {
            "target": "170976fa8a9277c25d4",
            "success": false,
            "error": {
                "code": 23008,
                "message": "Limite de débit atteinte 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 de base" } }

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

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 de base	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 système interne (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 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

Codes d'erreur complets : Create Push API - Réponse

Remarques

Gestion de la limitation de débit : Retourne des résultats partiellement réussis 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) interrompent immédiatement sans résultat partiel.