Aller au contenu principal

API Gesteos

Introduction​

Objectifs​

L'objectif de ce document est de définir :

  • Les principes généraux de fonctionnement des APIs

  • Les fonctionnalités exposées par l'API de Gesteos

Glossaire​

Tenant : instance d'une application GESTEOS (définie par un ou plusieurs noms de domaine)

L'identification est une phase qui consiste à établir l'identité de l'utilisateur. Elle permet répondre à la question : "Qui êtes-vous ?". L'utilisateur utilise un identifiant (que l'on nomme "Compte d'accès", "Nom d'utilisateur" ou "Login" en anglais) qui l'identifie et qui lui est attribué individuellement. Cet identifiant est unique.

L'authentification est une phase qui permet à l'utilisateur d'apporter la preuve de son identité. Elle intervient après la phase dite d'identification. Elle permet de répondre à la question : "Êtes-vous réellement cette personne ?". L'utilisateur utilise un authentifiant ou "code secret" que lui seul connait.

Principes fondamentaux​

Cette API doit respecter les critères suivants :

  • Sécurité

  • Robustesse

Sécurité​

La sécurité permet que seul un compte autorisé puisse effectuer une action.

On distingue plusieurs types d'autorisations :

  • Compte authentifié

  • Permissions

  • Filtrage par adresse IP

Compte authentifié​

L'accès aux APIs n'est disponible que pour un compte authentifié.

L'authentification passe par un token au format JWT fourni dans le header http Authorization.

Le compte est authentifié si :

  • Le compte est valide (existe)

  • La date d'expiration du token n'est pas atteinte

Permissions​

L'accès à une API n'est disponible que si le compte authentifié a les droits/permissions requises.

Filtrage par adresse IP​

L'accès à une API n'est disponible pour un compte authentifié que si l'adresse IP utilisée pour y accéder a été autorisée.

Robustesse​

La robustesse permet de s'assurer que l'application reste au maximum opérationnel.

La robustesse se fait au travers :

  • Performance des accès aux données

  • Protection contre une utilisation abusive

  • Versionning

Performance​

Différentes solutions pourront être mises en place pour améliorer la performance d'accès aux données :

  • Mise en cache (Redis ou autre solution)

  • Limiter les appels redondants à la base sur les mêmes données

Protection contre une utilisation abusive​

L'usage des APIs si elle n'est pas limitée/contrôlée peut causer des problèmes de performance sur l'application Gesteos voir un écroulement du serveur.

Pour limiter l'usage des APIs, il y a une mise en place de :

  • Stratégie de limitation d'usage des APIs par quota (throttling policy) : 1000 requêtes maximum autorisées par minute, paramétrable par compte.

Throttling policy​

Une throttling policy permet de limiter le nombre d'appels (quota) à une API par un client sur une période donnée.

Si le quota est atteint, les appels à l'API sont rejetés, jusqu'à ce que la période de référence soit écoulée.

Une throttling policy DOIT être définie pour chaque compte.

Versionning​

Le versionning permet que les applications clientes existantes ne soient pas impactées par une mise à disposition d'une nouvelle version d'une API existante.

Identification​

L'API d'identification implémente OAuth ou OpenIDConnect.

Cette API ne permet pas d'identifier un compte (pas de fourniture d'access_token à partir d'un login/mot de passe), mais permet de générer un access_token uniquement à partir d'un refresh_token.

Le refresh_token a une durée de vie glissante (i.e. sa date de validité est rafraichie à chaque demande de génération d'access_token) et pour une durée configurable (au bout de ce délai sans activité, le refresh_token n'est plus valide).

La demande de génération d'access_token ne renvoie pas de nouveau refresh_token, ni le refresh_token courant. L'access_token a une durée de validité configurable (15 minutes par défaut).

L'administrateur sécurité DOIT générer le refresh_token à fournir au client.

L'administrateur sécurité PEUT révoquer le refresh_token (exemple : sur demande du client en cas de brèche de sécurité).

En cas de perte, révocation ou expiration du refresh_token, l'administrateur sécurité DEVRA générer un nouveau refresh_token.

Le body de la requête doit être encodé en x-www-form-urlencoded et inclure les champs grant_type avec la valeur refresh_token ainsi que refresh_token contenant la clé API

Fonctions de l'API​

Description​

L'utilisateur peut :

  • Administrer les sociétés

  • Administrer les utilisateurs

  • Administrer les clients

  • Administrer les événements

  • Administrer les référentiels

Modèles communs​

Adresse postale​

| Champ | Description  | Type  | | recipient  | Libellé du destinataire  | string  | | streetAddress | Rue et compléments d'adresse | string | | floor | Etage | string  | | zipCode | Code postal | string  | | city | Ville | string  | | country | Pays | Objet | | | | Pays |

streetAddress est un champ sur plusieurs lignes (au maximum sur 4 lignes). Chaque ligne est séparée par « \r\n ».

Pays​

Champ Description  Type 

id Identifiant du pays. int 

label Nom du pays (Ex : France) string

code Code iso 2 du pays (Ex : Fr) string ​

Si l'id n'est pas renseigné, on cherche le pays avec le code iso sinon avec le label.

Informations de contact​

Champ Description  Type 

postalAddress Adresse postale (cf §4.2.1) object

mail1 Adresse mail principale string 

mail2 Adresse mail secondaire string 

phone1 Numéro de téléphone fixe string 

phone2 Numéro de téléphone mobile string 

phone3 Numéro de téléphone fixe 2 string 

phone4 Numéro de téléphone mobile 2 string 

fax1 Numéro de fax string 

fax2 Numéro de fax string 

url URL du site internet string 

notes string ​

Evénement​

Champ Description  Type 

Id Identifiant de l'événément String

Subject Sujet string 

Deal Affaire associée object  | null

Deal.Id Identifiant de l'affaire string 

Deal.Label Libellé de l'affaire string 

DateDebut Date de début de l'événément Date

DateFin Date de fin de l'événement Date | null

User Utilisateur qui a créé Object l'événement

User.id Identifiant de l'utilisateur string 

User.lastName Nom de l'utilisateur string 

User.firstName Prénom de l'utilisateur string 

Client Client associé object

Client.Id Identifiant du client

Client.Name Nom du client

Client.FirstName Prénom du client

Mean Moyen d'événement object

Type Type d'événement Object

State Etat d'événement object

IsAllDay Indique si la date de début et bool de fin s'applique sur une journée entière

DateCreation Date de création de l'événement Date

Origine Origine de l'événement String

Notes Notes/Mémo sur l'événement String

Revision Identifiant unique ordonné Int​

Moyen d'événement​

Champ Description  Type 

Id  Identifiant Int

Code Identifiant texte String

Label Libellé dans la langue de Bool l'utilisateur courant

IsSystem Indique si le moyen est défini Bool pour le système (true) ou spécifique au client (false)​

Type d'événement​

Champ Description  Type 

Id  Identifiant Int

Code Identifiant texte String

Label Libellé dans la langue de Bool l'utilisateur courant

IsSystem Indique si le moyen est défini Bool pour le système (true) ou spécifique au client (false)

Target Indique s'il s'applique à un int client (1) ou à une affaire (2)​

Etat d'événement​

Champ Description  Type 

Id  Identifiant Int

Code Identifiant texte String

Label Libellé dans la langue de Bool l'utilisateur courant

IsSystem Indique si le moyen est défini Bool pour le système (true) ou spécifique au client (false)

IsComplete Indique si l'état est un état bool indiquant une fin de traitement (true) ou pas (false)​

Recherche paginée​

Requête​

Champ Description  Type 

offset  Index  int (>=0)

pageSize Nombre maximum d'éléments à int (> 0) renvoyer​

Chaque requête doit définir :

  • Une taille de page par défaut et une taille de page maximum.

  • Les critères de recherche

Réponse​

Champ Description  Type 

total Nombre total d'éléments résultat Int (>= 0)  de la recherche

items Eléments recherchés dans la object[] plage demandée​

Type d'origine​

code valeur  Description

Internet 1

Parrainage 2 Notes contient le parrain

FoireSalon 3 Notes contient le nom du salon/foire

CommunicationLocale 4

PagesJaunes 5

PubliciteNationale 6

Prescription 7

ImportPermisConstruire 8

ImportFichierTiers 9

Presse 10

Flyer 11

Voiture 12

ReseauxSociaux 13

Magasin 14

ContactTelephonique 15

Panneau 16

Affichage 18

Radio 19

AncienClient 20

Television 21

ReseauPersonnel 22

Autre 999​

Type civilité​

code valeur 

Madame 1

Monsieur 2

MonsieurMadame 3

Mesdames 4

Messieurs 5

EntrepriseAutre 6

Docteur 7

MonsieurMessieurs 8​

External identifier​

Champ Description  Type 

provider Clés string

externalID Valeur string​

Administrer des utilisateurs​

Description​

L'utilisateur autorisé peut :

  • Lister les utilisateurs

  • Créer un utilisateur

  • Modifier un utilisateur existant

  • Lire les informations d'un utilisateur existant

  • Désactiver un utilisateur existant

Autorisations​

Nécessite les rôles User ou UserRead

Modèle Utilisateur​

Modèle résumé​

| Champ | Description  | Type  | | id  | Identifiant unique de | string  | | | l'utilisateur | | | | (read only) | | | firstName | Rue et compléments d'adresse | string | | lastName | Etage | string  | | creationTime | Code postal | string  | | updateTime | Ville | string  | | company | Informations de la société | object | | | associée à l'utilisateur | | | company.id | Identifiant de la société | string |

Modèle complet​

| Champ | Description  | Type  | | initials  | Initiales de l'utilisateur | string  | | login | Identifiant de connexion de | string | | | l'utilisateur | | | contact | Adresse mail | string  | | culture | Code culture | string | | enabled | Indique si l'utilisateur est | boolean | | | actif | | | | (read only) | | | notes | | string | | externalId | Identifiant de l'utilisateur | string | | | dans le système externe du | | | | client | | | company.name | Nom de la société | string |

Lister les utilisateurs​

POST /users

Autorisation​

Nécessite le rôle User ou UserRead

Description​

TODO

Données en entrée​

Modèle de requête de recherche paginée

| Champ | Description  | Type  | | pageSize  | Par défaut : 100, | int  | | | Max : 500 | | | filter.company | La recherche s'effectue sur | string | | | les utilisateurs appartenant | | | | à la société spécifiée par | | | | son identifiant | | | filter.enabledOnly | Indique si la recherche ne | boolean  | | | renvoie que les utilisateurs | | | | actifs | |

Données en sortie​

Modèle de réponse de recherche paginée. Les items sont de type « Modèle utilisateur complet »

Champ Description  Type 

total Nombre total d'éléments résultat Int (>= 0)  de la recherche

items Eléments recherchés dans la object[] plage demandée​

Les informations retournées pour chaque utilisateur sont les suivantes :

| Champ | Description  | Type  | | id  | Identifiant unique de | string  | | | l'utilisateur | | | | (read only) | | | firstName | Prénom | string | | lastName | Nom | string  | | login | Identifiant de connexion | string | | enabled | Indique si le compte est | boolean | | | activé | | | creationTime | Date de création | string  | | updateTime | Date de dernière modification | string  | | company | Informations de la société | object | | | associée à l'utilisateur | | | > company.id | Identifiant de la société | string |

Créer un utilisateur​

POST /user

Autorisation​

Nécessite le rôle User

Description​

TODO

Données en entrée​

| Champ | Description  | Type  | | firstName | Prénom | string | | lastName | Nom | string  | | login | Identifiant de connexion | string | | company | Informations de la société | object | | | associée à l'utilisateur | | | > company.id | Identifiant de la société | string | | initials  | Initiales de l'utilisateur | string  | | culture | Code culture | string | | notes | | string | | contact | Informations de contact de | object | | | l'utilisateur (cf §3.2) | |

Données en sortie​

Modèle utilisateur avec les champs suivants :

  • id

  • creationTime

  • updateTime

  • company.id, company.name

Modifier un utilisateur​

PUT /user/{userId}

Autorisation​

Nécessite le rôle User

Description​

TODO

Données en entrée​

| Champ | Description  | Type  | | id  | Identifiant unique de | string  | | | l'utilisateur | | | | (read only) | | | firstName | Prénom | string | | lastName | Nom | string  | | initials  | Initiales de l'utilisateur | string  | | culture | Code culture | string | | notes | | string | | contact | Informations de contact de | object | | | l'utilisateur (cf §3.2) | |

Les informations de l'utilisateur pouvant être modifiées sont celles ci-dessus (sauf id).

Données en sortie​

Les informations détaillées de l'utilisateur

Lire les informations d'un utilisateur​

GET /user/{userId}

Autorisation​

Nécessite le rôle User ou UserRead

Description​

Obtient les informations de l'utilisateur spécifié par son identifiant unique.

Données en entrée​

Requête URI : {userId} = identifiant de l'utilisateur

Données en sortie​

| Champ | Description  | Type  | | id  | Identifiant unique de | string  | | | l'utilisateur | | | | (read only) | | | firstName | Prénom | string | | lastName | Nom | string  | | login | Identifiant de connexion | string | | enabled | Indique si le compte est | boolean | | | activé | | | creationTime | Date de création | string  | | updateTime | Date de dernière modification | string  | | company | Informations de la société | object | | | associée à l'utilisateur | | | > company.id | Identifiant de la société | string | | > company.name | Nom de la société | string | | initials  | Initiales de l'utilisateur | string  | | culture | Code culture | string | | notes | | string | | contact | Informations de contact de | object | | | l'utilisateur (cf §4.2.2) | |

Désactiver un utilisateur​

DELETE /user/{userId}

Autorisation​

Nécessite le rôle User.

Description​

Désactive un utilisateur.

Données en entrée​

Requête URI : {userId} = identifiant de l'utilisateur

Données en sortie​

Appliquer un profile de droits à un utilisateur​

POST /user/{userId}/permissions

Autorisation​

Nécessite le rôle User.

Données en entrée​

Requête URI : {userId} = identifiant de l'utilisateur (champ id de l'utilisateur)

