Webservices liés aux profils

La notion de "Profils" dans ACTITO permet de gérer des tables de données vers lesquelles il sera possible de communiquer. Par exemple, un "profil" est une personne cliente, un prospect, un partenaire, … qui pourra recevoir une communication via un des canaux d’ "interaction" disponibles dans ACTITO (e-mail, SMS, campagne papier, … )

Ces tables de profils sont structurées grâce à 3 types de données :

  • des attributs

  • des abonnements

  • des segmentations

Pour plus d'informations concernant la mise en place de votre base de données de profils et de ses composants, nous vous invitons à vous référer au chapitre consacré aux "Profils".

Les APIs de Profils

Créer votre table de profils n'est pas possible via les APIs ACTITO. Il est nécessaire de la créer directement via l'interface.

La création de votre table de profils est donc un prérequis pour pouvoir utiliser les APIs de type "profile", qui permettent de gérer toutes les opérations en rapport avec les profils.

De plus, il est recommandé que cette table soit populée d'au moins 1 profil, et ce afin de faciliter l'implémentation des APIs. Cela vous permettra en effet d'identifier plus facilement la structure de la table, et surtout les éléments qui sont attendus pour paramétrer les attributs, abonnements et segmentations qui composent un profil.

Les APIs de profils vous donnent par contre la possibilité de :

  • Obtenir la structure d'une table de profils

  • Obtenir des informations concernant les profils

  • Créer, mettre à jour et supprimer des profils

images/download/attachments/615292219/image2019-3-13_17-1-34.png images/download/attachments/615292219/image2019-3-13_17-0-17.png

Obtenir la structure d'une table de profils

ACTITO vous permet de créer votre propre structure pour vos tables de profils. En effet, même si des attributs prédéfinis sont suggérés, vous restez libre de choisir lesquels utiliser, d'en créer de nouveaux ainsi que de mettre en place des abonnements et des segmentations.

Une fois créée dans l'interface ACTITO, la table de profils sera caractérisée par :

  • Un nom "t". Par exemple, "DemoDoc"

  • Une entité "e", qui correspond aux droits d'accès. Dans cet exemple : "actito"

Vous pouvez utiliser l'opération GET/entity/{e}/table/{t} pour obtenir la structure de cette table de profils.

Ceci vous permettra de comprendre comment la structure de votre table, que vous avez créé dans l'interface ACTITO, se traduit dans l'API. Grâce à cette information vous pourrez plus facilement programmer des méthodes POST ou PUT pour créer un import de profils en utilisant correctement tous les éléments qui constituent votre table de profils.

Pour ce faire, entrez le nom de l'entité et de la table de profils comme paramètres.

images/download/attachments/615292219/image2019-3-14_9-31-54.png

Astuce

La casse n'est pas prise en compte au niveau des noms.

Exemple de requête et de réponse pour cette opération : (Téléchargez cet exemple)

GET/entity/{e}/table/{t}
Curl call:
curl -X GET --header "Accept: application/json" https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/table/DemoDoc
 
Response body:
 
