Service de gestion de contacts

Contrat WSDL	http://api.dolist.net/v2/ContactManagementService.svc?wsdl
Exemple disponible	Implémentation en PHP.

Définition

Le service de gestion de contacts vous permet d'interagir avec les données contacts de la base de données Dolist.
L'ajout ou la modification de vos contacts sont réalisés de façon asynchrone.
Pour chaque demande de mise à jour, un numéro de ticket vous sera donné. Elles seront traitées dès que le service sera libre.
Vous devez faire appel à la méthode GetStatusByTicket pour savoir si la mise à jour a été correctement prise en compte.

Ajout d'un contact

Nom de la méthode : SaveContact

Cette méthode vous permet d'ajouter un contact dans votre base de données Dolist.
Si un contact existe déjà, les informations envoyées seront mises à jour. Seuls les champs présents dans le flux XML seront mis à jour. Les données vides ou non présentes n'effaceront pas les valeurs existantes dans la base de données.
Cette méthode vous permet également d'abonner ou désabonner un contact. Si un contact s'est désabonné par lui-même via notre lien de désinscription, vous pourrez le ré-abonner. Cependant, tous les contacts de type Hardbounce / Injoignables... ne pourront pas être modifiés.
Pour chaque appel à cette méthode, un numéro de ticket vous sera attribué.

Attention, la clé primaire est l'e-mail. Il n'est pas possible d'avoir le même e-mail présent plusieurs fois dans la base.

Les paramètres attendus en entrée

Champ	Type	Description
token	`AuthenticationTokenContext`	Jeton d'authentification
contact	`Contact`	Infos du contact

Les valeurs renvoyées

Type	Description
`string`	Renvoie le ticket de la demande

Statuts d'ajout/modification d'un contact

Nom de la méthode : GetStatusByTicket

Cette méthode vous indique si l'ajout ou la mise à jour du contact a bien été réalisé.

Les paramètres attendus en entrée

Champ	Type	Description
token	`AuthenticationTokenContext`	Jeton d'authentification
ticket	`string`	Ticket de la demande

Les valeurs renvoyées

Type	Description
`SavedContactInfo`	Résultat

Détail d'un contact

Nom de la méthode : GetContact

Vous pouvez récupérer l'ensemble des données de votre (ou vos) contact(s) en appelant cette méthode.
Vous pouvez définir des paramètres de sélection de champs pour obtenir seulement les informations souhaitées ou obtenir l'intégralité des champs en ne spécifiant rien.

Les paramètres attendus en entrée

Champ	Type	Description
token	`AuthenticationTokenContext`	Jeton d'authentification
request	`GetContactRequest`	Paramètre de la requête

Les valeurs renvoyées

Type	Description
`GetContactResponse`	Données des contacts

Statistique base de contacts

Nom de la méthode : GetContactCount

Vous pouvez récupérer le nombre de contacts de votre base réparti par optout et par canal de diffusion.
Vous pouvez spécifier uniquement l'optout et/ou le canal souhaités ou obtenir les statistiques de l'ensemble des contacts de la base.

Les paramètres attendus en entrée

Champ	Type	Description
token	`AuthenticationTokenContext`	Jeton d'authentification
request	`GetContactCountRequest`	Paramètres de la requête

Les valeurs renvoyées

Type	Description
`GetContactCountResponse`	Le nombre de contacts regroupé par optout et par canal de diffusion

Les objets du service de gestion des contacts

AuthenticationTokenContext

Champ	Type	Description
AccountID	`int`	Identifiant du client
Key	`string`	Clé du jeton d'authentification
ListID	`int`	Identifiant du client: obsolète. Utilisez AccountID à la place

ServiceException

Champ	Type	Description
Ticket	`string`	Le numéro de ticket
Message	`string`	Le message d'erreur
Description	`string`	La description de l'erreur
ErrorCodeType	`ErrorCodeType`	Type du code de l'erreur
ErrorCode	`int`	Code de l'erreur

