> [!CAUTION]
> Il est **strictement interdit** d'utiliser les notifications SMS à des fins promotionnelles ou marketing. Elles doivent servir uniquement à des fins de notification, en tant que [SMS transactionnel](https://www.bulkgate.com/fr/centre-d-aide/informations-generales/difference-messages-promotionnels-transactionnels/).

## URL de l'API

URL utilisée pour envoyer les requêtes HTTP :

```url
https://portal.bulkgate.com/api/1.0/advanced/transactional
```

> [!NOTE]
> Si la requête n'atteint pas sa destination, répétez-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/transactional 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 de l'application](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/administration-api/) | **Oui** | - |
| application_token | [Jeton de l'application](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/tokens-d-api/) | **Oui** | - |
| number            | Numéro du destinataire | **Oui** ou `admin` | - |
| admin             | Numéro de l'administrateur BulkGate qui reçoit la notification. [Plus d'informations](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-transactional-notifications-aux-administrateurs/) | **Oui** ou `number` | - |
| text              | Texte du message SMS (max. 612 caractères, ou 268 caractères si Unicode est activé), encodage UTF-8. Il est possible d'ajouter au modèle des variables provenant du tableau `variables` (autre paramètre) `Hello <first_name> <last_name> ....` | **Oui** | - |
| variables         | Tableau associatif pour ajouter des variables au texte, par ex. : `{"first_name": "John", "last_name": "Doe"}` | Non | `[]` |
| 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` (par ex. « 420 777 777 777 »), `gText` (par ex. « BulkGate »), `gProfile` (par ex. « 423 »), `gMobile` ou `gPush` [(KEY)](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 préfixe, par ex. `420`), ou ajoutez le [code pays](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`777777777` + `CZ` = `420777777777`). Voir l'exemple de requête avec le pays. Si la valeur est **`null`**, le fuseau horaire que vous avez défini est utilisé pour compléter l'information | Non | `null` |
| schedule          | Planifiez la date et 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). | Non | Maintenant |
| duplicates_check  | Choisissez **`on`** pour éviter l'envoi de messages en double au même numéro de téléphone. Les messages au texte identique envoyés au même numéro dans un intervalle de moins de 5 minutes seront supprimés. Avec **`off`**, aucun doublon n'est supprimé. | Non | `off` |
| tag               | Libellé du message permettant à l'utilisateur de le retrouver ultérieurement. | Non | - |

### Type d'expéditeur `sender_id`

| VALEUR | SIGNIFICATION |
|:--- |:---|
|`gSystem` |Numéro système| 
|`gShort`|Code court (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 propre (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/)|
| `<int>` |ID de profil BulkGate| 

## Exemple de requête

```http-json
POST /api/1.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",  	
	"number": "420777777777",
	"unicode": true,
	"text": "Bonjour, <first_name> <last_name>",
	"variables": {"first_name": "John", "last_name": "Doe"},
	"sender_id": "gText",
	"sender_id_value": "BulkGate",
	"country": "fr",
	"schedule": "2018-05-14T18:30:00-01:00"
}
```

## Réponse

**En cas de succès :**

```json
{
    "data": {
        "status": "accepted",
        "sms_id": "tmpde1bcd4b1d1",
        "part_id": [
            "tmpde1bcd4b1d1_1",
            "tmpde1bcd4b1d1"
        ],
        "number": "420777777777"
    }
}
```

Où :

- **part_ID** est le tableau des ID des parties du message long d'origine, qui a été découpé 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) figurent dans le [tableau des types d'erreurs](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-api/) 
- **code** correspond au code d'erreur HTTP
- **detail** contient des informations complémentaires sur l'erreur

Consultez tous les types d'erreurs de la Simple API et de l'Advanced API [ici](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-api/).