Body au format JSON

Champ Description  Type 

profile Libellé du profile string

Les profiles sont configurés au niveau de l'application.

Données en sortie​

N/A

Administrer des societes​

Description​

L'utilisateur peut :

  • Lister les sociétés

  • Lire les informations d'une société

Autorisations​

Nécessite les droits Company (accès en lecture/écriture) ou CompanyRead (accès en lecture seule).

Lister les sociétés​

GET /companies

Description​

Renvoie la liste des sociétés appartenant au réseau associé au compte courant.

Données en entrée​

N/A

Données en sortie​

La réponse est un objet au format JSON.

Champ Description  Type 

total  Nombre de sociétés int 

items La liste des sociétés object []​

Les informations suivantes sont renvoyées pour chaque société (élément de items) :

| Champ | Description  | Type  | | id  | Identifiant unique la société | string  | | | (read only) | | | name | Nom de la société | string | | externalIdentifiers | Liste des identifiants et de | object | | | leur source/fournisseur | |

Le format de externalIdentifiers est le suivant :

{

Provider1 : identifiant1,

Provider2 : identifiant2

}

Lire les informations d'une société​

GET /company/{companyId}

Description​

Renvoie les informations détaillées d'une société.

Données en entrée​

Requête URI : {companyId} = identifiant de la société dont on veut le détail

