Logo Harvest
redocly logo API docs by Redocly

Harvest API - Contacts O2S (0.9.3)

Download OpenAPI specification:Download

API de gestion des contacts O2S

Cette API offre différents services permettant de gérer des contacts O2S ainsi que les informations liées.

Pour ce faire, plusieurs ressources sont à disposition, à savoir :

  • Contact : Permet de gérer l'entité de base de cette API que sont les contacts.
  • Relation : Permet de gérer les relations des contacts.

Règlement Général sur la Protection des Données (RGPD)

Dans le cadre de la mise à disposition de l’API, HARVEST s’engage à effectuer pour le compte du Client responsable de traitement, les opérations de traitement de données à caractère personnel en qualité de sous-traitant. A ce titre, HARVEST et le Client s’engagent à respecter la réglementation en vigueur applicable au traitement de données à caractère personnel en particulier, le règlement (UE) 2016/679 du Parlement européen et du Conseil du 27 avril 2016 (ci-après le « RGPD »).

L’API peut vous permettre de renseigner librement des propriétés typées et non typées. HARVEST attire votre attention sur la nécessité, lors de la complétude de ces propriétés, de respecter les dispositions du RGPD. Dès lors, seules les données adéquates, pertinentes et strictement nécessaires au regard de la finalité des traitements réalisés par l’API doivent être transmises.

L’API contient par ailleurs des zones de commentaires libres dans lesquelles vous devez impérativement rédiger des commentaires objectifs, jamais excessifs ou insultants. Aussi, vous devez exclure toute donnée considérée comme sensible (origine raciale ou ethnique, opinions politiques, philosophiques ou religieuses, appartenance syndicale, données relatives à la santé ou à la vie sexuelle, infractions, condamnations, mesure de sûreté). En cas de doute, vous pouvez contacter votre DPO qui vous indiquera ce qu’il est possible de rédiger pour ne pas porter atteinte aux droits des personnes concernées.

Sécurité

Généralité

Pour utiliser l'API O2S, vous devez préalablement vous authentifier en suivant le protocole OAuth2 "password grant type" afin de récupérer un jeton (JWT) d'accès.

Informations nécessaires

Les informations nécessaires à l'obtention d'un jeton sont constituées :

  • d'informations fournies par Harvest qui sont spécifiques à votre application (client_id + client_secret)
  • d'informations spécifiques à un utilisateur O2S (username + password) dont l'API reprendra l'identité.

Il vous faut renseigner ces informations dans la ressource en entrée du service d'obtention d'un nouveau jeton.

Utilisation du jeton d'accès

Le jeton JWT doit être fourni lors de l'appel de chaque requête à l'API. Il doit être ajouté dans l'entête HTTP Authorization comme ceci : Authorization: Bearer <JWT>

OAuthPasswordAuthenticate

Le jeton JWT d'accès à exploiter est retourné dans valeur de la propriété access_token.

Il doit être précisé dans l'entête HTTP de toutes les requêtes (sauf celle d'authentification) comme ceci :

Authorization: Bearer <access_token>

Authorizations:
JWT
Request Body schema: application/x-www-form-urlencoded
grant_type
required
string
Value: "password"

Méthode d'authentification OAuth à définir obligatoirement à password.

client_id
required
string

Identifiant de l'application cliente.

client_secret
required
string

Secret de l'application cliente.

username
required
string

Identifiant de connexion de l'utilisateur.

password
required
string

Mot de passe de l'utilisateur.

Responses

Request samples

Content type
application/x-www-form-urlencoded
grant_type=password&client_id=clientId&client_secret=clientSecret&username=username&password=password

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOi...fgWOZZmV7Q",
  • "expires_in": 86400,
  • "refresh_expires_in": 86400,
  • "refresh_token": "eyJhbGciOi...KiIVIifWw",
  • "token_type": "bearer",
  • "not-before-policy": 1602682985,
  • "session_state": "85d20350-891b-4dad-b6ed-c411c6ac870c",
  • "scope": "..."
}

Réponse en cas de problème

Les réponses principales de l'API sont décrites au niveau de chacune de ses ressources (GET, POST, PUT, DELETE...).

Celles qui n'y sont pas spécifiées sont celles retournées en cas de problème soit avec la requête elle-même soit avec le serveur ou son environnement.

Les statuts HTTP concernés par ces dernières sont les 4xx (hors 404) et 5xx.

Le format des réponses répond au schéma Problem Zalando.

Contact

Opérations sur les contact O2S

Lister des Contacts

Récupère une liste de Contact correspondant aux critères facultatifs de recherche.
Par défaut :

  • aucun filtre n'est appliqué (permet de récupérer tous les contacts)
  • le nombre d'éléments retournés est limité à 20
Authorizations:
JWT
query Parameters
refext
string^.+:.*$
Example: refext=SI:12345

Référence externe du contact recherché (de la forme référentiel:identifiant)

limit
integer
Default: 20

Nombre maximum de contacts à retourner

offset
integer
Default: 0

Indice (0-based) du premier contact à retourner

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Créer un Contact

Crée un nouvel Contact.

