🔑

API Partenaire

Difficulté d'intégration : 7/10
Ce type d'intégration n'est pas à privilégier. Les coûts induits peuvent être assez conséquent en terme de développement et de maintenance.

🔑 API

Quels sont les pré-requis techniques ?

Pour mettre en place une intégration de notre API, il vous sera nécessaire de :
  • Avoir un espace utilisateur en mode connecté sur votre application,
  • Développer sur votre application une interface front-end qui ait les mêmes fonctionnalités que la nôtre : formulaires, dépôt de documents et échange avec les utilisateurs.

En quoi consiste l'intégration de notre API ?

En intégrant notre API, vous bénéficierez de la vérification par DossierFacile de dossiers déposés par vos utilisateurs sur votre application.
C'est vous qui créez un compte relié à DossierFacile pour lui avec l'ensemble des documents qu'il vous a transmis. Vous qui devez gérez les relations et les communications avec l'utilisateur. Un certains nombre de mails automatiques envoyés par nos systèmes peuvent être co-brandés.
Les opérateurs de DossierFacile vérifient les documents et vous avez accès à l'ensemble des informations du dossier du candidat locataire.
Pour les utilisateurs qui ont déjà un compte chez DossierFacile, DossierFacile Connect doit être utilisé pour faire la liaison avec le compte. Le compte est ensuite administrable via les API Partenaire.
Il est indispensable que les adresses emails de vos utilisateurs fournies lors de la création du compte par API Partenaire soit réelle et aient été vérifiées.

Le parcours des utilisateurs avec l'API

Ci-dessous, une vidéo d'illustration, non à jour, d'un parcours utilisateur via un partenaire utilisant l'API Partenaire.
Visionner la présentation technique par le développeur

Gestion des mails envoyés aux usagers

DossierFacile a mis en place un parcours de mails transactionnels envoyés à l’utilisateur à différents moments de la constitution du dossier, de sa création, de sa modification et de sa suppression.
Lorsqu’un partenaire utilise l’API Partenaire et que l'utilisateur n'existait pas précédemment sur DossierFacile, le dossier est constitué directement sur le site du partenaire. L’utilisateur n’a pas besoin de passer par DossierFacile qui peut demeurer quasi “transparent” pour lui.
Néanmoins, DossierFacile envoie un certain nombre de mails aux usagers que ce soit pour des raisons de marque d'Etat, des raisons RGPD ou des raisons fonctionnelles.
Pour cela, lors de la création de compte via l’API Partenaire, le partenaire devra renseigner l’adresse réelle de l’usager (et non une adresse fictive ou interne au partenaire) pour que DossierFacile puisse envoyer les emails précédemment cités.
Voici les mails qui seront envoyés par DossierFacile, y compris si l'utilisateur n'a jamais interagi directement avec DossierFacile :
  • à la création de compte : pour expliquer à l’utilisateur qu’un compte DossierFacile à son nom a été créé. Cela correspond à une volonté stratégique de l’Etat de signaler à l’usager que c’est un service public qui assure la validation de son dossier.
  • à + 6 semaines après la création de compte : pour mesurer l’impact de DF où nous demandons aux candidats s’ils ont trouvé un logement. Cela correspond à une volonté stratégique d’évaluation du service et de collecte d’informations relatives au temps de relocation.
  • après une inactivité de 3 mois : un mail de warning est envoyé sur le compte afin de prévenir l’usager de la suppression de ses pièces conformément au RGPD (obligation légale)
  • après une suppression de compte : (obligation RGPD, ne donne lieu à aucune action ensuite de la part de l’usager).
  • après la complétion de son dossier : pour lui indiquer que son dossier est prêt à être traité.
  • après un passage opérateur : pour indiquer le refus ou la validation de son dossier.
En complément, les emails suivants peuvent être co-brandés. Vous pouvez nous transmettre des urls pour que les liens de ceux-ci renvoient vers votre site. Les emails avec la destination du lien sont :
  • "Bienvenue sur DossierFacile" (creation de compte): Le lien renvoie vers la page d'édition du dossier de location.
  • "Nous avons bien reçu votre dossier" (dossier complet): Le lien renvoie vers la page de résumé du dossier de location.
  • "Vous avez reçu un message" (refus de dossier/demande de modification): Le lien renvoie vers la messagerie.
  • "Votre dossier a été validé" (validation du dossier): Le lien renvoie vers la page de partage du dossier de location.