Données en sortie​

La réponse est un objet au format JSON.

| Champ | Description  | Type  | | id  | Identifiant unique la société | string  | | | (read only) | | | name | Nom de la société | string | | mail | Adresse mail de la société | string | | phone | Numéro de téléphone de la | string | | | société | | | fax | Numéro de fax de la société | string | | externalIdentifiers | Liste des identifiants et de | object | | | leur source | |

Rechercher une société par son identifiant externe​

POST /companies

Données en entrée​

Champ Description  Type 

provider Code du fournisseur de string  l'identifiant externe

id Identifiant recherché string

actifOnly Lister les sociétés non Bool | supprimées et non de formation false

asActifUser Lister les sociétés ayant Bool | uniquement des utilisateurs false actifs

asAdminRights Lister les sociétés ayant des Bool | utilisateurs possédant le droit false admin société​

Données en sortie​

Champ Description  Type 

total  Nombre de sociétés int 

items La liste des sociétés Object[]​

Les informations suivantes sont renvoyées pour chaque société (élément de items) :

| Champ | Description  | Type  | | id  | Identifiant unique la société | string  | | | (read only) | | | name | Nom de la société | string |

Administrer des clients​

Description​

L'utilisateur peut :

  • Rechercher les clients

  • Créer un client

  • Modifier un client

  • Obtenir les informations d'un client

