Quelques généralités sur l’API

L’API Campaign expose l’ensemble des fonctionnalités de la plateforme Campaign via une interface de programmation normalisée.

Plateforme Campaign by Dolist

Campaign est une suite complète d’outils de communication SaaS, comprenant le messaging par courrier électronique, les SMS et le marketing automation.

L’API Campaign est une API RESTful qui s’appuie sur le standard OpenAPI (Swagger RESTful API).

La documentation détaillée de l’API et l’interface de Swagger sont 2 outils qui vont vous permettre de tester l’intégralité des possibilités proposées par l’API Campaign.

Points de terminaison

L’accès à l’API s’effectue en adressant des requêtes HTTPS à une url de point de terminaison spécifique, dans laquelle les méthodes GET, POST, PUT et DELETE pilotent la manière dont vous interagissez avec les objets disponibles.

L’API est accessible uniquement via un protocole sécurisé HTTPS (certificat TLS).

Point de terminaison de l’API : https://apiv9.dolist.net/v1/

Authentification à l’API

Pour accéder à l’API vous aurez besoin d’une clé d’authentification et d’un numéro de compte (AccountID dans l’API).

Requêtes

Les demandes doivent être envoyées via HTTPS avec les paramètres formatés en JSON (application/json). Toutes les requêtes doivent inclure les en-têtes accept: application/json et X-API-Key : xxxxxxx.

Exemple d’appel en curl :

Curl -X GET "https://apiv9.dolist.net/v1/applications"
-H "accept: application/json"
-H "X-API-Key: votre_clé_API"

Cette documentation vous propose des exemples de codes pour chaque méthode de l’API dans de nombreux languages (Shell, Go, Java, Javascript, Node; Obj-C, php, Python, PowerShell, Ruby, Swift, C#, C, etc…).

Langues de l’API et format des dates / heures

L’en-tête Accept-Language de la requête indique dans quelles langues sont attendues les données en entrée et en sortie de l’API. L’API permet de dialoguer en 3 langues (français, anglais et espagnol).

Par exemple une requête avec en entête Http :

  • Accept-Language: fr-FR,fr;q=0.9,en-US;q=0.8,en;q=0.7 retournera des réponses en français
  • Accept-Language: en-US,en;q=0.9,fr-FR;q=0.8,fr;q=0.7 retournera des réponses en anglais
  • Accept-Language: es-ES,es;q=0.9,fr-FR;q=0.8,fr;q=0.7 retournera des réponses en espagnol

Ce paramètre Accept-Language lorsqu’il est spécifié dans l’entête de la requête permettra de s’assurer du format des dates attendu par l’API. En français une date en entrée de l’API pourra être jj/mm/AAAA ou jj-mm-AAAA ou ddmmAAAA alors qu’en anglais les dates respecteront les formats YYYY/mm/dd ou YYYY/mm/dd ou YYYYmmdd par exemple.

La langue par défaut de l’API est l’anglais (si l’en-tête Accept-Language de la requête n’est pas précisée). Tous les paramètres de date de l’API sont des dates / heures qui s’appuient sur le format ISO-8601.

Réponses

L’API renverra pour chaque requête un code de statut qui s’appuie sur la norme RFC 2616 :

  • 200 et 201 et 204 : Succès de la requête.
  • 403 : Droit insuffisant pour effectuer cette tâche ou accès refusé.
  • 404 : Erreur fonctionnelle lors de l’opération (POST et PUT).
  • 500 et 503 : Une exception inattendue est survenue. Veuillez contacter le support.

Attention, si vous obtenez le code erreur 403 et la réponse suivante de l’API :

{
  "ResponseStatus": {
    "ErrorCode": "Forbidden",
    "Message": "Unauthorized request blocked."
  }
}

merci de vous assurer que :

  • Le numéro de compte AccountID saisi est correct.
  • La clé d’authentification X-API-Key saisie est bien liée au compte et correcte.
  • L’adresse IP utilisée par la machine qui réalise l’appel est bien renseignée dans le portail Client Dolist par l’administrateur de votre compte.

L’API peut renvoyer en fonction de la requête 3 types de réponses :

  1. Une réponse vide (par exemple dans le cas d’une mise à jour de données réalisée avec succès lors d’un POST ou un PUT).
  2. Un objet JSON correspondant aux résultats de la requête jouée avec succès.
  3. En cas d’erreur, l’objet JSON contiendra un code et une description de l’erreur.

Pagination

Nom Type Description
limit entier Le nombre de résultats retournés par la requête
offset entier L’index du résultat retourné par la requête

L’API n’a pas de limite dans le nombre de résultats qu’elle retourne (excepté pour la méthode qui permet de rechercher des contacts POST/contacts/search qui retournera au maximum 50 résultats).

Il est pour autant possible de paginer les résultats en utilisant les paramétres de requête offset et limit.

Toutes les réponses qui comportent plusieurs résultats débuteront par :

{
  "Count": 20,   // Nombre de résultats renvoyés dans la réponse actuelle
  "Total": 62,  // Nombre total de résultats de la requête
  "ItemList": [
    { .......

Afin de récupérer 20 résultats à chaque appel pour des raisons d’affichage par exemple, on réalisera :

  • Un premier appel pour récupérer les 20 premiers résultats en passant offset à 0 et limit à 20
  • Un deuxième appel pour récupérer les 20 résultats suivants en passant offset à 20 et limit à 20
  • Un troisième appel pour récupérer les 20 résultats suivants en passant offset à 40 et limit à 20
  • Un dernier appel pour récupérer les 2 derniers résultats en passant offset à 60 et limit à 20