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é.
Les API publiques 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.
Accès aux API Publiques
ACTITO met à disposition des accès Webservices dans 2 environnements : en environnement de TEST et en environnement de PROD
La documentation technique est disponible en ligne et en anglais sur notre portail dévelopeurs. Elles sont constamment maintenues à jour.
La section "Webservices" de la documentation plateforme est utile pour avoir plus de contexte business, mais l'information concernant la mise en place des appels peut être obsolète.
Nous vous invitons à consulter la documentation pour développeurs pour tous les sujets techniques.
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.
Deux systèmes d'authentification coexistent actuellement :
-
l'authentification basique ("HTTP basic authentication")
-
l'authentification par clé API (API key)
Authentification basique
L'authentification basique se fait grâce à un compte Webservice et un mot de passe. Ce compte spécifique se distingue de votre accès classique au premier coup d'oeil par le fait que "webservices" ou "WS" sera toujours mentionné dedans. Il vous a été communiqué par votre gestionnaire de compte ou l'équipe Support.
Pour vous connecter, le nom d'utilisateur à renseigner correspond au nom de la licence suivi de votre compte Webservice, avec le format "licence/compteWS"
Les identifiants devront ensuite être encodés en base64 en respectant le format : "nomUtilisateur:motDePasse"
Par exemple, pour la licence "ActitoIODemo", avec un compte Webservice "WebServices_test" et un mot de passe "NBCJD44DLFNX$", l'entête 'Authorization' de votre appel devra être :
Basic base64(“ActitoIODemo/WebServices_test:NBCJD44DLFNX$”)
ou, directement encodé en base 64 :
Basic QWN0aXRvSU9EZW1vL1dlYlNlcnZpY2VzX3Rlc3Q6TkJDSkQ0NERMRk5YJA==
L'authentification basique supporte uniquement la version 4 (voir section suivante) de nos APIs. Elle est donc en cours de dépréciation : les comptes en "basic auth" restent bien sûr fonctionnels, mais aucun nouvel accès n'est créé avec ce mode. Nous vous encourageons à utiliser les clés API.
Astuce
Des accès en authentification basique peuvent toujours être donnés pour certains connecteurs qui nécessitent ce mode d'authentification, comme notre intégration avec Zapier.
Authentification par clé API
L'authentification par clé API est le nouveau protocole utilisé pour se connecter aux APIs d'Actito. Elle permet à la fois d'accéder à la V4 et à la V5. L'AdminUser de votre licence a la possibilité de paramétrer directement vos clés API (voir "Gérer les utilisateurs API")
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://apitest.actito.com/auth/token
avec la clé API dans l'entête 'Authorization'
curl -X GET 'https://apitest.actito.com/auth/token' \
-H 'Authorization: qhdfbvdh747R49FRHrthqhdfbvdh74' \
-H 'Accept: application/json'
Vous obtiendrez un token (dans le paramètre 'accessToken' de la réponse)
{ "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.
curl -X GET 'https://apitest.actito.com/v5/entities/MyEntity/etls' \
-H "Authorization: Bearer
eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0IiwiaWF0IjoxNTg2ODY1MjE1LCJpc3MiOiJhY3RpdG8iLCJleHAiOjE1ODY4NjYxMTUsImxpY2VuY2VJZCI6MTI3NDAsImFjY291bnRJZCI6MTIsInBvbCI6Im1haW5Qb2xpY3lBcGkiLCJzdWIiOiI2ZWY3YjZmYS0wYTc1LTQ1YTYtYmE5My1iZGY5MmUyZjg3NDAifQ.umizXm0TueN6jRkMCaz9AnQP30qNxud5XIxnZiPzz24L8Aon7WKeJ8_49xcjsTe_v13nv4AI9991Mw_k9bvQffT__eikkv9UMmZ22wvQr5UxCH5Y-NkxFRctEGLjmkEdFFe2EuOkF1GjsIetPrJgY-_L6bpoa3G0o69IWavBIFowQtw_q0FOPaZ_JtBLiDiFH59IM5s4-8S-QAhGkGgjOhTzqBTyDBGj8cqnhvr9eFwgoxGSAZ1QLGU5yTRyIJm8Uaq97M5UhKn98ixK4oQhQvVKwW9MDgGyf0jLFLEFO7l9kyFON34OsxiTyK58U_OFJzehgxqRokBE3wXWo9rKEA" \
-H 'Accept: application/json'
Version des API publiques
Actito améliore son produit quotidiennement et travaille activement à élargir sa plateforme d'Intégrations.
C'est pourquoi nous avons sorti la V5 de nos API publiques, dont le but est de standardiser notre implémentation de garantir la cohérence entre les ressources. Toute nouvelle de l'API Actito sera exclusivement développée en V5.
Mais cela ne veut pas dire que la V4 n'est plus d'actualité ! Les deux versions coexistent actuellement et la dépréciation ne sera que progressive. Nous n'arrêterons jamais de supporter une version sans vous prévenir longtemps à l'avance, pour vous laisser le temps de migrer votre code vers la nouvelle version.
Version 4
Les routes V4 sont à la fois accessibles par authentification basique et par clé API. Sur la plateforme 'développeurs', toute route n'étant pas explicitement référencée comme V5 est en V4. Tous les appels présentés dans cette documentation dite 'business' (sur laquelle vous vous trouvez) sont en V4.
Pour se connecter en 'Basic Auth', le chemin est :
https://${env}.actito.com/ActitoWebServices/ws/v4
Pour se connecter à la V4 via clé API, le chemin est :
https://${env}.actito.com/v4
Rendez-vous sur la plateforme 'développeurs' pour connaître la valeur prise par la variable ${env} selon l'environnement sur lequel vous vous trouvez et obtenir l'url complète.
Astuce
En 'Basic Auth', l'url https://www.actito.be/ActitoWebServices/ws/v4 reste supportée.
Version 5
Les routes V5 sont uniquement accessible par authentification par clé API. Toute route V5 est explicitement identifiée comme telle. Il s'agit des derniers ajouts dans la librairie API Actito. Ces routes ne sont pas expliquées dans cette documentation dite 'business' mais uniquement sur la plateforme 'développeurs', plus adaptée pour cela.
Pour se connecter à la V5, le chemin est :
https://${env}.actito.com/v5
Rendez-vous sur la plateforme 'développeurs' pour connaître la valeur prise par la variable ${env} selon l'environnement sur lequel vous vous trouvez et obtenir l'url complète.
Astuce
Via clé API, l'appel pour obtenir un token est le même pour utiliser une route V4 ou V5. Il s'agira toujours de GET https://${env}.actito.com/auth/token
A savoir
Sur la plateforme 'développeur', chaque appel est directement testable via un formulaire en bas de page. Une variable {env.domain} peut être paramétrée pour garder en mémoire votre version et votre mode d'authentification comme expliqué en bas de cette page.
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".