NAV
json

Description

Lorsque vous disposez de plusieurs partenaires bancaires, il peut s'avérer long et coûteux pour vos opérateurs de saisie de se connecter à chacune des interfaces mise à disposition par ces derniers et d'y saisir toutes les informations relatives aux dossiers que vous souhaitez faire accepter.

Les banques mettent à disposition des API permettant le transfert des données dans le but d'accélérer ce processus.
Vous avez donc surement décidé de développer vos propres solutions et avez pu rapidement vous rendre compte des difficultés de la tâche :

L'API de Keyfast Gateways, en prenant le contrôle du transfert du flux de données, intervient en tant que solution à ces problématiques puisqu'elle propose :

En définitive, l'API de Keyfast Gateways vient corriger les défauts précités dans le but de vous faire gagner un maximum de temps possible. Vos opérateurs de saisie gagneront en productivité et pourront davantage se consacrer à leurs clients.

Informations préliminaires

Environnements

Keyfast Gateways dispose de deux environnements pour vous permettre de stabiliser vos développements et de protéger les données à caractère personnel de vos clients :

Chaque fois que nécessaire dans cette documentation, nous traiterons des deux différents cas (accès au manageur ou URL d'appel par exemple).

Banques disponibles

Dans sa version actuelle, Keyfast Gateways gère l'envoi de données pour les banques suivantes :

Communication et contact

Afin de faciliter les échanges, Keyfast Gateways a choisi Slack.
Pour rejoindre l'espace de travail dédié à nos échanges et pour que nous puissions vous créer des accès à notre manageur (son utilité est évoqué plus loin), vous devrez au préalable en fournir la demande par email dans lequel il faudra nous fournir impérativement les informations de votre société suivantes :

Vous recevrez par email une invitation à rejoindre notre espace de travail et vos mots de passe pour les deux environnements du manageur respectifs.

Lorsque vous aurez joint cet espace, vous disposerez de l'accès à plusieurs canaux :

Gestion des accès

Accès aux API bancaires

Créatis impose qu'on adresse au préalable une demande, à leurs services techniques, (nous nous en chargeons par mail) d'accès à leurs webservices. Pour cette raison, nous vous demandons de bien vouloir nous communiquer votre volonté d'envoyer des dossiers chez eux afin qu'ils puissent débloquer l'accès en 48H (délai fourni par la banque) après notre demande. Sans cette démarche, votre numéro de contremarque sera refusé chez eux et vous obtiendrez une erreur d'authentification.

Accès à l'API de Keyfast Gateways

Afin de centraliser la gestion des identifiants bancaires, Keyfast Gateways dispose d'une interface : le manageur.
L'accès à celle ci dépend de l'environnement dans lequel vous souhaitez administrer vos utilisateurs et identifiants :

Comme évoqué précédemment, vous en avez reçu les accès par email.
Cette application vous permet :

Vous remarquerez également qu'il est possible d'associer un rôle à chaque utilisateur, il est donc nécessaire d'expliquer en quoi ils consistent :

Informations relatives à la structure des identifiants bancaires

Pour la plupart des banques, un seul identifiant est nécessaire, mais ce n'est pas toujours le cas.
Cette section a pour but d'éclaircir ce point.

CFCAL

MyMoneyBank

Authentification et envoi

Exemple du contenu du payload d'authentification :

{
  "email": "exampleemail@test.com",
  "password": "examplepassword"
}

Asurez vous de remplacer exampleemail@test.com par votre email et examplepassword par le mot de passe de votre compte Keyfast Gateways.

Une authentication qui s'est bien déroulée vous retournera un payload sous cette forme :

{
  "status": true,
  "credentials": {
    "accessToken": "myaccesstoken",
    "accessTokenExpireAt": "2022-08-10 13:29:43",
    "refreshToken": "myrefreshtoken",
    "refreshTokenExpireAt": "2022-08-15 12:29:43"
  },
  "user": {
    "id": 50,
    "email": "exampleemail@test.com",
    "description": null,
    "enabled": true,
    "roles": [
      "ROLE_MANAGER",
      "ROLE_USER"
    ],
    "company": {
      "id": 40,
      "name": "mycompany"
    }
  }
}

Keyfast Gateways utilise un système d'authentification basé sur un token d'accès à durée limitée.
Pour obtenir un token, vous devrez vous authentifier sur l'API via les URL suivantes :

Le token ainsi obtenu devra être envoyé dans l'entête de la requête Authorization avec comme valeur Bearer mytoken pour chaque envoi de dossier.

Les URL de base pour envoyer vos dossiers sont différentes selon l'environnement :

Vous devrez enfin ajouter le slug correspondant à la banque à la fin de l'URL.
Voici la liste des slugs actuellement disponibles :

Structure du payload

Les modèles

Voici un exemple de payload correctement formaté (scrollable car très long) :

{
  "property": [
    {
      "borrowers_reference": [
        0
      ],
      "is_acquitted": 0,
      "is_included_in_guarantee": 0,
      "mortgage_rank": "",
      "mortgage_amount": "",
      "environment": "excellent",
      "title_of_property": "Maison",
      "patrimony": "house",
      "property_type": "none",
      "owner_type": "full_ownership",
      "rate": "",
      "standing": "normal",
      "use_of_property": "main",
      "initial_price": "0",
      "value": "280000",
      "estimate_date": "2023-04-21",
      "estimated_amount": "280000",
      "estimation_type": "notary",
      "construction_date": "1970-01-01",
      "acquisition_date": "",
      "cadastral_ref": "",
      "type_proof_area": "valued",
      "area": "",
      "address": {
        "number": "",
        "way_type": "",
        "way_name": "",
        "complement": "",
        "place_known_as": "",
        "floor": "",
        "zip_code": "",
        "city": "",
        "country": ""
      }
    }
  ],
  "borrower": [
    {
      "is_main": 1,
      "civility": "miss",
      "firstname": "Inspecteur",
      "lastname": "Gadget",
      "alt_firstname": "",
      "legal_capacity": "capable_adult",
      "is_sci_representative": 0,
      "sci_share": "0",
      "is_ficp": 0,
      "is_fcc": 0,
      "birth": {
        "name": "Gadget",
        "birthdate": "1967-01-18",
        "nationality": "FR",
        "country": "FR",
        "zip_code": "97400",
        "city": "SAINT-DENIS"
      },
      "residence": {
        "residential_status": "freehold_no_sci",
        "entry_date": "2001-01-01",
        "owner_profil": ""
      },
      "address": {
        "number": "20",
        "way_type": "",
        "way_name": "Rue des chemins",
        "complement": "",
        "place_known_as": "",
        "floor": "",
        "zip_code": "59400",
        "city": "Cambrai",
        "country": "FR"
      },
      "id_piece": {
        "type": "none",
        "number": "",
        "start_date": "",
        "end_date": "",
        "place_of_creation": ""
      },
      "contact": {
        "phone": [
          {
            "number": "+262692959273",
            "usage": "personal"
          }
        ],
        "email": "rose.rouge@hotmail.fr"
      },
      "relation": {
        "relation_type": "single",
        "start_date": "2007-03-24",
        "matrim_regime": "",
        "separation_type": ""
      },
      "dependents": [
        {
          "gender": "male",
          "name": "Roberto",
          "birthdate": "2003-12-30",
          "dependent_type": "dependent_child",
          "family_link": "child"
        }
      ]
    }
  ],
  "activity": [
    {
      "borrower_reference": "0",
      "is_main": 1,
      "activity": "Fonctionnaire",
      "has_valid_trial_period": 1,
      "employer": "EPIDE",
      "activity_type": "public",
      "socio_pro_category": "school_teachers_primary_school_teachers_and_similar",
      "start_date": "1993-01-01",
      "end_date": "",
      "contract_type": "civil_servant",
      "country_of_practice": "",
      "has_payday_advance": 0,
      "has_seizure": 0,
      "siret": "",
      "ape_code": "",
      "address": {
        "number": "",
        "way_type": "",
        "way_name": "Rue du Moulinel",
        "complement": "",
        "place_known_as": "",
        "floor": "",
        "zip_code": "",
        "city": "",
        "country": ""
      },
      "contact": {
        "phone": [
          {
            "number": "+33327733665",
            "usage": "professional"
          }
        ],
        "email": ""
      }
    }
  ],
  "additional_record": {
    "is_ok_for_postal_mail": 0,
    "is_ok_for_tele_sales": 0
  },
  "bank_situation": [
    {
      "borrowers_reference": [
        0
      ],
      "is_main": 1,
      "created_date": "2000-01-01",
      "account_number": "",
      "iban": "FR7619906009743000824574260",
      "bic": "AGRIRERX",
      "bank_name": "Credit agricole",
      "bank_code": "credit_agricole",
      "beginning_balance": "0",
      "ending_balance": "2796.24",
      "exceptionals_expenses": "0",
      "number_months_account_statements": "3",
      "exceptionals_incomes": "0",
      "credit_card": "none",
      "revolving_credit_release_amount": "0",
      "revolving_credit_release_amount_used_m1": "0",
      "revolving_credit_release_amount_used_m2": "0",
      "revolving_credit_release_amount_used_m3": "0",
      "number_of_rejects": "0",
      "number_of_regularized_rejections": "0",
      "total_unpaid_months": "0",
      "mortgage_unpaid_months": "0",
      "mortgage_unpaid_regularized": "0",
      "total_unpaid_not_regularized": "0",
      "mortgage_unpaid_not_regularized": "0",
      "last_month_total_unpaid_not_regularized": "0",
      "last_month_mortgage_unpaid_not_regularized": "0",
      "has_late_rent": 0,
      "has_increase_or_delay_income_tax": 1,
      "has_bailiff_or_collection_company": 0,
      "has_other_delay": 0,
      "has_intervention_committee": 0,
      "saving_type": "",
      "saving_amount": ""
    }
  ],
  "credit": [
    {
      "borrowers_reference": [
        0
      ],
      "nature_of_loan": "non_mortgage_personal_loan",
      "sub_type": "",
      "loan_reference": "RP220600881",
      "nature_of_info": "not_disclosed",
      "start_date": "2022-08-05",
      "periodic_amount": "137.77",
      "periodicity": "monthly",
      "creditor_name": "SOREFI",
      "creditor_code": "sorefi",
      "bank_name": "",
      "account_number": "",
      "account_owner": "",
      "is_to_be_kept": 0,
      "is_already_redeeming": 0,
      "nominal_rate": "8",
      "early_repayment_noticeperiod": "",
      "init_cap": "7000",
      "res_term_month": "40",
      "init_term_month": "48",
      "report_term_month": "0",
      "release_fees": "0",
      "is_with_notice": 0,
      "notice_period": "0",
      "is_already_covered": 0,
      "nature_of_consumer_good": "",
      "remaining_capital_due": "4301.05",
      "arl_repay_fees": "0",
      "pieces": {
        "contract": 0,
        "amortization_table": 0,
        "addendum": 0,
        "account_statements": 0
      },
      "address": {
        "number": "1",
        "way_type": "RUE",
        "way_name": "de la banque",
        "complement": "",
        "place_known_as": "",
        "floor": "",
        "zip_code": "75002",
        "city": "Paris",
        "country": "FR"
      }
    },
    {
      "borrowers_reference": [
        0
      ],
      "nature_of_loan": "non_mortgage_personal_loan",
      "sub_type": "",
      "loan_reference": "81015766112",
      "nature_of_info": "not_disclosed",
      "start_date": "2020-01-01",
      "periodic_amount": "254.58",
      "periodicity": "monthly",
      "creditor_name": "Sedef",
      "creditor_code": "sedef",
      "bank_name": "",
      "account_number": "",
      "account_owner": "",
      "is_to_be_kept": 0,
      "is_already_redeeming": 0,
      "nominal_rate": "10",
      "early_repayment_noticeperiod": "",
      "init_cap": "15000",
      "res_term_month": "56",
      "init_term_month": "96",
      "report_term_month": "0",
      "release_fees": "0",
      "is_with_notice": 0,
      "notice_period": "0",
      "is_already_covered": 0,
      "nature_of_consumer_good": "",
      "remaining_capital_due": "5295.88",
      "arl_repay_fees": "0",
      "pieces": {
        "contract": 0,
        "amortization_table": 0,
        "addendum": 0,
        "account_statements": 0
      },
      "address": {
        "number": "1",
        "way_type": "RUE",
        "way_name": "de la banque",
        "complement": "",
        "place_known_as": "",
        "floor": "",
        "zip_code": "75002",
        "city": "Paris",
        "country": "FR"
      }
    },
    {
      "borrowers_reference": [
        0
      ],
      "nature_of_loan": "revolving_credit",
      "sub_type": "",
      "loan_reference": "530 053 547 90",
      "nature_of_info": "not_disclosed",
      "start_date": "2021-01-01",
      "periodic_amount": "46.61",
      "periodicity": "monthly",
      "creditor_name": "Sedef",
      "creditor_code": "sedef",
      "bank_name": "",
      "account_number": "",
      "account_owner": "",
      "is_to_be_kept": 0,
      "is_already_redeeming": 0,
      "nominal_rate": "20",
      "early_repayment_noticeperiod": "",
      "init_cap": "3000",
      "res_term_month": "69",
      "init_term_month": "96",
      "report_term_month": "0",
      "release_fees": "0",
      "is_with_notice": 0,
      "notice_period": "0",
      "is_already_covered": 0,
      "remaining_capital_due": "666.83",
      "arl_repay_fees": "0",
      "pieces": {
        "contract": 0,
        "amortization_table": 0,
        "addendum": 0,
        "account_statements": 0
      },
      "address": {
        "number": "1",
        "way_type": "RUE",
        "way_name": "de la banque",
        "complement": "",
        "place_known_as": "",
        "floor": "",
        "zip_code": "75002",
        "city": "Paris",
        "country": "FR"
      }
    }
  ],
  "debt": [
    {
      "borrowers_reference": [
        0
      ],
      "nature_of_debt": "private_debt",
      "debt_reference": "598526655ADDSSS55488",
      "remaining_capital_due": "6340.4",
      "start_date": "2019-02-05",
      "periodic_amount": "870",
      "creditor_name": "Autre Retard",
      "creditor_code": "other",
      "is_to_be_kept": 0,
      "third_signatories": "",
      "init_cap": "20000",
      "res_term_month": "8",
      "init_term_month": "59",
      "address": {
        "number": "1",
        "way_type": "RUE",
        "way_name": "de la banque",
        "complement": "",
        "place_known_as": "",
        "floor": "",
        "zip_code": "75002",
        "city": "Paris",
        "country": "FR"
      }
    },
    {
      "borrowers_reference": [
        0
      ],
      "nature_of_debt": "income_tax",
      "debt_reference": "BSF 2504",
      "remaining_capital_due": "12015.5",
      "start_date": "2023-04-19",
      "periodic_amount": "200",
      "creditor_name": "Tresor Public",
      "creditor_code": "tresor_publique",
      "is_to_be_kept": 0,
      "third_signatories": "",
      "init_cap": "12015.5",
      "res_term_month": "60",
      "init_term_month": "60",
      "address": {
        "number": "1",
        "way_type": "RUE",
        "way_name": "de la banque",
        "complement": "",
        "place_known_as": "",
        "floor": "",
        "zip_code": "75002",
        "city": "Paris",
        "country": "FR"
      }
    }
  ],
  "income": [
    {
      "borrowers_reference": [
        0
      ],
      "periodic_amount": "4144.13",
      "income_type": "salary",
      "periodicity": "monthly",
      "is_permanent": 1,
      "start_date": "",
      "end_date": ""
    }
  ],
  "charge": [],
  "financing": {
    "total_duration": "84",
    "deprecation_type": "linear",
    "periodicity": "monthly",
    "rate_type": "fixed",
    "remuneration_type": "commissionIOBSP",
    "is_with_guarantee": 0,
    "courtage_fees_amount": "1938",
    "courtage_fees_rate": "5.5",
    "notary_name": "",
    "insurance": [
      {
        "borrower_reference": "0",
        "insurer_identifier": "mutlog",
        "type_of_insurance_capital": "initial_capital",
        "type": "insurance_group",
        "formula": "dc_ptia_itt",
        "rate": "100"
      }
    ],
    "treasury": [
      {
        "cashflow_type": "comfort_treasury",
        "cashflow_duration": "84",
        "cashflow_amount": "4000"
      }
    ],
    "notary_address": {
      "number": "",
      "way_type": "",
      "way_name": "",
      "complement": "",
      "place_known_as": "",
      "floor": "",
      "zip_code": "",
      "city": "",
      "country": ""
    },
    "product": {
      "contributor_business_code": "",
      "contributor_code": "",
      "vendor_code": "",
      "commercial_offer_code": "",
      "product_code": "",
      "sub_product_code": "",
      "nature_of_property_code": "",
      "order_form_reference": "",
      "delivery_date": "",
      "property_value": "310000",
      "monthly_with_insurance": "1508.96",
      "scale_code": "",
      "number_due_day": "30"
    }
  }
}

L'idée de ce document n'est pas de détailler toutes les propriétés qui devront être présentes dans votre payload mais d'apporter des précisions complémentaires à la documentation autogénérée par le manageur de Keyfast Gateways.

La structure du payload de chaque dossier repose sur l'existence de plusieurs clés principales que nous qualifions de modèles.
Par exemple, le CommonModel représente le payload en son intégralité et le BorrowerModel représente une sous clé borrower.

À droite de cette sous-section, nous vous fournissons un exemple de payload correctement formaté afin que vous puissiez mieux comprendre ce système.

Certains modèles comme le AddressModel sont des sous clés qui pourront apparaitre plusieurs fois dans votre payload et à différents endroits (par exemple en tant que sous clé de borrower ou de notary). L'intérêt de cette pratique est que chacune des définitions d'une adresse possède une structure identique à l'autre.

Cardinalité des propriétés

Exemple d'une propriété non obligatoire et vide :

{
  "property": []
}

Sur certaines propriétés du payload, vous pourrez observer qu'il existe un astérisque. La présence de ce dernier détermine l'obligation ou non de renseigner la propriété.

Capture d'écran d'une propriété obligation possédant un astérisque

Dans cet exemple, l'emprunteur doit à chaque fois posséder un attribut is_main pour que l'API de Keyfast Gateways puisse déterminer s'il s'agit de l'emprunteur principal ou non.

En revanche, un emprunteur n'est pas dans l'obligation d'être propriétaire. Par conséquent, la propriété property peut être un tableau vide.

Il arrivera souvent qu'il soit imposé le fait de renseigner une propriété pour une ou plusieurs banques :

Capture d'écran d'une propriété obligatoire pour une seule banque

Dans cet exemple, la clé is_permanent n'est obligatoire que si vous envoyez le dossier à CFCAL (Required field for CFCAL.). Vous pouvez l'omettre pour les autres banques.

Spécificités de certaines listes

Certaines propriétés de type string ne permettent pas une saisie libre et imposent de choisir parmi une liste de valeurs possibles.

Capture d'écran d'une liste

Ces listes sont généralement valables pour toutes les banques.

Les données optionnelles

Un modèle d'options a été intégré à notre API depuis sa version 1.5.
Ce dernier vous permet d'ajouter des données supplémentaires nécessaires à la bonne execution de la requête.

Cette section a pour but de préciser tous les cas d'application pour lesquels ce modèle vous sera utile et comment l'utiliser convenablement.

Gestion des doublons Créatis

Exemple d'un retour de doublon Créatis :

{
  "status": false,
  "level": "Bank",
  "errors": "Aborted injection by bank API",
  "identifier": "cae1e793-de1f-4a1f-a4da-768ade7b9b6d",
  "details": {
    "message": "It seems that one of the borrowers (or both of them) is already known by Créatis. Please resubmit your payload with the necessary additional information (refer to the documentation for more details).",
    "request_id": "2023-02-15-09.25.53.823402",
    "known_borrowers": {
      "borrower": [
        {
          "id": "7B6C674244E8BB689955D627CDF742B8B264E32249DD786F4838013A70F7DF2C",
          "birthname": "ELLESSEDEUXGO",
          "firstname": "RECETTE",
          "birthdate": "19721107",
          "birthcity": "BETHUNE"
        }
      ],
      "co_borrower": [
        {
          "id": "5B3BA792099910F11B9D372D1A40D18DF807D6A88BB33B2BB6E4DB4C06365A3C",
          "birthname": "GRANIE",
          "firstname": "JULIE",
          "birthdate": "19800510",
          "birthcity": "SAINT DENIS"
        }
      ]
    }
  }
}

Exemple de contenu de la clé options à ajouter à votre prochaine requête après le retour de Créatis précédent :

{
  "options": {
    "complement": {
      "request_id": "2023-02-15-09.25.53.823402",
      "known_borrowers": [
        {
          "borrower_reference": "0",
          "creatis_id": "7B6C674244E8BB689955D627CDF742B8B264E32249DD786F4838013A70F7DF2C"
        },
        {
          "borrower_reference": "1",
          "creatis_id": "5B3BA792099910F11B9D372D1A40D18DF807D6A88BB33B2BB6E4DB4C06365A3C"
        }
      ]
    }
  }
}

Créatis check si l'emprunteur ou le coemprunteur n'est/ne sont pas déjà connu(es) de leurs services.
Le dossier peut se voir refusé pendant l'étape d'injection pour cette raison et nécessite donc de choisir parmi une liste de tiers au préalable avant de renvoyer la requête en intégralité avec un identifiant permettant de raccrocher la nouvelle requête à la demande initiale.

Vous trouverez à droite un exemple de retour de l'API de Keyfast Gateways dans le pire des cas : Créatis a détecté 2 doublons (emprunteur et coemprunteur), et un exemple de données additionnelles à ajouter à votre nouvelle requête pour régler ce problème.

Dans cette situation, le contenu de details est d'une importance capitale :

Dans cette situation, il suffira d'ajouter en options de votre payload les informations nécessaires pour permettre à Créatis de passer en mode séléction et d'accepter le dossier tel que dans l'exemple qui vous est communiqué.

Si tout s'est bien passé, le retour de la banque sera alors un retour positif classique.

Réponse

Structure

Exemple d'un retour positif de la part de MyMoneyBank :

{
  "status": true,
  "level": "Bank",
  "message": {
    "eligible": true,
    "processus": "standard",
    "processusExpertise": "NA",
    "ratioHypothecaire": "0",
    "mtEstimationsBiens": {
      "devise": "EUR",
      "valeur": "0"
    }
  }
}

Keyfast Gateways vous retournera toujours un JSON avec au moins deux clés :

Dans certains cas, Keyfast Gateways y ajoutera les clés :

Erreurs

Exemple d'un retour d'erreur 400 :

{
  "status": false,
  "level": "KeyfastGateways",
  "errors": [
    {
      "path": "debt[0].periodic_amount",
      "error": "The periodic debt amount is required"
    },
    {
      "path": "debt[0].is_to_be_kept",
      "error": "The debt must be kept or redeemed but cannot be null"
    }
  ],
  "identifier": "b97146ce-fb39-47a6-8cf4-b8e89f8fcdb5"
}

Ici, debt est la clé et [0] une référence de tableau. Ces messages signifient donc que pour la dette déclarée en premier, les champs periodic_amount et is_to_be_kept n'ont pas été, ou du moins pas correctement, renseignés.

Voici les différentes erreurs que l'API de Keyfast Gateways pourraient vous retourner ainsi que le comportement à adopter en fonction de chacune :

Code Explication
400 Bad Request -- Votre requête est invalide.
401 Unauthorized -- Votre token d'accès ou vos identifiants est/sont invalide(s).
403 Forbidden -- Un identifiant bancaire rattaché à votre compte pour le partenaire ciblé est inexistant.
404 Not Found -- Vous appelez une route qui n'existe pas.
405 Method Not Allowed -- Vous n'utilisez pas la bonne méthode de requête HTTP.
500 Internal Server Error -- Contactez nous via votre canal slack dédié.
json