Modèles​

Client​

Champ Description  Type 

id Identifiant du client string

notes Memo sur le client

creationTime Date de création

updateTime Date de dernière modification

CiviliteId Identifiant du type de civilité Nullable Int

FirstName Prénom du client

Name Nom du client

companyId Identifiant de la société rattachée au client

origin Identifiant de l'origine du int client

Abandon Objet de type Information Object d'abandon

contact Objet de type Informations de Object contact

externalId Identifiant du client dans la string source externe

externalProvider Identifiant de la source externe string

userId Identifiant du compte string utilisateur responsable du client​

Informations d'abandon​

Champ Description  Type 

id Identifiant du type d'abandon string

Code Code du motif d'abandon String

label Libellé du motif d'abandon String

Reason Information complémentaire au string motif

value Date complémentaire Date | null

when Date d'abandon date​

Rechercher les clients​

POST /clients

Description​

L'utilisateur peut rechercher les clients selon :

  • La société ou l'utilisateur rattaché

  • La date de création (dans une période)

  • La date de mise à jour (dans une période)

Si plusieurs critères sont utilisés, on effectue une recherche qui respecte tous les critères (AND).

Autorisations​

Nécessite le droit Deal ou DealRead.

Données en entrée​

Format du body​

Champ Description  Type 

