Contact
Les contacts peuvent être manipulés à travers l'objet ncContact dans l'API.
L'objet ncContact
Le contact récupéré ou à insérer via l'API est un objet comprenant les méthodes suivantes :
Guid : L'identifiant du compte
Label : Le nom et le prénom du contact
Name
: Le nom de famille
FirstName
: Le prénom
Extcode
: Code externe (celui d'une application externe par exemple)
Function
: La fonction dans l'entreprise
Gender
: L'appelation (Monsieur, Madame...)
Phone
: Le téléphone fixe
Cell
: Le téléphone mobile
Fax
: Le fax
EMail
: L'EMail
AssignedTo
: A quelle personne est-il affecté (de la forme {FullName:'', Guid:'', Extcode:''})
Origin : L'origine du contact. A renseigner comme suit : { Code : 'XXXX' }. Le code doit être défini dans la liste Origine au niveau de l'application Koban
AssignedTo
: A quelle personne est-il affecté (de la forme {FullName:'', Guid:'', Extcode:''})
Origin : L'origine du contact. A renseigner comme suit : { Code : 'XXXX' }. Le code doit être défini dans la liste Origine au niveau de l'application Koban
Third
: Un objet ncThird représentant le compte associé au contact
Chaque objet dispose également d'une propriété Updated spécifiant la dernière date de modification.
Méthodes disponibles
-
GET https://app-koban.com/api/v1/ncContact/GetUpdated Tester
Renvoie la liste des contacts créés ou modifiés depuis une date de référence
Paramètres :
- updated : date timestamp UNIX. date de référence
- l : Entier: Longueur de la liste renvoyée (pagination)
- s : Entier: Index de départ (pagination)
-
GET https://app-koban.com/api/v1/ncContact/GetOne Tester
Renvoie un contact à partir de son identifiant
Paramètres :
- id : Identifiant (Guid) du contact
-
GET https://app-koban.com/api/v1/ncContact/GetByEMail Tester
Renvoie un contact à partir de son email
Paramètres :
-
GET https://app-koban.com/api/v1/ncContact/GetSearch Tester
Renvoie la liste des contacts d'un compte correspondant à une chaine de recherche
Paramètres :
- search : chaine de recherche sur le nom de famille (elle peut être vide, dans ce cas tous les contacts du compte sont renvoyés).
- thirdid : Identifiant (guid) du compte
-
POST https://app-koban.com/api/v1/ncContact/Many
Crée ou modifie un ensemble de contacts. Si un contact correspondant à la clé uniqueproperty existe, alors l'API effectue une création. Sinon l'API met à jour le contact. Le compte associé est recherché également à partir de sa propre clé. Si le compte n'est pas trouvé, alors le contact n'est pas créé
Paramètres :
- uniqueproperty : Propriété sélectionnée pour vérifier si le contact doit être créé ou modifié. Peut prendre la valeur : Email (Email), Guid (Identifiant), Extcode (Code externe), NameFirstname (Nom et prénom). L'API vérifie qu'un contact correspondant à cette clé existe. Si il existe, il effectue une modification, sinon il effectue une création
- thirduniqueproperty : Propriété sélectionnée pour sélectioner le compte transmis. Peut prendre la valeur : Email (Email), Guid (Identifiant), Extcode (Code externe), NameAddress (Nom et code postal). L'API vérifie qu'un compte correspondant à cette clé existe. Si il existe, il est associé au contact.
- Corps de la requête : Liste des comptes en tableau d'objet ncThird JSON
Exemples
Création ou modification de plusieurs contacts
Cet exemple lance la création ou la modification de 3 contacts dans Koban à partir d'une application tierce :
- Marie DURAND - marie9855@gmail.com, dont nous disposons des coordonnées téléphonique, de la société ACME (Code 10001). Son centre d'intérêt est Cuisine.
- Hervé DUPOND - herve.dupont@outlook.com, dont nous ne disposons pas des coordonnées téléphonique, de la société ACME (Code 10001). Ses centres d'intérêts sont Bricolage et Poterie. Il est inscrit à la newsletter
- Jean OVAGNA - jean.ovagna@polimat.fr, dont nous disposons des coordonnées téléphonique, de la société Polimat (Code 10002). Pas de centre d'intérêt.
Les comptes auront préalablement été créés ou mis à jour grâce à la méthode d'API ncThird/PostMany.
Paramétrage préalable de Koban dans ce cas :
- La liste origine paramétrée avec une valeur de liste "Origine Application tierce" dont le code est "TIERS".
- Une catégorie de tag "Centre d'intérêt" dont le code Koban est "INTERET". Cette catégorie dispose des tags Poterie, Cuisine, Bricolage, Escalade.
- Une liste de diffusion "Newsletter" dont le guid Koban est "nl_5704ffda0dc3640c748f843a" (Accessible au niveau des champs personnalisés du contact Paramètres > Comptes et Contacts > Personnalisation Contact)
L'appel se fera sur la clé EMail pour dédoublonner les contacts avant insertion ou mise à jour sur l'email. Le compte associé sera repéré grâce à la propriété Code Externe Extcode
POST /api/v1/ncContact/PostMany?uniqueproperty=Email&thirduniqueproperty=Extcode HTTP/1.1
Host: app-koban.com
X-ncApi: XXXXXXXXXXXX
X-ncUser: XXXXXXXXXXXX
Accept: application/json
Content-Type: application/json
Cache-Control: no-cache
[{ "Name":"DURAND",
"FirstName":"Marie",
"EMail":"marie9855@gmail.com",
"Phone":"04 11 22 55 11",
"Mobile":"06 44 86 48 55",
"Third":{
"Code": "10001"
},
"Tags":[{
"TagCategoryCode":"INTERET","Label":"Cuisine"
}]
},
{ "Name":"DUPOND",
"FirstName":"Hervé",
"EMail":"herve.dupont@outlook.com",
"MoreFields":[
{ "FieldId": "nl_5704ffda0dc3640c748f843a",
"Value": "true" }
],
"Third":{
"Code": "10001"
},
"Tags":[{
"TagCategoryCode":"INTERET",
"Label":"Bricolage"
},
{
"TagCategoryCode":"INTERET",
"Label":"Poterie"
}]
},
{ "Name": "OVAGNA",
"FirstName": "Jean",
"EMail": "jean.ovagna@polimat.fr",
"Function": "Directeur",
"Phone":"04 88 55 11 44",
"Third":{
"Code": "10002"
}
}
]
Résultat
201 Created
{
"Result": [
"XXXXXXXXXXXX",
"XXXXXXXXXXXX",
"XXXXXXXXXXXX"
],
"Success": true,
"Message": null,
"Errors": null
}
Revenir à la liste des méthodes