Aller au contenu principal

Webservices & Webhooks

Webservices​

Actito a pour vocation de vous proposer une grande connectivité dans votre approche marketing. De ce fait, nous veillons particulièrement à permettre les échanges de données entre Actito et les autres systèmes, propres à votre activité.

L'API publique mises à votre disposition vous permettent dès lors d'interagir directement avec Actito sans devoir passer par l'interface. Par le biais des webservices, vous allez être en mesure d'appeler des données présentes dans Actito et d'obtenir ces données comme réponse. Vous pouvez également programmer l'envoi des données de votre système vers Actito.

Plus qu'un simple procédé d'échange de données, les webservices Actito vous permettent également d'activer l'utilisation de ces données, mais aussi d'en automatiser le traitement.

En effet, l'API se compose d'une série de routes, groupées en catégories correspondant aux différents canaux et applications d'Actito. Pratiquement tout ce qui peut être réalisé dans l'interface Actito peut être automatisé à travers notre API publique.

Alt text

Accès aux API Publiques​

Actito met à disposition des accès Webservices dans 4 environnements : 1 environnement de PREPROD et les 3 environnements de PROD.

La documentation technique est disponible en ligne et en anglais sur notre portail dévelopeurs. Elles sont constamment maintenues à jour.

Avertissement

La section "Webservices" de la documentation plateforme sert à vous donner une perspective business de ce qui est possible de faire à travers l'API Actito.

Pour les détails d'implémentation, les dévelopeurs doivent toujours se référer aux spécifications API sur le Developers Portal (lien ci-dessus).

Création de compte utilisateur Webservices et authentification​

L’utilisation des API se fait de manière authentifiée. Il s'agit de comptes spécifiques séparés des comptes utilisateurs pour la plateforme.

L'API Actito utilise une authentification basée sur le principe de clé API.

Authentification par clé API​

Les utilisateurs Adminstrateurs de votre licence a la possibilité de paramétrer directement vos clés API (voir "Gérer les utilisateurs API")

Astuce

Lors de la création d'utilisateur API, il convient de l'associer à l'adresse e-mail d'une personne responsable de la maintenant de vos API. En effet, cette addresse sera utilisée pour vous notifier de tout changement impactant vos intégrations.

Pour paramétrer des appels API, la clé API ne doit pas être utilisée directement comme identifiant.

Elle va servir a générer un token d'accès à la validité limitée dans le temps (15 minutes), qui lui devrait être poussé dans tous les appels.

Par exemple, pour générer un token en environnement de TEST, l'appel sera

GET https://api-pre1.actito.com/auth/token

avec la clé API dans l'entête 'Authorization'

GET Token

curl
 -X GET 'https://api-pre1.actito.com/auth/token' \
 -H 'Authorization: qhdfbvdh747R49FRHrthqXXXXXXX' \
 -H 'Accept: application/json'

Vous obtiendrez un token (dans le paramètre 'accessToken' de la réponse)

Reponse GET Token

{
 "accessToken": "AAAAAAAAAAAAAAAAAAAAAMLheAAAAAAA0%2BuSeid%2BULvsea4JtiGRiSDSJSI%3DEUifiRBkKG5E2XzMDjRfl76ZC9Ub0wnz4XsNiRVBChTYbJcE3F",
 "tokenType": "bearer",
 "expiresIn": "900s",
 "scope": "read write",
 "jti": "ce6c1d3c-ab49-4b62-8f4c-964351ac5d58"
}

Le token obtenu servira à l'authentification de tous les appels dans les 15 minutes suivantes. Il devra être passé comme 'Authorization' de type 'Bearer' dans tous les appels.

Exemple Bearer Token

curl
 -X GET 'https://api-pre1.actito.com/v5/entities/MyEntity/etls' \
 -H "Authorization: Bearer
                      AAAAAAAAAAAAAAAAAAAAAMLheAAAAAAA0%2BuSeid%2BULvsea4JtiGRiSDSJSI%3DEUifiRBkKG5E2XzMDjRfl76ZC9Ub0wnz4XsNiRVBChTYbJcE3F" \
 -H 'Accept: application/json'

Version des API publiques​

Actito améliore son produit quotidiennement et travaille activement à élargir sa plateforme d'Intégrations.

Toutes les dernières routes développées peuvent être reconnues au v5 dans leur path. La philosophie de la V5 est de suivre de près les usages standards des API REST et d'améliorer la cohérence de leur comportement selon les ressources.