Offset

PageSize Nombre d'éléments maximums à retourner

Since

Creationtime Permet de filtrer sur la date de création

CreationTime.From Borne min Date | null

CreationTime.Until Borne max Date | null

UpdateTime Permet de filtrer sur la date de dernière mise à jour

UpdateTime.From Borne min Date | null

UpdateTime.Until Borne max Date | null

User Permet de filtrer selon l'utilisateur responsable

User.ExcludeInactive Exclure les clients associés aux bool utilisateurs inactifs

User.TypeExternId Filtrer sur le type extern id de Int | l'utilisateur responsable null

Company Permet de filtrer selon la société associée

Company.ExcludeDeleted Exclure les clients associés à une société désactivée

Company.EstDemo Exclure les sociétés de Bool | démonstration null

ClieNHSource Filtrer sur le fournisseur externe du client​

Format de la query​

La requête http accepte le paramètre fullFormat (bool, par défaut false) qui permet de renvoyer les informations complètes (fullFormat =true) ou partielles (fullFormat = false)

Données en sortie​

Créer un client​

POST /client

Description​

Autorisations​

Nécessite l'autorisation Deal

Données en entrée​

Objet client. Les données suivantes ne sont pas modifiables :

  • Id

  • Revision

  • companyId

  • Abandon

  • CreationTime

  • UpdateTime

Données en sortie​

Créer un contact pour le premier utilisateur admin de la société​

POST / client/addClientToFirstAdministrator

Description​

Cette api permet de créer un nouveau contact en l'associant automatiquement au premier utilisateur admin de la société passée dans le body

Autorisations​

Données en entrée​

Objet client. Les données suivantes sont obligatoires :

  • firstName

  • Name

  • companyId

Données en sortie​