Authorizations:
JWT
Request Body schema: application/json

Les données d'un Contact à créer.

object (TypeReferencesExternes)

Collection d'identifiants de la ressource dans plusieurs référentiels. Chaque référence externe est constituée :

  • d'une clé correspondant à un identifiant global du référentiel externe
  • d'une valeur associée correspondant à la valeur de l'identifiant de la ressource dans le référentiel externe concerné
object (InformationsCommerciales)

Extension InformationsCommerciales d'une Etude.

object (Confidentialite)

Extension Confidentialite d'une Etude.

object (SuiviRelationClient)

Extension SuiviRelationClient d'une Personne.

object (MetaDonnees)

Extension MetaDonnees d'une Document.

object (Personne)
Array of objects (PersonneLiee)
organisationId
string

Référence (id) de l'organisation à laquelle est rattachée le contact.

Array of objects (Adresses)
Array of objects (TypeFlux)
Array of objects (Stock)
object (EtudeIndicateurs)

Extension Indicateurs d'une Etude.

Array of objects (Dispositions)
libelle
string (TypeLibelle) [ 1 .. 200 ] characters

Le libellé de l'entité.

Responses

Request samples

Content type
application/json
Example
{
  • "refExternes": {
    },
  • "informationsCommerciales": {
    },
  • "confidentialite": {
    },
  • "suiviRelationClient": {
    },
  • "personne": {
    },
  • "personnesLiees": [
    ],
  • "adresses": [
    ],
  • "fluxs": [
    ],
  • "stocks": [
    ],
  • "indicateurs": {
    },
  • "dispositions": [
    ],
  • "id": "a339e8d3-15fd-11ec-9434-0050568ae49b"
}

Response samples

Content type
application/json
{
  • "id": "f2d4a982-c1f6-11eb-ba91-0050568a56f0"
}

Obtenir un Contact

Récupère les données d'un unique Contact.

Authorizations:
JWT
path Parameters
contactId
required
string (TypeId) [ 1 .. 100 ] characters

Référence (id) du contact

Responses

Response samples

Content type
application/json
Example
{
  • "refExternes": {
    },
  • "informationsCommerciales": {
    },
  • "confidentialite": {
    },
  • "suiviRelationClient": {
    },
  • "personne": {
    },
  • "personnesLiees": [
    ],
  • "adresses": [
    ],
  • "fluxs": [
    ],
  • "stocks": [
    ],
  • "indicateurs": {
    },
  • "dispositions": [
    ],
  • "id": "a339e8d3-15fd-11ec-9434-0050568ae49b"
}

Mettre à jour un Contact

Met à jour un Contact existant.

Authorizations:
JWT
path Parameters
contactId
required
string (TypeId) [ 1 .. 100 ] characters

Référence (id) du contact

Request Body schema: application/json

Les données d'un Contact à mettre à jour.

object (TypeReferencesExternes)

Collection d'identifiants de la ressource dans plusieurs référentiels. Chaque référence externe est constituée :

  • d'une clé correspondant à un identifiant global du référentiel externe
  • d'une valeur associée correspondant à la valeur de l'identifiant de la ressource dans le référentiel externe concerné
object (InformationsCommerciales)

Extension InformationsCommerciales d'une Etude.

object (Confidentialite)

Extension Confidentialite d'une Etude.

object (SuiviRelationClient)

Extension SuiviRelationClient d'une Personne.

object (MetaDonnees)

Extension MetaDonnees d'une Document.

object (Personne)
Array of objects (PersonneLiee)
organisationId
string

Référence (id) de l'organisation à laquelle est rattachée le contact.

Array of objects (Adresses)
Array of objects (TypeFlux)
Array of objects (Stock)
object (EtudeIndicateurs)

Extension Indicateurs d'une Etude.

Array of objects (Dispositions)
libelle
string (TypeLibelle) [ 1 .. 200 ] characters

Le libellé de l'entité.

Responses

Request samples

Content type
application/json
Example
{
  • "refExternes": {
    },
  • "informationsCommerciales": {
    },
  • "confidentialite": {
    },
  • "suiviRelationClient": {
    },
  • "personne": {
    },
  • "personnesLiees": [
    ],
  • "adresses": [
    ],
  • "fluxs": [
    ],
  • "stocks": [
    ],
  • "indicateurs": {
    },
  • "dispositions": [
    ],
  • "id": "a339e8d3-15fd-11ec-9434-0050568ae49b"
}

Supprimer un Contact

Supprime un Contact existant.

Authorizations:
JWT
path Parameters
contactId
required
string (TypeId) [ 1 .. 100 ] characters

Référence (id) du contact

Responses

Relation

Opérations sur les relations O2S

Lister des Relations

Récupère une liste de Relation correspondant aux critères facultatifs de recherche.
Par défaut :

  • aucun filtre n'est appliqué (permet de récupérer toutes les relations)
  • le nombre d'éléments retournés est limité à 20
Authorizations:
JWT
query Parameters
personneId
string (TypeId) [ 1 .. 100 ] characters

Référence (id) d'un contact. La recherche retournera les relations de ce contact.