Il n'est pas prévu d'entièrement déprécier la V4 ou de la remplacer dans son ensemble avec des routes V5. Cependant, des changements peuvent survenir sur des routes V4 individuelles. Elles seront annoncées à travers le processus documenté ici.

Concepts Actito accessibles par Webservices​

Chaque opération est regroupée sous un concept, qui correspond à la catégorie de ressources Actito sur laquelle l'opération va être appliquée.

Chacun de ces concepts peut faire appel à une ou plusieurs méthodes, selon sa nature et selon les opérations s'y rapportant qu'il est possible de faire.

Pour vous familiariser avec les différents concepts avec lesquels il est possible d'interagir via l'API Actito, nous vous invitons à lire le chapitre consacré aux "Concepts Actito accessibles par Webservice".

Webhooks​

Actito a pour vocation de vous proposer une grande connectivité dans votre approche marketing. De ce fait, nous veillons particulièrement à permettre les échanges de données entre Actito et les autres systèmes, propres à votre activité.

Plusieurs solutions vous permettent d'interagir directement avec Actito sans devoir passer par l'interface. L'API publique d'Actito vous permettaient déjà d'appeler des données présentes dans Actito et d'envoyer des données vers Actito.

Les Webhooks vous offrent le service inverse des Webservices. Il n'est plus nécessaire de faire un appel à chaque fois que vous avez besoin d'une information. En effet, les Webhooks sont à l'écoute de l'information. En vous abonnant à des Webhooks, ceux-ci vous permettent d'être notifié directement d'événements survenus sur un profil ou une entrée dans une table mauve. Ces événements seront communiqués sur une URL que vous avez renseignée.

Avertissement

Cette section de la documentation plateforme sert à vous donner une perspective business de ce qui est possible de faire à travers la plateforme d'intégration d'Actito

Pour les détails d'implémentation, les dévelopeurs doivent toujours se référer aux spécifications sur le Developers Portal.

Contexte​

Événements concernés​

Les Webhooks vous permettent d'être notifié des événements concernant les tables de profils et les tables personnalisées du modèle de données.

Ces événements sont de la nature suivante :

  • CREATE : Ceci vous permet d'être notifié lors de la création d'un nouveau profil ou d'un nouvel enregistrement de données
  • UPDATE : Ceci vous permet d'être notifié à chaque changement sur un profil ou sur un enregistrement de données. Il est possible de spécifier exactement quels champs de la table doivent être pris en compte
  • DELETE : Ceci vous permet d'être notifié lors de la suppression d’un profil ou d’un enregistrement
  • UPDATED_SEGMENT et UPDATED_SUBSCRIPTION : Ces événements sont spécifiques aux tables de profils. Ils vous permettent d'être notifié lors d'un changement d'abonnement ou de segmentation
A savoir

Pour les tables personnalisées du modèle en étoile, il est nécessaire que les événements soient précisés dans le fichier JSON de définition de la table (dans le paramètre "eventToTrigger").
Un événement CREATE existe toujours par défaut dans les tables personnalisées, mais les événements d'UPDATE doivent être définis (notamment pour définir les mises à jour de quels champs déclenchent un événement).
N'hésitez pas à contacter votre gestionnaire de compte si vous avez besoin d'aide pour mettre en place des événements dans vos tables.

En plus de récupérer les informations de vos tables, les webhooks peuvent aussi récupérer les statuts de vos ETLs et synchronisation de de fichier, ou connecter vos scenarios à des systèmes externes grâce aux custom actions.

Protocole​

Chaque fois qu'un événement correspondant à la définition de l'abonnement Webhook est enregistré dans Actito, le Webhook va pousser l'information sur l'URL que vous avez renseignée.

Pour vous aider à gérer les plus gros volumes, les appels peuvent être faits en mode unitaire ou en masse. Le mode de masse est utile quand plusieurs éléments sont impactés en même temps (comme dans un import par fichier), pour regrouper les mises à jours dans un appel. Néanmoins, lew webhooks récupèrent toujours l'information en temps réel : même en mode de masse, si 1 événement est enregistré et qu'un 2em événement n'est pas enregistré dans les secondes qui suivent, la notification par webhook sera envoyée.

Accès​

Pour recevoir des notifications chaque fois qu'un des événements survient dans la table écoutée, il est nécessaire de créer un abonnement à un Webhook. Un abonnement Webhook doit être créé par événement écouté et par table écoutée.

La création et la gestion de ces abonnements se fait via les APIs d'Actito. Leur définition est disponible sur la documentation technique.