Objet client enrichi :

  • Id (id du nouveau client)

  • userId (id de l'utilisateur associé au contact)

  • date de création

Modifier un client​

PUT /client

Description​

Autorisations​

Nécessite l'autorisation Deal

Données en entrée​

Les propriétés suivantes sont modifiables :

Champ Description 

notes Memo sur le client

CiviliteId Identifiant du type de civilité

FirstName Prénom du client

Name Nom du client

ExternalId Identifiant du client dans la source externe

contact Objet de type Informations de contact​

Obtenir les informations d'un client​

GET /client/{clientId}

Description​

Autorisations​

Nécessite l'autorisation Deal ou DealRead

Données en entrée​

Requête URI : {clientId} = identifiant du client dont on veut le détail

Données en sortie​

Objet de type client

Rechercher un client à partir d'un identifiant externe​

GET /client/lookup/{externid}

Description​

Autorisations​

Nécessite l'autorisation Deal ou DealRead

Données en entrée​

Requête URI : {externId} = identifiant du client dans la source externe

Données en sortie​

Obtenir la liste des clients d'un utilisateur​

GET /user/{userid}/clients

Description​

Renvoie la liste des clients dont l'utilisateur spécifié est responsable.

Autorisations​

Nécessite l'autorisation Deal ou DealRead

Données en entrée​

Requête URI : {client} = identifiant du compte utilisateur pour lequel on veut extraire les clients

Données en sortie​

Champ Description  Type 

total Nombre de clients int

Items Liste des clients Object[]

Items[].id Identifiant du client String

Items[].Name Nom du client String

Items[].FirstName Prénom du client string​

Obtenir la liste des clients d'une société​

GET /company/{companyId}/clients

Description​

Renvoie la liste des clients associés à la société spécifiée.

Autorisations​

Nécessite l'autorisation Deal ou DealRead

Données en entrée​

Requête URI : {companyId} = identifiant de la société pour laquelle on veut extraire les clients

Données en sortie​

Obtenir la liste des événements d'un client​

GET /client/{clientid}/events

Description​

Renvoie la liste des événements associés à un client dont les événements associés à ses affaires.

Autorisations​

Nécessite l'autorisation Deal ou DealRead

Données en entrée​

Requête URI : {clientId} = identifiant du client dont on veut obtenir la liste des événements.

Données en sortie​

Liste d'objet de type Evénement.

Champ Description  Type 

total Nombre d'événements int

Items Liste des événements Object[]​

Import clients​

POST/client/batch/externalIdentifier

Description​

Autorisations​

Données en entrée​

Cette api prend en body une liste d'objet suivant :

| Champ | Description  | Type  | | name | Nom du client | string | | firstName | Prénom du client | string | | notes | Memo sur le client | string | | civiliteId | Identifiant du type de | Nullable Int | | | civilité | | | | | Voir Enum Type | | | | civilité | | type | Type du contact (particulier | Int | | | / entreprise) | | | | | 1 : particulier | | | Si le type = 2 pas besoin de | | | | renseigner la civilité | 2 : entreprise | | origine | Identifiant de l'origine du | Int | | | client | | | | | Voir | | | | Enum Type | | | | d'origine | | company | La société rattachée au | List<External | | | client | identifier> | | establishment | L'établissement rattaché au | List<External | | | client | identifier> | | user | L'utilisateur rattaché au | List<External | | | client | identifier> | | externalIdentifiers | Liste des identifiants et de | List<External | | | leur source | identifier> | | contact | Objet de type Informations | Object | | | de contact | | | | | Informations de | | | | contact |

Exemple json :

[

{

"name": "string",

"firstName": "string",

"notes": "string",

"civiliteId": 0,

"origine": 0,

"type": 0,

"company": [

{

"provider": "string",

"externalID": "string"

}

],

"establishment": [

{

"provider": "string",

"externalID": "string"

}

],

"user": [

{

"provider": "string",

"externalID": "string"

}

],

"externalIdentifiers": [

{

"provider": "string",

"externalID": "string"

}

],

"contact": {

"postalAddress": {

"streetAddress": "string",

"floor": "string",

"zipCode": "string",

"city": "string",

"country": {

"id": 0,

"label": "string",

"code": "string"

}

},

"mail1": "string",

"mail2": "string",

"phone1": "string",

"phone2": "string",

"phone3": "string",

"phone4": "string",

"fax1": "string",

"fax2": "string",

"url": "string",

"notes": "string"

}

}

]

Données en sortie​

L'api retourne uniquement les lignes non traitées (même format que l'entrée)

Administrer des affaires​

Description​

L'utilisateur peut :

  • Rechercher les affaires

  • Créer une affaire

  • Obtenir les informations d'une affaire