{
"id": 45,
"name": "DemoDoc",
"attributes": {
"addressCountry": {
"mandatory": false,
"multiValue": false,
"unicity": "NOT_UNIQUE",
"modifiable": true,
"valueType": "Country",
"possibleValues": [],
"comment": "Address country"
},
"lastName": {
"mandatory": true,
"multiValue": false,
"unicity": "NOT_UNIQUE",
"modifiable": true,
"valueType": "Name",
"possibleValues": [],
"comment": "Last name"
},
"firstName": {
"mandatory": false,
"multiValue": false,
"unicity": "NOT_UNIQUE",
"modifiable": true,
"valueType": "Name",
"possibleValues": [],
"comment": "First name"
},
"emailAddress": {
"mandatory": true,
"multiValue": false,
"unicity": "NOT_UNIQUE",
"modifiable": true,
"valueType": "EmailAddress",
"possibleValues": [],
"comment": "e-Mail address"
},
"nbChildren": {
"mandatory": false,
"multiValue": false,
"unicity": "NOT_UNIQUE",
"modifiable": true,
"valueType": "Integer",
"possibleValues": [],
"comment": "Number of children"
},
"sex": {
"mandatory": false,
"multiValue": false,
"unicity": "NOT_UNIQUE",
"modifiable": true,
"valueType": "Sex",
"possibleValues": [],
"comment": "Sex"
},
"customerId": {
"mandatory": true,
"multiValue": false,
"unicity": "UNIQUE_FOR_ALL_ELEMENTS",
"modifiable": true,
"valueType": "Integer",
"possibleValues": [],
"comment": null
},
"addressLocality": {
"mandatory": false,
"multiValue": false,
"unicity": "NOT_UNIQUE",
"modifiable": true,
"valueType": "String",
"possibleValues": [],
"comment": "Address locality"
},
"rep": {
"mandatory": false,
"multiValue": false,
"unicity": "NOT_UNIQUE",
"modifiable": true,
"valueType": "String",
"possibleValues": [],
"comment": null
},
"birthDate": {
"mandatory": false,
"multiValue": false,
"unicity": "NOT_UNIQUE",
"modifiable": true,
"valueType": "Datum",
"possibleValues": [],
"comment": "Birth date"
},
"motherLanguage": {
"mandatory": false,
"multiValue": false,
"unicity": "NOT_UNIQUE",
"modifiable": true,
"valueType": "Language",
"possibleValues": [],
"comment": "Mother language"
},
"gsmNumber": {
"mandatory": false,
"multiValue": false,
"unicity": "NOT_UNIQUE",
"modifiable": true,
"valueType": "PhoneNumber",
"possibleValues": [],
"comment": "Mobile number"
}
},
"subscriptions": [
{
"name": "Info",
"id": 30
},
{
"name": "Newsletter",
"id": 29
},
{
"name": "Offer",
"id": 28
}
],
"segmentations": [
{
"segmentation": "IntrtProduit",
"exclusive": false,
"categories": [
"Member"
]
},
{
"segmentation": "Active",
"exclusive": false,
"categories": [
"Member"
]
}
]
}

Le corps de la réponse se caractérise par les 3 types d'éléments qui constituent la fiche de profil.

Les attributs

Les attributs de profils représentent les données principales des profils. Chaque attribut est défini par une série de paramètres qui caractérisent sa nature et l'utilisation qui sera faite de lui. Pour plus d'informations sur les attributs, nous vous invitons à lire le chapitre expliquant comment "Ajouter un attribut à la table de profil".

Le corps de la réponse présentera les attributs les uns à la suite des autres avec le détail de ses paramètres. Ceux-ci se caractérisent comme suit :

  • "mandatory" : Ce paramètre indique si l'attribut est obligatoire ou pas, sous format "true/false" (vrai ou faux).

  • "multiValue" : Ce paramètre indique si l'attribut peut avoir plusieurs valeurs ou pas, sous format "true/false" (vrai ou faux). Dans ce cas, les valeurs de l’attribut pour un profil particulier seront représentées comme suit : ["a","b"].

  • "unicity" renseigne le caractère unique ou non de l'attribut. Il peut être :

    • UNIQUE_FOR_ALL_ELEMENTS : la valeur ne pourra être présente que pour un seul profil dans toute la base de données. Ce sera le cas pour les attributs qui peuvent être utilisés comme clé (par exemple : clientId ou emailAddress)

    • NOT_UNIQUE : la valeur de cet attribut peut être identique pour plusieurs profils (par exemple, le prénom ou le pays).

    • UNIQUE_BY_ELEMENT : seulement applicable pour les attributs multi-valeurs. Cela implique que chaque valeur possible ne pourra apparaître qu'une fois pour chaque profil.

  • "valueType" : Ce paramètre indique le format attendu de l'attribut (par exemple : entier, booléen, numéro de téléphone, ...)

  • "possibleValues" : Ce paramètre indique les valeurs qui seront acceptées pour l'attribut. Les valeurs non-incluses dans cette restriction seront rejetées. Ce paramètre est optionnel.

  • "comment" : Ceci est description de l'attribut. Elle est optionnelle.

Les abonnements

Les abonnements représentent les opt-ins de chaque profil. Pour plus d'informations sur les abonnements, nous vous invitons à lire le chapitre expliquant comment "Ajouter un abonnement à la table de profil".

Dans le corps de la réponse de la requête webservice, ils sont renseignés sous le nom de "subscription" et se composent comme tels :

  • "name" : Ce paramètre indique le nom donné à l'attribut.

  • "id" : Ceci est l’identifiant technique auto-généré de l'attribut, propre à chaque base de données.

