🔗DossierFacile Connect

Difficulté d'intégration : 3/10

En quoi consiste le DossierFacile Connect ?

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)

Intégration technique

• Etablissement d'une authentification OAuth2.0

• Appels API

• Réception Webhook - optionnel

Télécharger la présentation

1MB

DossierFacile - Presentation_DossierFacile_Connect.pdf

pdf

Visionner la présentation technique par le développeur

📽️Webinaires d'intégration technique

Le parcours des usagers

Le bouton DossierFacile Connect

Téléchargez le bouton à implémenter

55KB

DossierFacileConnect.zip

archive

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.

Testez DossierFacile Connect avec Postman (environnement bac à sable)

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-preprod.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.

1 - Création d’une requête dans Postman

Créez un endpoint GET sur l’URL https://api-preprod.dossierfacile.fr/dfc/tenant/profile

2 - 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	Authorization Code
Callback URL	https://locataire-preprod.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-preprod.dossierfacile.fr

Cliquez ensuite sur Use Token

3 - Et enfin lancez la requête Postman

4 - Optionnel 1 : utilisation du refresh 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-test-client' \

--data-urlencode 'refresh_token={REFRESH TOKEN VALUE}'\

5 - Optionnel 2 : webhooks

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 de DossierFacile est associé à votre plateforme, vous receviez les changements de statuts de son dossier.

Ainsi, 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 CREATED_ACCOUNT

• Supprime son compte DELETED_ACCOUNT

• Révoque les droits d'accès à un partenaire ACCESS_REVOKED

• Change son type d'application (Seul, En couple ou En colocation) APPLICATION_TYPE_CHANGED

Ou lorsque le dossier est mis à jour par un opérateur ou par une tache planifiée:

• Validé VERIFIED_ACCOUNT

• Décliné DENIED_ACCOUNT

• Supprimé DELETED_ACCOUNT

• Archivé / Retour après inactivité* ARCHIVED_ACCOUNT/RETURNED_ACCOUNT

• Fusionné avec un autre compte MERGED_ACCOUNT

L'URL de votre webhook doit renvoyer un code de statut HTTP 200 ou 202 pour indiquer la bonne réception du message. Tout autre code de statut HTTP, notamment ceux de la catégorie 4XX ou 5XX, sera interprété par notre système comme une erreur de livraison du webhook. En cas d'erreur, notre système pourra effectuer de nouvelles tentatives de livraison (retry).

Le format du callback (certain attribut sont facultatifs selon l'état et le type de 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 / ...
    "applicationType": "XXXX", // type d'application: COUPLE / ALONE / GROUP
    "dossierUrl": "url vers la page de résumé" // lorsque le compte est validé
    "dossierPdfDocumentStatus": "DELETED", // statut génération du document PDF : COMPLETED, ...
    "dossierPdfUrl": "url vers le path du pdf " // !POST pour génération avec GET // lorsque le compte est validé
    "status": "TO_PROCESS", // status de l'apartmentSharing : TO_PROCESS / VALIDATED / DECLINED / INCOMPLETE
    "tenants": ...
    ...
}

Téléchargez le JSON du callback ci-dessous : ⤵️

3KB

example_webhook_content_v4.json

6 - Optionnel : API pour la synchronisation par endpoint

Il est nécessaire d'avoir votre identifiant de connexion pour tester cette fonctionnalité.

Le token de service ne doit en aucun cas être partagé avec vos utilisateurs.

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/token

Par 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-preprod.dossierfacile.fr/swagger-ui

Example de connexion service sur la pré-prod pour la récupération de l'acces token

7 - Voir un exemple de fonctionnement de DFC et le contenu du callback(webhook) lors de la complétion du dossier de location.

Rendez-vous sur la plateforme de simulation suivante :

https://demo-partenaire.dossierfacile.frdemo-partenaire.dossierfacile.fr

8 - Visualiser et modifier votre configuration

Il est possible de visualiser et d'éditer certaines information de votre configuration.

Vous devez vous connecter avec votre client et utiliser le endpoint suivant:

GET {{baseUrl}}/dfc/api/v1/settings : Pour la visualisation

PATCH {baseurl}/dfc/api/v1/settings : Pour l'edition des champs (tout les champs ne sont pas éligible à l'édition - ex: le nom du client)

Ce endpoint vous permet notamment d'éditer: Votre version des API, l'URL de webhook et son x-api-key associé, l'email de contact technique.

Pour rappel, pour obtenir un accessToken "service", il faut appeler le endpoint POST {{baseUrlSSO}}/auth/realms/dossier-facile/protocol/openid-connect/tokenavec dans le body (form) grant_type=client_credentials, clientId=VotreClientId, clientSecret=VotreClientSecret

9 - Prévalidation automatique des documents

Afin d'améliorer la qualité des dossiers et pour optimiser le traitement du dossier au premier passage devant les opérateurs, nous avons mis en place une analyse automatique des dossiers qui est présenté à nos utilisateur.

Lors de l'ajout des pièces du dossier, certains documents sont analysés de façon asynchrone et le résultat de l'analyse est fournie dans la réponse du service au niveau des documents dans un champ documentAnalysisReport qui indique le résultat de l'analyse sur le document et les éventuels manquements détectés sur le document.

Cette analyse est à titre indicative et n'est pas systématique: Elle ne doit pas être bloquante mais est à considérer de manière informative.

// Voici un exemple de résultat de l'analyse dans la réponse de /profile:
"documents": [
    {
...
        {
            "id": XXXXX,
            "documentCategory": "TAX",
            "documentSubCategory": "MY_NAME",
            "noDocument": false,
            "documentStatus": "TO_PROCESS",
            "documentAnalysisReport": {
                "id": XXX,
                "analysisStatus": "DENIED",
                "brokenRules": [
                    {
                        "rule": "R_TAX_NAMES",
                        "message": "Les noms et pr\u00e9noms ne correspondent pas"
                    }
                ],
                "comment": null
            },
            "name": "..."
        },
...
}

Faire une demande d'identifiant

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 (voir#5-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.

Prendre rendez-vous pour plus d'informations

📅Echanger avec un membre de l'équipe