limit
integer
Default: 20

Nombre maximum de relations à retourner. Mettre -1 pour renvoyer la totalité des relations (no limit).

offset
integer
Default: 0

Indice (0-based) de la première relation à retourner

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Créer une relation

Crée une nouvelle Relation.

Authorizations:
JWT
Request Body schema: application/json

Les données d'une Relation à créer.

libelle
string (TypeLibelle) [ 1 .. 200 ] characters

Le libellé de l'entité.

type
string (TypeRelationTypeCode)
Enum: "FAMILLE" "EMPLOYEUR" "COUPLE" "NOTAIRE" "TP" "EXPERT_COMPTABLE" "PERSONNE_MORALE" "AFFAIRES" "MESURE_JUDICIAIRE" "REPRESENTANT_LEGAL" "DIRECTION" "GERANCE" "DROIT_PROPRIETE" "GARANTIE" "PORTEUR_CARTE" "DELEGATION" "CONTROLE" "PROCURATION" "ADMINISTRATION" "CONFORMITE" "ENTREPRENEUR_INDIVIDUEL" "INTERLOCUTEUR_SANS_MANDAT" "AUTRE_RELATION_PM" "LIBRE"

Type de relation entre deux personnes :

  • COUPLE : Relation de couple (époux, concubin, partenaire)
  • FAMILLE : Relation de famille (enfant, frère, sœur, collatéral)
  • TP : Toute relation avec une personne ne faisant pas partie du cercle familial. A utiliser par exemple pour désigner les personnes bénéficiaires d'un contrat que l'on voudrait faire apparaître dans le calcul successoral.
  • AFFAIRES : Relations d'affaires ou commerciales entre deux personnes.
  • MESURE_JUDICIAIRE : Relation entre deux personnes suite à une mesure judicaire (tutelle, curatelle,...).
  • REPRESENTANT_LEGAL : Relation entre deux personnes dont l'une est désignée pour représenter l'autre.
  • DIRECTION : Relations de direction d'une entité juridique.
  • GERANCE : Relation de gérance d'une entité juridique.
  • DROIT_PROPRIETE : Relations de droit de propriété d'une entité juridique.
  • GARANTIE : Relation d'engagement de garantie entre un garant et un bénéficiaire de la garantie.
  • PORTEUR_CARTE : Relation de porteur de carte d'une entité juridique.
  • DELEGATION : Relation de délégation d'une personne envers une autre.
  • CONTROLE : Relation de contrôle d'une entité juridique.
  • PROCURATION : Relation de procuration d'une personne envers une autre.
  • ADMINISTRATION : Relation d'administration de biens entre le déposant et le dépositaire.
  • CONFORMITE : Relation désignée pour compléter le recueil d'information client et le questionnaire profil investisseur d'une entité juridique.
  • ENTREPRENEUR_INDIVIDUEL : Relation entrepreneur individuel.
  • INTERLOCUTEUR_SANS_MANDAT : Relation interlocuteur sans mandat.
  • AUTRE_RELATION_PM : Relation autre
  • LIBRE : Relation personnalisée
Array of objects (TypePersonneIdRelation) [ 2 .. 3 ] items

Identification des personnes concernées par la relation.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "FAMILLE",
  • "personneIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "f2d4a982-c1f6-11eb-ba91-0050568a56f0"
}

Supprimer une Relation

Supprime une Relation existante.

Authorizations:
JWT
path Parameters
relationId
required
string (TypeId) [ 1 .. 100 ] characters

Référence (id) de la relation

Responses

Liste des questions/réponses

Je n'arrive pas à créer un premier contact. Quelles sont les données à minima à renseigner pour la création d'un contact ?

Pour créer un contact avec le minimum d'information, il est nécessaire de renseigner à minima ces deux données :

  • /JSON/refExternes/O2S_API
  • /JSON/personne/donneesNominatives/nom
    {
  "refExternes": {
      "O2S_API": "a339e8d3-15fd-11ec-9434-0050568ae49b"
  },
  "personne": {
      "donneesNominatives": {
          "nom": "DUPOND"
      }
  }
}

Dans le format json de l'API, à quoi correspond les données O2S liées à la partie "Patrimoine" (actif/passif) et "Budget" (revenu/charge) ?

Les données liées au Patrimoine se trouvent dans le bloc "stocks", et les données liées au Budget se trouvent dans le bloc "flux".

Comment importer dans O2S la profession d'un contact ?

Le champ "/JSON/profession/professions/profession/applCsp" permet de renseigner le code de la profession (code interne O2S à renseigner, utiliser les services de référenciels pour obtenir les valeurs possibles), et le champ "/JSON/personne/profession/professions/profession/libelleProfession " permet de renseigner le libellé de la profession (champ libre).

Comment faire le lien entre les données d'O2S IHM et les données de l'API O2S ?

Cf la documentation spécifique O2S qui contient une colonne indiquant l'emplacement O2S des valeurs API.

Comment traiter les relations manuelles d'O2S ?

Ce n'est pas possible via l'API. L'import ne permet pas d'importer ces relations, et l'export n'affiche pas les relations manuelles.