Les segmentations

Les segmentations permettent de regrouper des profils qui présentent des caractéristiques communes. Pour plus d'informations sur les segmentations, nous vous invitons à lire le chapitre expliquant comment "Ajouter une segmentation à la table de profil".

Dans le corps de la réponse de la requête webservice, elles sont renseignées sous le nom de "segmentation" et se caractérisent comme suit :

  • "segmentation" : Il s'agit du nom technique de la segmentation. Celui-ci est automatiquement généré à la création de la segmentation dans l'interface, sur base du nom d'affichage choisi, mais en supprimant les espaces et les caractères spéciaux. Veuillez noter que, s'il est possible de changer le nom d'affichage d''une segmentation dans l'interface, le nom technique n'est quant à lui pas modifiable et restera toujours celui d'origine.

  • "exclusive" : Ce paramètre indique s'il s'agit d'une segmentation exclusive, sous format "true/false" (vrai ou faux). Une segmentation exclusive se distingue d'une segmentation simple par l'existence de sous-catégories de segments.

  • "categories" :

    • Dans le cas des segmentations exclusives, ceci indique les différents segments auxquels le profil peut appartenir.

    • Pour les segmentations simples, la seule catégorie est "Member", indiquant si un profil appartient à la segmentation ou pas.

Obtenir les caractéristiques d'un profil

Obtenir les caractéristiques d'un profil donné

Une fois que vous avez pris connaissance de la structure de la table de profils, vous êtes en possession des éléments nécessaires pour correctement paramétrer les méthodes d'import de profils.

Cependant, il peut être utile d'obtenir des informations à propos des profils qui sont déjà présents dans votre base de données. Cela vous donnera un exemple concret des informations qui sont attendues lors des appels de création de profils, surtout en ce qui concerne les caractéristiques des attributs individuels. Par la suite, cette opération vous permettra appeler les données d'un profil, par exemple pour la consultation de leurs coordonnées dans un espace client.

Vous pouvez récupérer les détails concernant ce profil via l'opération GET/entity/{e}/table/{t}/profile/{p}