Modèles​

Information d'abandon​

Champ Description  Type 

id Identifiant du type d'abandon string

Code Code du motif d'abandon String

label Libellé du motif d'abandon String

Reason Information complémentaire au string motif

value Date complémentaire Date | null

when Date d'abandon date​

Affaire​

Champ Description  Type 

id Identifiant de l'affaire string

Label Contremarque de l'affaire String

state Etape de l'affaire (Découverte, string Devis, Vente, Facture, Facture directe)

Client Référence du client

Client.id Identifiant du client string

Client.Name Nom du client String

Client.FirstName Prénom du client String

User Référence de l'utilisateur responsable de l'affaire

User.id Identifiant du compte String utilisateur

User.firstName Prénom de l'utilisateur String

User.lastName Nom de l'utilisateur string

Abandon Information de l'abandon object

ExternalId Identifiant de l'affaire dans la String source externe

Notes Notes/mémo de l'affaire String

Revision Identifiant séquentiel Int

TypeProjetId Type du projet Int

SellingHT Prix de vente HT Decimal

SellingTTC Prix de vente TTC Decimal

CreationDate Date de création Date

LastUpdateDate Date de dernière modification Date

Currency Code devise (EUR, USD,...) String

Contact Informations de contact Object

Decouverte Informations de découverte object​

D'autre information peut être récupérées en plus, si le query param fullFormat = true

Champ Description  Type 

Status Le statut de l'affaire object

DateQuote Date devis Date

QuoteNumber Numéro de devis string

DateSale Date de passage en vente Date

SaleNumber Numéro de commande String

DateInvoice Date de passage en facture Date

InvoiceNumber Numéro de facture String

comany.id Identifiant de la société de String l'affaire

comany.name Nom de la société string

typeProject.id Type de projet de l'affaire enum

typeProject.label Nom du projet String​

Informations de découverte​

Champ Description  Type 

BudgetType Type de budget Int | null

DelayType Type de délai de réalisation Int | null

HomeStatusType Propriétaire ou locataire Int | null

HouseOwnerAuthorized Travaux autorisés par le Bool | propriétaire si locataire null

HomeType Type de résidence (Appartment ou string House)

HasPose Pose à réaliser Bool | null

HasTtravaux Travaux à réaliser Bool | null

ClientDoTravaux Le client effectue les travaux Bool | null

RealisationDate Date de réalisation Date | null

Origine Type d'origine de l'affaire Int | null

OrigineNotes Informations d'origine string

IsHomeOlderThan2Years Le logement a plus de 2 ans Bool | null

CreationDate Date de création Date

LastUpdateDate Date de dernière mise à jour Date​

Rechercher les affaires​

POST /deals

Description​

L'utilisateur peut rechercher les affaires selon :

  • La société ou l'utilisateur rattaché

  • La date de création (dans une période)

  • La date de mise à jour (dans une période)

Si plusieurs critères sont utilisés, on effectue une recherche qui respecte tous les critères (AND).

Autorisations​

Nécessite l'autorisation Deal ou DealRead

Données en entrée​

Format du body​

Champ Description  Type 

Offset

PageSize Nombre d'éléments maximums à retourner

Since

Creationtime Permet de filtrer sur la date de création

CreationTime.From Borne min Date | null

CreationTime.Until Borne max Date | null

UpdateTime Permet de filtrer sur la date de dernière mise à jour

UpdateTime.From Borne min Date | null

UpdateTime.Until Borne max Date | null

User Permet de filtrer selon l'utilisateur responsable

User.ExcludeInactive Exclure les clients associés aux bool utilisateurs inactifs

User.TypeExternId Filtrer sur le type extern id de Int | l'utilisateur responsable null

Company Permet de filtrer selon la société associée

Company.ExcludeDeleted Exclure les clients associés à une société désactivée​

Paramètres​

La requête http accepte le paramètre fullFormat (bool, par défaut false) qui permet de renvoyer les informations complètes (fullFormat =true) ou partielles (fullFormat = false)

Données en sortie​

Créer une affaire​

POST /deal

Description​

