Raccourcit une URL cible en un lien court que vous pouvez ensuite utiliser dans le texte d'un message ou dans le portail BulkGate.

## URL de l'API

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

```url
https://portal.bulkgate.com/api/1.0/shortener/shorten
```

> [!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/shortener/shorten HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```

> [!NOTE]
> L'API est limitée à `20` requêtes par minute.

## 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 | [Token d'authentification de l'application](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/tokens-d-api/)	                       | **Oui**   | -             |
| target_url        | URL à raccourcir	                                                                | **Oui**   | -             |
| url_type          | Domaine du lien court, voir [Domaines pris en charge](#domaines-pris-en-charge) | Non        | `ur7.wf`      |

### Domaines pris en charge

Les valeurs de `url_type` relèvent de la configuration de l'instance et changent — la liste actuelle pour votre compte est renvoyée par l'[endpoint `domains`](https://www.bulkgate.com/fr/documentation/raccourcisseur-d-url/raccourcisseur-domaines-disponibles/). Au moment de la rédaction :

| DOMAINE             | RESTRICTION DE L'ADRESSE CIBLE                            |
|:--------------------|:----------------------------------------------------------|
| `ur7.wf`            | Aucune restriction. Valeur par défaut.                    |
| `ms6.fr`            | Aucune restriction.                                       |
| `ur7.yt`            | Uniquement les domaines cibles en liste blanche.          |
| `ur7.tf`            | Uniquement les domaines cibles en liste blanche.          |
| `ms6.wf`            | Uniquement les domaines cibles en liste blanche.          |
| `ms6.tf`            | Uniquement les domaines cibles en liste blanche.          |
| `track-message.com` | Uniquement les domaines cibles en liste blanche.          |

Pour les domaines restreints, l'adresse cible doit figurer sur la liste blanche de votre compte, sinon la requête échoue avec `domain_is_not_white_listed`. Quelques services publics (Google, YouTube, Facebook, GitHub et d'autres) sont toujours en liste blanche.

## Exemple de requête

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

{
  "application_id": 451,
  "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
  "target_url": "www.bulkgate.com",
  "url_type": "ur7.wf"
}
```

## Réponse

**En cas de succès :**

```json
{
    "data": {
        "short_url": "http://ur7.wf/W",
        "target_url": "http://www.bulkgate.com/",
        "final_url": "http://www.bulkgate.com",
        "title": "SMS & other channels for business communication | BulkGate",
        "expiration": "2026-10-10T09:00:00+02:00"
    }
}
```

Les liens créés via l'API sont valables **30 jours** — `expiration` contient la date d'expiration au format ISO 8601.

Les trois champs d'URL ne désignent pas la même chose :

| CHAMP        | VALEUR                                                                                                 |
|:-------------|:---------------------------------------------------------------------------------------------------------|
| `short_url`  | Le lien raccourci lui-même, construit à partir de `url_type` et de la clé générée                      |
| `target_url` | L'adresse telle qu'elle a été enregistrée — le schéma est ajouté s'il manque et l'URL est normalisée, ainsi `www.bulkgate.com` devient `http://www.bulkgate.com/` |
| `final_url`  | L'adresse que vous avez envoyée, seulement complétée du schéma. **Les redirections ne sont pas suivies**, ce n'est donc pas la page sur laquelle le visiteur arrive finalement |
| `title`      | Titre lu sur la page cible                                                                             |


**En cas d'erreur :**

```json
{
    "type": "url_is_not_valid",
    "code": 400,
    "error": "Url is not valid",
    "detail": null
}
```

```json
{
    "type": "the_per_minute_quota_has_been_exceeded",
    "code": 400,
    "error": "The per minute quota has been exceeded",
    "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** est le code d'erreur HTTP
- **detail** est une information complémentaire sur l'erreur

### Types d'erreurs de la Shortener API

Outre les [types généraux](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-api/), la Shortener API renvoie ses propres types :

| TYPE                                    | QUAND CELA SE PRODUIT                                                  |
|:----------------------------------------|:-----------------------------------------------------------------------|
| `url_is_not_valid`                      | `target_url` n'a pas pu être analysée.                                 |
| `url_type_is_incorrect`                 | `url_type` ne figure pas dans la liste des domaines du compte.         |
| `domain_is_not_white_listed`            | Le domaine cible n'est pas en liste blanche (pour les domaines restreints). |
| `url_is_not_allowed`                    | L'adresse cible pointe vers une adresse locale/interne.                |
| `url_can_not_be_redirected_out_of_target_domain` | L'adresse cible redirige en dehors de son propre domaine.     |
| `url_can_not_be_created`                | Le lien n'a pas pu être créé.                                          |
| `the_per_minute_quota_has_been_exceeded`| Le quota de 20 requêtes par minute est épuisé.                         |