Pour ce faire, vous devrez renseigner comme paramètres :

  • L'entité

  • La table de profil

  • Le profil que vous voulez chercher : pour cela vous pouvez utiliser soit l'ID technique du profil (l'identifiant fourni par ACTITO à la création du profil, sous forme de "profileId") ou tout autre attribut que vous avez défini comme clé unique (par exemple : le numéro de client, l'adresse e-mail, ...). Dans le deuxième cas, il convient d'utiliser le format attributClé=valeur (par exemple, emailAddress=mailtest@actito.com). Pour connaître l'attribut servant de clé, référez-vous à la page "Accéder à la fiche d'un profil".

images/download/attachments/615292219/image2019-3-14_12-25-15.png

Exemple de requête et de réponse pour cette opération : (Téléchargez cet exemple)

GET/entity/{e}/table/{t}/profile/{p}
Curl call:
curl -X GET --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/table/demodoc/profile/147471"
 
Response body:
{
"attributes": [
{
"name": "profileId",
"value": "147471"
},
{
"name": "creationMoment",
"value": "14/02/2019 13:58:23"
},
{
"name": "updateMoment",
"value": "14/03/2019 12:22:33"
},
{
"name": "lastName",
"value": "Doe"
},
{
"name": "firstName",
"value": "Jane"
},
{
"name": "birthDate",
"value": "03/04/1956"
},
{
"name": "sex",
"value": "F"
},
{
"name": "motherLanguage",
"value": "EN"
},
{
"name": "emailAddress",
"value": "mailtest@citobi.com"
},
{
"name": "addressLocality",
"value": "Waterloo"
},
{
"name": "addressCountry",
"value": "BE"
},
{
"name": "gsmNumber",
"value": "1223344556"
},
{
"name": "customerId",
"value": 12189
},
{
"name": "nbChildren",
"value": 2
},
{
"name": "rep",
"value": "3"
}
],
"subscriptions": [
{
"name": "Newsletter",
"id": 29
}
],
"segmentations": [
{
"name": "TypeClient",
"category": "Silver"
},
{
"name": "Active",
"category": "Member"
}
]
}

Veuillez noter que certains attributs techniques sont automatiquement renseignés dans la réponse. Ces attributs ne sont pas modifiables. Il s'agit de :

  • "profileId" : L'identifiant technique auto-généré, que vous avez pu utiliser comme clé

  • "creationMoment" : La date et l'heure de création

  • "updateMoment" : La date et l'heure de la dernière mise à jour

Les abonnements et les segmentations affichés sont uniquement ceux actuellement associés au profil. Si ce dernier ne fait pas partie d'une segmentation ou d'un abonnement, il ne sera pas affiché.

Utiliser des paramètres de requête

Si vous ne connaissez pas le "profileId" ni les autres attributs clés d'un profil donné, ou si vous voulez obtenir une liste de profils sur base de critères spécifique, vous avez la possibilité d'utiliser des paramètres de requête (query parameters) via l'opération GET/entity/{e}/table{t}/profile

Ces paramètres de recherche sont :

  • "search" : Critère de recherche, pouvant être composé de plusieurs critères séparés par le signe ";". Ce critère doit être composé du nom technique d'un attribut, suivi de l'opérateur "=" et d'une valeur.

  • "dateFilter" : Critères de recherche concernant une date, pouvant être composé de plusieurs critères séparés par le signe ";". Ce critère doit porter sur les attributs "creationMoment" ou "updateMoment", suivi d'un opérateur (">", "<", ">=" ou "<="), puis d'une valeur de date.

  • "number" : Ce paramètre limite le nombre de résultats affichés (200 maximum et par défaut).

images/download/attachments/615292219/image2019-3-14_13-50-50.png

Imaginons que vous vouliez obtenir les détails d'un profil, n'importe lequel, afin de prendre connaissance de la structure d'une fiche profil, comme à l'étape précédente. Vous pouvez définir le filtre "number" à 1.

Obtenir les interactions d'un profil

Vous avez la possibilité d'obtenir les interactions d'un profil via l'opération GET/entity/{e}/table{t}/profile{p}/interactions

Les paramètres à renseigner dans ce cas sont l'entité, la table de profils et l'identifiant du profil. Ils seront accompagnés des critères suivants :

  • "dateFilter" : Il s'agit d'un filtre de date basé sur l'attribut "creationMoment"

  • "typeFilter" : Ceci est un filtre concernant le type d'interaction. Laissez ce champ vide pour inclure toutes les interactions. Un seul type d'interaction peut être ciblé à la fois. Si vous voulez cibler les interactions liées aux Custom Tables, il convient de choisir le filtre "UserDefined".

  • "includeTest" : Ce filtre permet d'inclure ou d'exclure les interactions de test.

images/download/attachments/615292219/image2019-3-14_14-38-54.png

Exemple de requête visant les interactions de type e-mail et sa réponse : (Téléchargez cet exemple)

GET/entity/{e}/table/{t}/profile/{p}/interactions
Curl call:
curl -X GET --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/table/demodoc/profile/147471/interactions?typeFilter=Mail&includeTest=true"
 
Response body:
{
"interactions": [
{
"id": "1854",
"type": "Mail",
"businessKey": "actito",
"attributes": {
"Status": "SENT_OPENED_WITH_CLICK",
"Test": "true",
"actitoInteractionId": "1854"
},
"campaignId": 178,
"creationMoment": "19/02/2019 15:12:28"
},
{
"id": "1869",
"type": "Mail",
"businessKey": "actito",
"attributes": {
"Status": "SENT_OPENED_WITH_CLICK",
"Test": "true",
"actitoInteractionId": "1869"
},
"campaignId": 178,
"creationMoment": "19/02/2019 15:31:05"
},
{
"id": "1875",
"type": "Mail",
"businessKey": "actito",
"attributes": {
"Status": "SENT_OPENED_WITH_CLICK",
"Test": "true",
"actitoInteractionId": "1875"
},
"campaignId": 178,
"creationMoment": "19/02/2019 15:36:24"
},
{
"id": "1909",
"type": "Mail",
"businessKey": "actito",
"attributes": {
"Status": "SENT_OPENED_WITH_CLICK",
"Test": "true",
"actitoInteractionId": "1909"
},
"campaignId": 178,
"creationMoment": "20/02/2019 11:54:41"
}
]
}

Obtenir les abonnements d'un profil

Vous avez la possibilité d'obtenir la liste des abonnements auxquels est souscrit un profil via l'opération GET/entity{e}/table{t}/profile{p}/subscription

Les paramètres à renseigner dans ce cas sont l'entité, la table de profils et l'identifiant du profil ("profileId" ou couple "attributClé=Valeur").

Exemple de requête et de réponse pour cette méthode : (Téléchargez cet exemple)

GET/entity/{e}/table/{t}/profile/{p}/subscription
Curl call:
curl -X GET --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/table/demodoc/profile/147471/subscription"
 
Response body:
{
"subscriptions": [
{
"name": "Newsletter",
"id": 29
},
{
"name": "Info",
"id": 30
}
]
}

Les abonnements affichés en réponse sont uniquement ceux auxquels le profil a souscrit actuellement. Si ce dernier n'est pas abonné à un abonnement, il ne sera pas affiché.

Obtenir les segmentations d'un profil

Vous avez la possibilité d'obtenir la liste des segmentations auxquelles un profil appartient via l'opération GET/entity{e}/table{t}/profile{p}/segmentation

Les paramètres à renseigner dans ce cas sont l'entité, la table de profils et l'identifiant du profil ("profileId" ou couple "attributClé=Valeur").

Exemple de requête et de réponse pour cette méthode : (Téléchargez cet exemple)

GET/entity/{e}/table/{t}/profile/{p}/segmentation
Curl call:
curl -X GET --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/table/demodoc/profile/147471/segmentation"
 
Response body:
{
"segmentation": [
{
"name": "TypeClient",
"category": "Silver"
},
{
"name": "Active",
"category": "Member"
}
]
}

Les segmentations affichées en réponse sont uniquement celles dont le profil fait partie. Si ce dernier ne fait pas partie d'une segmentation, elle ne sera pas affichée.

Créer ou mettre à jour un profil

Une fois que vous connaissez la structure d'une table de profil, il vous est possible de populer celle-ci directement via les webservices ACTITO.

Les APIs d'ACTITO proposent deux manières de créer ou mettre à jour des profils dans une base de données : un par un ou par lots. Le choix entre ces deux manières de procéder doit être fait à la fois par rapport aux besoins propres à votre activité, mais aussi par rapport aux limites à respecter concernant l'utilisation des webservices.

Il convient donc de se poser les questions suivantes :

  • Une synchronisation en temps réel est-elle nécessaire ?

  • Avez-vous pour but de déclencher des scénarios en temps réel ?

  • Quels sont les volumes à traiter ?

  • La méthode de votre choix est-elle compatible avec les limites d'utilisation ?

Les APIs d'import de masse doivent être utilisés quand les données peuvent être accumulées jusqu'à atteindre un volume suffisant pour un traitement par lots. La méthode d'import de masse n'a pas pour vocation de pousser de façon fréquentes des fichiers légers qui ne contiennent de quelques enregistrements. En effet, la limite est de 12 appels de masse par jour. De plus, les imports de masse sont asynchrones. Pousser plusieurs fichiers en même temps n'est pas une pratique convenue, étant donné qu'ils ne seront considérés que l'un à la suite de l'autre.

Par contre, quand les données sont utilisées pour déclencher un processus de travail ou qu'elles doivent être synchronisées de façon immédiate avec une base de données, il est préférable d'utiliser les appels un par un.

Si les spécificités de votre activité présentent un cas mixte de besoin de synchronisations en temps réel et de synchronisation journalière, il est conseillé de répartir les appels entre les imports de masse et les appels un par un au cas par cas selon les besoins de volume et d'immédiateté.

Créer ou mettre à jour un seul profil

De nombreuses opérations permettent de créer ou de mettre à jour les profils un par un. Un des avantages de cette manière de procéder est qu'il existe des opérations pré-paramétrées pour mettre à jour certains éléments spécifique d'une table de profils, comme les abonnements ou les segmentations.

Pour une explication détaillée concernant ces opérations, nous vous invitons à lire la page "Créer ou mettre à jour un seul profil".

Créer ou mettre à jour des profils en masse

Les imports de masse vont se faire sur base de fichiers contenant les données. Si certaines lignes de données tombent en erreur lors de la tentative d'import, elles seront détaillées afin de vous permettre de remédier au problème.

Pour découvrir le fonctionnement de cette méthode, nous vous dirigeons vers la page "Créer ou mettre à jour des profils en masse".