Crée une affaire à l'étape Découverte si une découverte est fournie, sinon l'affaire est créée à l'étape Devis.

Autorisations​

Nécessite le droit Deal.

Données en entrée​

Un objet de type affaire.

Données en sortie​

Le deal avec les informations autogénérées (date, id).

Obtenir les informations d'une affaire​

GET /deal/{dealId}

Description​

Autorisations​

Nécessite l'autorisation Deal ou DealRead

Données en entrée​

Requête URI : {dealId} = identifiant de l'affaire

Données en sortie​

Objet de type affaire.

Rechercher une affaire à partir d'un identifiant externe​

GET /deal/lookup/{externid}

Description​

Autorisations​

Nécessite le droit Deal ou DealRead.

Données en entrée​

Requête URI : {externid} = identifiant de l'affaire dans la source externe.

Données en sortie​

Objet de type Affaire.

Obtenir la liste des affaires d'un utilisateur​

GET /user/{userid}/deals

Description​

Autorisations​

Nécessite le droit Deal ou DealRead.

Données en entrée​

Requête URI : {userId} = identifiant de l'utilisateur responsable des affaires

Données en sortie​

Obtenir la liste des affaires d'un client​

GET /client/{clientId}/deals ?fullFormat=true

Description​

Renvoie la liste des affaires d'un client

Autorisations​

Nécessite le droit Deal ou DealRead.

Données en entrée​

| Requête URI | Description  | Type  | | {clientId} | Identifiant du client dont on veut obtenir | string | | | les affaires | | | fullFormat | Le paramètre qui détermine les infos qu'on | Bool | | | veut en sortie (facultatif) | || | | | | false | | | Si true : sortie objet Affaire | |

Données en sortie​

Champ Description  Type 

total Nombre d'affaires int

Items Liste des affaires Affaire[]​

Obtenir la liste des événements d'une affaire​

GET /deal/{dealid}/events

Description​

Renvoie la liste des événements associés à une affaire.

Autorisations​

Nécessite le droit Deal ou DealRead.

Données en entrée​

Requête URI : {dealId} = identifiant de l'affaire dont on veut obtenir les événements.

Données en sortie​

Liste d'objets de type Evénement.

Champ Description  Type 

total Nombre d'événements int

Items Liste des événements Object[]​

Administrer les évenements​

Description​

L'utilisateur peut :

  • Créer un événement pour un client

  • Lister les événements

Autorisations​

Nécessite les droits Deal ou DealRead

Lister les événements​

POST /events

Description​

Autorisations​

Nécessite les droits Deal ou DealRead

Données en entrée​

Champ Description  Type 

offset Offset de début de pagination int

PageSize Nombre d'événements à renvoyer int

Since Int | null​

Données en sortie​

Champ Description  Type 

total Nombre total d'événement de la int recherche

items Liste des événements Object[]​

Ajouter un événement​

POST /event

Description​

Autorisations​

Nécessite le droit Deal

Données en entrée​

Objet de type événement.

Données en sortie​

Administrer les référentiels​

Description​

L'utilisateur peut :

  • Obtenir la liste des types d'événement

  • Obtenir la liste des moyens d'événement

  • Obtenir la liste des états d'événement

Autorisations​

Tout compte authentifié a accès aux informations de référentiel.

Obtenir la liste des types d'événement​

GET /company/events/types

Description​

Renvoie la liste des types d'événement disponibles pour le réseau associé au compte courant

Données en sortie​

Champ Description  Type 

total  Nombre d'éléments dans la liste int 

items La liste des types d'événements Object[]​

Obtenir la liste des moyens d'événement​

GET /company/events/means

Description​

Renvoie la liste des moyens d'événement disponibles pour le réseau associé au compte courant

Données en sortie​

Champ Description  Type 

total  Nombre d'éléments dans la liste int 

items La liste des origines Object[]​

Obtenir la liste des états d'événement​

GET /company/events/states

Description​

Renvoie la liste des états d'événements disponibles pour le réseau associé au compte courant.

Données en sortie​

Champ Description  Type 

total  Nombre d'éléments dans la liste int 

items La liste des états d'événement Object[]​