Lorsqu'il y a plusieurs partenaires ou que l'utilisateur s'est connecté sur dossierFacile, les emails ne sont plus co-brandés.
Cette liste est succeptible d'évoluer en fonction des nouvelles fonctionnalité de l'application.

Quelles sont les conditions juridiques ?

Convention de sous-traitance RGPD

Il vous sera demandé de nous retourner la convention de sous-traitance RGPD ci-dessous remplie et signée avant l'intégration de l'API sur votre plateforme.
⚠️
Pensez à compléter l'entête et les paragraphes 5.3 et 5.5.

Obligations d'information des utilisateurs

Les utilisateurs dont le dossier nous est transmis devront être informés :
  • que leurs pièces sont transmises et vérifiés à un service tiers
  • que ce service est proposé par l'Etat
  • qu'ils peuvent partager leur DossierFacile en-dehors de votre plateforme
Pensez à mettre à jour vos CGU et vos registres de traitement de données personnelles !
L'utilisation de l'API étant offerte, le service de vérification ne pourra en aucun cas être proposé comme une option payante à l'utilisateur.

Lien vers le swagger de l'API

Testez l'API avec Postman

API Partenaire DossierFacile est un système vous permettant de créer et modifier un dossier de location DossierFacile pour vos utilisateurs directement sur votre plateforme. Il permet également de mettre en place un webhook vous indiquant quand le statut d’un dossier change.
Ce tutoriel décrit les différentes étapes de l’utilisation via Postman.
L’objectif de l’opération est de dérouler toutes les étapes nécessaires à la création d’un dossier de location DossierFacile jusqu'au statut “TO PROCESS” qui correspond à un dossier complet qui sera alors étudié par nos opérateurs.
Il vous faudra demander un accès pour réaliser vos tests d'intégration. Nous vous invitons à contacter notre équipe qui vous fournira des identifiants nominatifs et adaptés à vos environnements.

1 - Configuration de l’authentification dans Postman

Configurez l’authentification de Postman en Oauth 2.0 puis configurez un nouveau token avec les valeurs suivantes.
Token Name
oauth2 keycloack
Grant Type
Client Credentials
Access Token URL
https://sso-preprod.dossierfacile.fr/auth/realms/dossier-facile/protocol/openid-connect/token
Client ID
{{clientID}}
Client Secret
{{clientSecret}}
Scope
openid
State
Client Authentication
Send as Basic Auth header
Cliquez ensuite sur Get New Access Token puis sur Use Token

2 - Utilisation de l’API Partner

3 - Optionnel : webhooks

Il est possible de configurer un webhook afin qu’une fois qu’un utilisateur s’est logué à DossierFacile depuis votre plateforme, vous receviez les changements de statuts de son dossier. Veuillez contacter l’équipe pour la mise en place de ce webhook.

4 - Cas d’usage : création d’un compte de bout en bout

Séquence des appels API :
{{url}}/api-partner/register/account
{{url}}/api-partner/register/names
{{url}}/api-partner/register/application/v2
{{url}}/api-partner/register/documentIdentification
{{url}}/api-partner/register/documentResidency
{{url}}/api-partner/register/documentProfessional
{{url}}/api-partner/register/documentFinancial
{{url}}/api-partner/register/documentTax
{{url}}/api-partner/register/guarantorType (optionnel -> voir "Documents du garant")
{{url}}/api-partner/register/honorDeclaration
➡️
Le dossier est alors terminé et soumis à validation
Documents du garant en fonction de son type :
  1. 1.
    Cas d’un garant personne physique (jusqu'à 2 garants)
{{url}}/api-partner/register/guarantorNaturalPerson/documentIdentification
{{url}}/api-partner/register/guarantorNaturalPerson/documentResidency
{{url}}/api-partner/register/guarantorNaturalPerson/documentProfessional
{{url}}/api-partner/register/guarantorNaturalPerson/documentFinancial
{{url}}/api-partner/register/guarantorNaturalPerson/documentTax
2. Cas d’un garant organisme
{{url}}/api-partner/register/guarantorOrganism/documentCertificate
3. Cas d’un garant personne morale
{{url}}/api-partner/register/guarantorLegalPerson/documentIdentification
{{url}}/api-partner/register/guarantorLegalPerson/documentRepresentantIdentification

Faire une demande de credentials

Pour récupérer des identifiants de pré-production, écrivez à votre contact partenaire et un développeur vous ouvrira les accès.
Lors de la demande d'un accès en preprod et/ou prod il faudra fournir les URLs de redirections autorisées et l'URL de webhook (non localhost) à utiliser.

Prendre rendez-vous pour plus d'informations