Guide API pour les développeurs

Normes d'interopérabilité

Les APIs fournies par les banques du Groupe Crédit du Nord respectent le standard d'architecture REST et adoptent le niveau 2 du modèle de maturité de Richardson + la convention HAL, comme exigence minimum.

Contrat d'interface : Swagger v2.0

Développements : HTTP 1.1, REST Richardson L2, convention HAL, format JSON et encodage UTF-8

Sécurité : TLS 1.2, OpenID Connect

Bases pour les développements

Langue utilisée

Les APIs des banques du Groupe Crédit du Nord étant ouvertes à l'internationale, l'anglais est la langue adoptée pour leurs publications. En particulier pour leurs descriptions dans les contrats d'interface, pour les champs en entrée/sortie et chemins des APIs.

Granularité d'une API

Chaque API fournie par les banques du Groupe Crédit du Nord n'expose qu'un seul type de ressource (et éventuellement ses sous-ressources).
Exemple : /agencies

Documentation d'une API

Chaque API, ressource et opération fournie par les banques du Groupe Crédit du Nord porte une description fonctionnelle du service rendu et du périmètre couvert. Si des filtres, éléments de pagination, de tri ou de comptage sont implémentés, la description de l'API y fera référence.

La description d'une API contient un tableau qui présente l'historique de toutes les versions encore supportées, ainsi que les coordonnées du(des) responsable(s) technique(s). Les spécifications des APIs sont disponibles dans le fichier de modélisation Swagger, téléchargeable dans le descriptif de l’API.

Explorez nos APIs

Implémentation des méthodes HTTP

Aucune autre méthode HTTP que celles décrites ci-dessous (CRUD), ne sera disponible pour l'utilisation des APIs des banques du Groupe Crédit du Nord :

POST : utilisée pour la création d'une nouvelle ressource. Cette méthode peut également être utilisée pour les opérations ne correspondant à aucune autre méthode (ex : fonctions, opérations de calcul...)

GET : utilisée pour la récupération d'une ou plusieurs ressources

PUT : utilisée pour la mise à jour d'une ou plusieurs ressources (éventuellement par remplacement)

PATCH : utilisée en alternative de la méthode PUT pour des modifications sans remplacement, sur une ressource

DELETE : utilisée pour la suppression d'une ressource

Idempotence

Toutes les APIs fournies par les banques du Groupe Crédit du Nord sont "stateless".

Le principe d'idempotence est également garanti. A savoir que, quel que soit le nombre d'appels identique sur une ressource API, le résultat sera toujours le même sur le serveur (la réponse en revanche peut être différente).

Structure et contenu de la requête API

Authentification et sécurité

Le module « CDN Connect » permet de vous authentifier à la plate-forme « Groupe Crédit du Nord | Portail API », en utilisant les identifiants (login et mot de passe) de votre compte développeur.

Le processus d'accès aux APIs se fera par le transfert d'un Token d'accès, lors de l'appel à celles-ci (dans le Header "Authorization" de la requête). Le mode de récupération de ce Token d'accès pourra être différent suivant les APIs que vous souhaitez utiliser. De même, pour l'utilisation de certaines APIs, l'import d'un certificat pourra vous être demandé lors de l'enregistrement de votre application.

Gestion des versions

Les versions des services mis à disposition par les banques du Groupe Crédit du Nord, portent sur les APIs et non sur les ressources. Il existe deux niveaux de version pour ces APIs : "majeure" et "mineure" ; mais seule la version majeure est à indiquer dans le chemin de l'API.

La disponibilité et le support ne sont effectifs que sur deux versions majeures d'une même API. Ces versions majeures peuvent ne pas être rétro-compatibles, mais les versions mineures le sont.

Utilisation des paramètres

Les paramètres du Header HTTP sont réservés aux métadonnées.

Les paramètres de type "path param" ou "query param", qui forment les requêtes d'API proposées par les banques du Groupe Crédit du Nord, sont de convention typographique : "camelCase".

Les paramètres de type "path param" sont utilisés pour les identifiants des ressources
Exemple : /agencies/{agencyId}/

Tous les autres paramètres sont type "query param"

Structure et contenu de la réponse API

Pagination sur les collections

La pagination sera activée dans la plupart des cas sur les APIs des banques du Groupe Crédit du Nord, pour une requête renvoyant une collection. Les paramètres "offset" et "limit" seront alors présents dans le Header HTTP de la réponse.

Codes retour HTTP utilisés

Seul les codes retours ci-dessous, seront présents dans le Header HTTP de la réponse API :

20x : Succès

200 : La requête a été traitée avec succès pour la récupération ou la mise à jour d'une ressource

201 : La requête a été traitée avec succès pour la création d'une nouvelle ressource

202 : La requête a été accepté pour un traitement asynchrone (avec les méthodes POST, PUT, DELETE ou PATCH)

204 : Le serveur a traité la requête avec succès et aucun contenu n'est attendu en retour

206 : La requête a été traitée avec succès sur une méthode GET, mais seulement une réponse partielle est retournée

40x : Erreur côté client

400 : Erreur générique pour tout type de requête

401 : La requête a échoué car l'utilisateur n'est pas authentifié

403 : La requête a échoué car l'utilisateur n'a pas l'authorization d'accès à la ressource

404 : La requête a échoué car la ressource demandée n'existe pas

422 : La requête a été prise en compte mais certains paramètres sont erronés ou manquants

429 : Trop de requêtes

50x : Erreur côté serveur

500 : Une erreur interne sur le serveur s'est produite

Sécurité des APIs

Nos APIs sont sécurisées au travers du serveur OIDC & OAuth2 CDN Connect. La documentation complète peut être retrouvée ici : https://cdn-connect.groupe-credit-du-nord.com/apidoc/oauth2

Parcours d’authentification forte pour l’utilisation des APIs

Tous marchés : DSP2 - Parcours SCA Canal API V2.pdf

Mécanisme d'urgence

Dans le cas où l'interface dédiée (APIs DSP2) ne fonctionnerait pas conformément à l'article 32 du règlement délégué UE 2018/389, le Groupe Crédit du Nord met à disposition un mécanisme d'urgence.

Le Groupe Crédit du Nord propose aux Prestataires de Services de Paiements agréés, dans le cadre de ce mécanisme d'urgence, un accès sécurisé aux interfaces mises à la disposition des utilisateurs de services de paiement en vue de l'authentification et de la communication avec leur prestataire de services de paiement gestionnaire de comptes.

Ce mécanisme d'urgence, accessible via les liens ci-dessous, est sécurisé via le protocole TLS avec une authentification mutuelle et nécessite la présentation du certificat eIDAS DSP2 QWAC (Qualified Website Authentication Certificate) du Prestataire de Services de Paiement agréé.

Les URL d'accès sont les suivantes :

Parcours d’authentification forte pour l’utilisation du mécanisme d’urgence

Tous marchés : DSP2- Parcours SCA Mécanisme urgence V2.pdf