🔗
DossierFacile Connect
Difficulté d'intégration : 3/10
DossierFacile Connect est la solution qui utilise la connexion SSO (single-sign-on) de DossierFacile pour permettre à un candidat de partager les informations de son dossier de location.
Un bouton de connexion est intégré à votre site qui permet à l’utilisateur de se connecter à DossierFacile. Il devra consentir à partager ses informations et la liaison entre son compte DossierFacile et votre plateforme sera établie.
Si l'utilisateur n'a pas encore de compte DossierFacile, il aura la possibilité de le créer. Il devra suivre le scénario complet pour que son compte soit utilisable (validation de son email ou connexion via FranceConnect)
- Etablissement d'une authentification OAuth2.0
- Appels API
- Réception Webhook - optionnel
DossierFacile - Presentation_DossierFacile_Connect.pdf
1MB
PDF
Téléchargez le bouton à implémenter
DossierFacileConnect.zip
55KB
Binary
Aperçu du bouton DossierFacile Connect
Ajoutez le court texte de présentation suivant.
DossierFacile est le dossier de location numérique de l'Etat. Entièrement gratuit, conforme et sécurisé, il protège les locataires et rassure les propriétaires.
DossierFacile Connect vous permettant de récupérer les informations du dossier de location d’un de 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 avec Postman.
L’objectif de base est de pouvoir appeler le endpoint https://api-dev.dossierfacile.fr/dfc/tenant/profile qui contient les informations du dossier de location de l’utilisateur qui consent à partager ses informations.
Le client de test permet de découvrir les API. Pour vos tests d'intégration, nous vous invitons à contacter notre équipe qui vous fournira des identifiants nominatifs et adaptés à vos environnements sur notre plateforme de préproduction.
Notamment les elements pour mettre en place les webhook et accéder aux API de DFC.
Créez un endpoint
GET sur l’URL https://api-dev.dossierfacile.fr/dfc/tenant/profile
Configurez l’authentification de Postman en Oauth 2.0 puis configurez un nouveau token avec les valeurs suivantes.
| |
Token Name | oauth2 keycloack |
Grant Type | Authorization Code |
Callback URL | https://locataire-dev.dossierfacile.fr |
Authorize using browser | non coché |
Auth URL | https://sso-preprod.dossierfacile.fr/auth/realms/dossier-facile/protocol/openid-connect/auth |
Access Token URL | https://sso-preprod.dossierfacile.fr/auth/realms/dossier-facile/protocol/openid-connect/token |
Client ID | dfc-test-client |
Client Secret | |
Scope | openid |
State | |
Client Authentication | Send as Basic Auth header
|
Cliquez ensuite sur Get New Access Token, une fenêtre d’identification DossierFacile va s’ouvrir.
Il est possible de pré-remplir par défaut l'adresse e-mail du locataire en ajoutant
login_hint en paramètre de l'Auth URL.De même, il est possible d'empêcher partiellement le changement d'e-mail avec le paramètre
login_edit_disableden paramètre de l'Auth URL.
Toutefois, ce comportement peut être by-passé en utilisant la connection FC ou en tapant un mot de passe erroné.
Renseignez les champs avec les identifiants d’un compte créé préalablement sur https://locataire-dev.dossierfacile.fr
Cliquez ensuite sur Use Token
Il existe dans la réponse à l’authentification un refresh token, qui permet de générer un nouveau token d’authentification afin d’accéder au endpoint /dfc/tenant/profile à nouveau sans demander à l’utilisateur de se reconnecter.
curl --location --request POST https://sso-preprod.dossierfacile.fr/auth/realms/dossier-facile/protocol/openid-connect/token' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'grant_type=refresh_token' \--data-urlencode 'client_id=dfc-locservice' \--data-urlencode 'refresh_token={REFRESH TOKEN VALUE}'
Il est necessaire d'avoir votre identifiant de connexion pour tester cette fonctionnalité
Il est possible de configurer un webhook afin qu’une fois qu’un utilisateur s’est loggé à DossierFacile depuis votre plateforme, vous receviez les changements de statuts de son dossier.
Une fois que l'utilisateur s'est loggé à DossierFacile depuis votre plateforme, vous recevez les modifications des statuts sur l'URL de callback. Cela s'opère dès lors que l'utilisateur effectue l'une des actions suivantes :
- complète son dossier
- supprime son compte.
Ou lorsque le dossier est traité par un opérateur:
- Validé
- décliné
- archivé/supprimé
Le format du callback :
Requête POST sur l'URL prédéfinie contenant le body JSON :
A la validation
{
"id": 0, // Id de l'apartmentSharing
"onTenantId": 1, // tenant duquel provient l'evenement
"partnerCallBackType": "XXXXXXX", // type de CallBack: DELETED_ACCOUNT / VERIFIED_ACCOUNT / CREATED_ACCOUNT / DENIED_ACCOUNT
"applicationType": "XXXX", // type d'application: COUPLE / ALONE / GROUP
"dossierPdfDocumentStatus": "DELETED", // statut génération du document PDF : COMPLETED, ...
"status": "TO_PROCESS", // status de l'apartmentSharing : TO_PROCESS / VALIDATED / DECLINED / INCOMPLETE
"tenants": ...
...
}
Téléchargez le JSON du callback ci-dessous :
⤵
2-callback_version2.json
4KB
Code
Il est necessaire d'avoir votre identifiant de connexion pour tester cette fonctionnalité
En plus de la récupération des données de l'utilisateur par connexion avec
{baseurl_API}/dfc/tenant/profile et de la synchronisation par réception du webhook, DossierFacile permet également aux partenaires de récupérer la liste des utilisateurs DossierFacile qui sont associés à leur système et de récupérer leurs données.Pour appeler ces endpoints (
{baseurl_API}/dfc/api/v1/**), il est nécessaire de réaliser une authentification OAuth2 du service via {baseurl_SSO}/auth/realms/dossier-facile/protocol/openid-connect/tokenPar mesure de sécurité, ces endpoints ne sont pas activés par défaut pour tous les partenaires. Rapprochez-vous de votre interlocuteur DossierFacile pour son activation.
Pour plus d'information consulter la documentation Swagger https://api.dossierfacile.fr/swagger-ui/?urls.primaryName=API%20DFC#/
Example de connexion service sur la pré-prod pour la récupération de l'acces token
Rendez-vous sur la plateforme de simulation suivante :
Pour récupérer des identifiants de préproduction, écrivez à un membre de l'équipe pour être mis en relation avec un développeur. Echanger avec un membre de l'équipe
Pensez à bien indiquer dans le mail vos URLs de redirection et vos URLs de webhook si vous voulez utiliser les webhooks (voir5-optionnel-2-webhook).
Il faut d'abord utiliser les identifiants de la documentation pour tester la connexion et travailler depuis un poste local (cf URL de callback en localhost).
Lors de la demande d'un accès privé en preprod et/ou prod il faut fournir l'URL de callback (non localhost) et l'URL de webhook à utiliser.