Contact

Contact à mettre à jour.

Champ	Type	Description
Email	`string`	Email du contact
Fields	`Field[]`	Liste des champs du contact
InterestsToAdd	`int[]`	Liste des intérêts à ajouter
InterestsToDelete	`int[]`	Liste des intérêts à supprimer
OptoutEmail	`int`	Optout email du contact à modifier
OptoutMobile	`int`	Optout sms du contact à modifier

Les listes d'intérêts déclarés sont des listes d'identifiants d'intérêts déclarés que vous pouvez retrouver sur la plateforme Dolist dans l'onglet Administration, puis en "E.3 Les intérêts".
Les valeurs des optouts possibles sont :

0 : Inscription.
1 : Désinscription.

Field

Champ du contact à mettre à jour avec la valeur du contact.

Champ	Type	Description
Name	`string`	Nom du champ à sauvegarder
Value	`string`	Valeur du champ à sauvegarder

Les noms des champs correspondent aux champs d'un contact défini sur la plateforme Dolist dans l'onglet Administration, E.2 "Base de contact".
Les dates doivent être au format "yyyy-MM-dd HH:mm:ss"
Les champs "Civilité", "Pays" et "Format message" attendent des identifiants.

SavedContactInfo

Résultat de votre demande de mise à jour d'un contact.

Champ	Type	Description
Description	`string`	Description du résultat sur l'ajout ou la modification du contact
Email	`string`	Email du contact ajouté ou modifié
MemberId	`int`	Identifiant du contact ajouté ou modifié
ReturnCode	`int`	Code retour de l'ajout ou la modification du contact

Les codes de retour possible sur la mise à jour du contact :

-1 : En attente de traitement
0 : Erreur sur la mise à jour du contact
1 : Succès de la mise à jour du contact
402 : E-mail non autorisé par Dolist
403 : Email incorrect
404 : Modification impossible car e-mail de remplacement déjà présent en base
408 : Modification de l'optout e-mail non autorisé pour ce contact

GetContactRequest

Champ	Type	Description
AllFields	`boolean`	Indique si on doit retourner tous les champs
Culture	`string`	Culture de l'utilisateur
Interest	`boolean`	Indique si les intérêts déclarés sont retournés par la requête
LastModifiedOnly	`boolean`	Indique si la requête doit retourner uniquement les derniers contacts modifiés
Offset	`int`	L'indice du 1er contact retourné
RequestFilter	`RequestFilter`	Les critères de recherche des contacts
ReturnFields	`string[]`	La liste des champs d'un contact à retourner. Spécifier le nom du champ DOLIST

RequestFilter

Champ	Type	Description
Email	`string`	E-mail du contact
MemberID	`int`	Identifiant du contact

GetContactResponse

Champ	Type	Description
ContactList	`ContactData[]`	Liste des contacts
ReturnContactsCount	`int`	Le nombre des contacts retournés par la requête
TotalContactsCount	`int`	Le nombre total des contacts de la base correspondants aux critères de la requêtes

ContactData

Champ	Type	Description
CustomFields	`CustomField[]`	Liste des champs du contact
Email	`string`	Email du contact
Error	`int`	Compteur d'erreur du contact
Interests	`Interest[]`	Liste des intérêts déclarés du contact
MemberId	`int`	Identifiant du contact
OptoutEmail	`int`	Optout email du contact
OptoutMobile	`int`	Optout sms du contact
ReadOnly	`boolean`	Indique si le optout du contact est modifiable et si la suppression est autorisée
RentCount	`int`	Le compteur de location
Status	`int`	Status du contact
SubscribeDate	`dateTime`	Date d'inscription du contact
UnsubscribeDate	`dateTime`	Date de désabonnement du contact
UpdateDate	`dateTime`	Date de modification du contact

CustomField

