## URL de l'API
URL utilisée pour l'envoi des requêtes HTTP :
```url
https://portal.bulkgate.com/api/1.0/advanced/promotional
```
> [!NOTE]
> Si la requête n'atteint pas sa destination, renvoyez-la sur le [serveur de secours](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/serveur-de-secours/) `backup1.bulkgate.com`.
## Méthodes HTTP prises en charge
- `POST` - `application/json`
```http
POST /api/1.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```
## Tableau des paramètres
| NOM DU PARAMÈTRE | VALEUR | OBLIGATOIRE | VALEUR PAR DÉFAUT |
|:------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------:|:-------------:|
| application_id | [ID d'application](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/administration-api/) | **Oui** | - |
| application_token | [Jeton d'application](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/tokens-d-api/) | **Oui** | - |
| number | Tableau des destinataires - [Valeur number](#valeur-number) | **Oui** ou `admins` ou `groups` | - |
| groups | Tableau des numéros de groupes du carnet d'adresses BulkGate. [Plus d'informations](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-promotional-envoi-aux-groupes-du-carnet-d-adresses/) | **Oui** ou `number` ou `admins` | - |
| admins | Tableau des numéros des administrateurs BulkGate qui reçoivent les notifications. [Plus d'informations](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-promotional-envoi-aux-administrateurs/) | **Oui** ou `number` ou `groups` | - |
| text | Texte du message SMS (612 caractères max., ou 268 caractères si l'Unicode est activé), encodage UTF-8 | **Oui**, si `number` est un tableau de numéros ou si le paramètre `groups` ou `admin` est utilisé | - |
| unicode | `Yes`/`true`/`1` pour un SMS Unicode, no/false/0 pour un SMS 7 bits | Non | `false` |
| sender_id | Identifiant d'expéditeur, voir [Type d'expéditeur](#type-d-expediteur-sender-id) | Non | `gSystem` |
| sender_id_value | Valeur de l'expéditeur - `gOwn` (p. ex. « 420 777 777 777 »), `gText` (p. ex. « BulkGate »), `gProfile` (p. ex. « 423 »), `gMobile` ou `gPush` [(CLÉ)](https://www.bulkgate.com/fr/centre-d-aide/mobile-connect/installation-mobile-connect/) | Non | `null` |
| country | Indiquez les numéros des destinataires au format international (avec l'indicatif, p. ex. `420`) ou ajoutez le [code pays](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`775123456` + `CZ` = `420775123456`). Voir l'exemple de requête avec pays. Si la valeur est **`null`**, le fuseau horaire que vous avez défini sert à compléter l'information | Non | `null` |
| schedule | Planification de la date et de l'heure d'envoi au format [timestamp Unix](https://en.wikipedia.org/wiki/Unix_time) ou [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Voir les exemples ci-dessous | Non | Maintenant |
| duplicates_check | Choisissez **`same_text`** pour éviter l'envoi de messages en double au même numéro de téléphone. Avec **`same_number`**, vous empêchez l'envoi au même numéro d'un message au texte identique comme différent. Avec **`null`**, aucun doublon n'est supprimé. Les doublons sont supprimés **uniquement au sein d'un même lot**, et non d'une requête à l'autre. | Non | `null` |
| tag | Libellé du message permettant à l'utilisateur de le retrouver ultérieurement. | Non | - |
### Valeur `number`
La valeur number peut être écrite de deux façons :
- Tableau de numéros de téléphone
```json
[
"420775123456",
"420606123456",
"44771447678"
]
```
- Tableau associatif avec la structure `number`, `text` et `variables`, dont le seul paramètre obligatoire est `number`. Si `number` n'est pas renseigné, le message est ignoré.
```json
[
{"number": "420775123456", "text": "test1 ", "variables": {"a": 5}},
{"number": "420606123456", "text": "test2 ", "variables": {"b": 5}},
{"number": "44771447678", "text": "test3 ", "variables": {"c": 3, "d": "abc"}}
]
```
Vous pouvez insérer les variables du tableau `variables` dans le modèle du paramètre `text`.
### Type d'expéditeur `sender_id`
| VALEUR | SIGNIFICATION |
|:-----------|:---------------------------------------------------------------------|
| `gSystem` | Numéro système |
| `gShort` | Short Code |
| `gText` | Expéditeur texte |
| `gMobile` | [Mobile Connect](https://www.bulkgate.com/fr/centre-d-aide/mobile-connect/installation-mobile-connect/) |
| `gPush` | Mobile Connect push - Envoie une notification dans l'application Mobile Connect |
| `gOwn` | Numéro personnel (nécessite la vérification du numéro) |
| `gProfile` | [ID de profil BulkGate](https://www.bulkgate.com/fr/centre-d-aide/sms/profil-d-expediteur/) |
| `` | ID de profil BulkGate |
## Exemples de requêtes
**Exemple de requête complète :**
```http-json
POST /api/1.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"number": [
{"number": "420775123456", "text": "test1 ", "variables": {"a": 5}},
{"number": "420606123456", "text": "test2 ", "variables": {"b": 5}},
{"number": "44771447678", "text": "test3 ", "variables": {"c": 3, "d": "abc"}}
],
"unicode": true,
"groups": [1, 2],
"admins": [1, 4],
"text": "Hello, ",
"sender_id": "gText",
"sender_id_value": "BulkGate",
"country": "cz",
"schedule": "2018-05-14T18:30:00-01:00"
}
```
**Exemple de requête indiquant les destinataires sous forme de tableau de numéros et planifiant l'envoi via un timestamp Unix :**
```http-json
POST /api/1.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"number": [
"420775123456",
"420606123456",
"44771447678"
],
"text": "Hello, ",
"schedule": "1526992636"
}
```
## Réponse
**En cas de succès :**
```json
{
"data": {
"total": {
"status": {
"sent": 0,
"accepted": 0,
"scheduled": 2,
"error": 0,
"blacklisted": 0,
"invalid_number": 1,
"invalid_sender": 0
}
},
"response": [
{
"status": "scheduled",
"sms_id": "idyrcmdd-0",
"part_id": [
"idyrcmdd-0_1",
"idyrcmdd-0"
],
"number": "420775123456",
"channel": "sms"
},
{
"status": "scheduled",
"sms_id": "idyrcmdd-1",
"part_id": [
"idyrcmdd-1_1",
"idyrcmdd-1"
],
"number": "420606123456",
"channel": "sms"
},
{
"status": "invalid_number",
"code": 400,
"error": "Invalid phone number",
"detail": null,
"number": "44771447678",
"channel": "sms"
}
]
}
}
```
Où :
- **part_ID** est le tableau des ID des parties du message long d'origine, scindé parce qu'il dépassait la limite de 160 caractères d'un message unique. Plus d'informations [ici](https://www.bulkgate.com/fr/centre-d-aide/sms/concatenation-des-messages/).
**En cas d'erreur :**
```json
{
"type": "invalid_phone_number",
"code": 400,
"error": "Invalid phone number",
"detail": null
}
```
```json
{
"type": "unknown_identity",
"code": 401,
"error": "Unknown identity / unauthorized / empty application_id",
"detail": null
}
```
Où :
- **type** et **error** (description de l'erreur) sont décrits dans le [tableau des types d'erreurs](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-api/)
- **code** représente le code d'erreur HTTP
- **detail** contient des informations complémentaires sur l'erreur
Tous les types d'erreurs de la Simple API et de l'Advanced API sont disponibles [ici](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-api/).