Résultat de votre demande de mise à jour d'un contact.

Champ	Type	Description
CustomName	`string`	Nom personnalisé du champ
FieldType	`int`	Champ Système DOLIST - Typage de champ
Name	`string`	Nom du champ
Value	`string`	Valeur du champ

Référez vous à l'API de "listing des champs Dolist" pour connaitre les propriétés du champ.

1 : Chaine de caractères
2 : Entier
3 : Date
4 : Civilité
6 : Interet déclaré
7 : Entité gestionnaire
8 : Pays
9 : Html
10 : Url

GetContactCountRequest

Champ	Type	Description
Media	`Media`	Support de diffusion
Optout	`Optout`	Statut des contacts

Les valeurs possibles pour Media sont :

All : Tous les canaux
Email
Mobile

GetContactCountResponse

Champ	Type	Description
ContactCountList	`ContactCountPerOptout[]`	La répartition des contacts par optout et canal de diffusion

Les valeurs d'optout possibles sont :

All : Tous les contacts
Active : Contacts actifs
Unsubscribed : Contacts inactifs désabonnés
Unreachable : Contacts inactifs injoignables
Excluded : Contacts inactifs exclus
DolistInactive : Contacts inactifs Dolist
SubscriptionPending : Contacts inactifs temporaires - En attente d'inscription
SpamTemporary : Contacts inactifs temporaires - SPAM
RentedContactExpiration : inactifs temporaires - Expiration contact loué

ContactCountPerOptout

Champ	Type	Description
ContactCount	`int`	Le nombre de contacts correspondants à l'optout
Media	`Media`	Canal de diffusion
Optout	`Optout`	Statut du contact
RentedContactCount	`int`	Le nombre de contacts loués correspondants à l'optout

Interest

Champ	Type	Description
Group	`InterestGroup`	Groupe d'intérêt déclaré
InterestDate	`dateTime`	Date d'inscription à l'intérêt déclaré
Value	`InterestValue`	Intérêt déclaré

InterestGroup

Champ	Type	Description
Id	`int`	Identifiant du groupe d'intérêt déclaré
Name	`string`	Nom du groupe d'intérêt déclaré

InterestValue

Champ	Type	Description
Id	`int`	Identifiant de l'intérêt déclaré
Name	`string`	Nom de l'intérêt déclaré

Liste des erreurs communes

Code	Nom	Description
0	`UnexpectedException`	Erreur inattendue
1	`AuthenticationException`	Erreur d'authentification
2	`NullTokenException`	Le token est null, vérifiez que l'objet est correctement passé à la méthode et que les propriétés sont renseignées
3	`NullRequestException`	L'objet 'request' est null, vérifiez que l'objet est correctement passé à la méthode et que les propriétés sont renseignées
4	`ForbiddenActionException`	L'action demandée n'est pas autorisée
5	`InvalidArgumentException`	Les arguments passés à la méthode ne sont pas valides, vérifiez les types des propriétés, leurs noms et leur nullité
6	`BadRequestException`	La requête n'est pas correcte
7	`NothingToDoException`	La requête demandée n'effectue aucun traitement, car les données soient déjà à jour, il est possible que la requête ai été exécuté plusieurs fois
8	`InvalidDataTypeException`	Le type de donnée n'est pas valide
9	`UnknownTicketException`	Le ticket n'est pas connu, vérifiez la valeur de celui-ci
10	`UnavailableTicketResultException`	Le résultat associé n'est pas disponible, le traitement de la demande n'est pas terminé, veuillez réessayer plus tard.
11	`InvalidDatePeriodException`	L'intervalle de temps n'est pas valide, vérifiez les dates passées à la requête
999998	`TokenNull`	Le token est null, vérifiez que l'objet est correctement passé à la méthode et que les propriétés sont renseignées
999999	`TokenNotAuthorized`	L'objet 'token' n'est pas autorisé, vérifiez les propriétés