Différences

Ci-dessous, les différences entre deux révisions de la page.

--- tecdoc:api [2023/07/13 09:05]
mactar.ba créée
+++ tecdoc:api [2023/07/26 08:39] (Version actuelle)
mactar.ba
@@ Ligne 1: / Ligne 1: @@
 ====== API CYNOD ======
+Ce document a pour objectif de présenter les API exposées par l’application CYNOD pour la gestion des fonctionnalités internes mais aussi de celles pour la mise en place de services à valeur ajouté de nos clients via les partenaires.
 ===== Vue d'ensemble =====
-==== Objectif ====
-==== Cible ====
+{{ :tecdoc:cynodthirdpartypaymentgateway-overview-wiki-version.jpg?nolink |}}
-===== Installation & Permissions =====
 ===== Sécurité =====
+La sécurité de l’interface est principalement basée sur l’authentification ''oAuth2'' combinée au protocole ''https'' qui est le canal de communication par défaut des échanges.
+D’autres outils internes pourront être mis en place pour renforcer la sécurité tels que le filtrage d’adresse IP, les autorisations de ports et le VPN.
+==== Identification ====
+Les informations suivantes sont mises à la disposition des partenaires autorisés à envoyer des requêtes:
+  - **//consumer-key//**
+  - **//consumer-secret//**
+//:!: Ces informations permettront aux partenaires de pouvoir s’authentifier.//
+==== Authentification ====
+L’authentification est gérée via le protocole ''oAuth2''.
+Une fois connectés via l’API d’authentification, vous aurez un access_token qui vous permettra d’accéder aux autres ressources.
+Les accès se feront en https.
+//:!: Pour les partenaires qui le désirent, l'authentification peut être réalisée en ''Basic Authentication'' **que nous ne recommandons pas**.//
+===== Principe général des échanges =====
+Le format général des APIs respecte les principes ci-dessous :
+  * Les données échangées sont au format ''JSON''.
+  * La gestion des erreurs se base sur les codes ''statuts http'', et un code d’erreur interne selon les principe ci-dessous :
+__**En cas de succès**__
+  * <code java>http status : 200 - OK</code>
+  * payload json de réponse <code>{
+    "success": "true",
+    "code": "success code",
+    "message":"success message to the application user",
+    "data": "response data if necessary"
+}</code>
+__**En cas d'erreur fonctionnelle liée à la requête du client**__
+  * <code java>http status : 400 - Bad Request (Client Error)</code>
+  * payload json avec le détail de l’erreur <code>{
+    "success": "false",
+    "code": "error code message to the app user",
+    "debugMessage": "verbose message for debug purpose",
+    "moreInfo": "null"
+}</code>
+__**En cas d'erreur d'authentification**__
+  * <code java>http status : 401 - Unauthorized </code>
+__**En cas d'erreur système lié à un problème serveur**__
+  * <code java>http status : 500 - Internal Server Error </code>
+  * payload json avec le détail de l’erreur <code>{
+    "success": "false"
+    "code": "9999",
+    "message": "message to the app user",
+    "debugMessage": "verbose message for debug purpose"
+}</code>
+//:!: La description des données échangées est au format ''swagger''. Voir en annexe les différents codes d’erreur.//
+/*
+^ Cas                                                                               ^ Réponse                                                                                                                                                                                                                                                                                                  ^
+| Succès                                                                            | http status : 200 - OK\\ payload json de réponse <code json>{    "success":       "true",     "code":           "success code",     "message":     "success message to the application user"     "data":            "response data if necessary” } </code>                                               |
+| Erreur Fonctionnel\\ (En cas d’erreur fonctionnelle liée à la requête du client)  | http status : 400 - Bad Request (Client Error)/ 404 - Not Found - \\ payload json avec le détail de l’erreur <code json>{\\    "success": "false",\\    "code": "error code message to the app user",\\    "debugMessage": "verbose message for debug purpose",\\     "moreInfo": "null"\\ }\\  </code>  |
+| Erreur Authentification                                                           | http status : 401 - Unauthorized                                                                                                                                                                                                                                                                         |
+| Erreur Système\\ (En cas d’erreur système lié à un problème serveur)              | http status : 500 - Internal Server Error \\ payload json avec une indication de l’erreur <code json>{\\     “success”:false\\      "code": "9999",\\       "message": "message to the app user",\\       "debugMessage": "verbose message for debug purpose"\\ }\\ </code>                              |
+*/
 ===== Base Core API =====
 ===== 3rd Party API =====
+Cette section référence les API CYNOD qui sont mises à la disposition des partenaires pour construire des services digitaux au service de tous.
+==== API de consultation de solde carte ====
+^ Type         | <color #22b14c>**GET**</color>                                 |
+^ URI          | /get-solde-carte                                               |
+^ Description  | envoi d’une requête pour la consultation du solde d’une carte  |
+__**Paramètres :**__
+^ Nom          ^ Description                    ^
+| numeroCarte  | Numéro de la carte du client   |
+| walletId     | Numéro de téléphone du client  |
+| clientId     | Identifiant du client          |
+__**Header :**__
+^ Content-type   | application/json           |
+^ Authorization  |Bearer %%{{ACCESS_TOKEN}}%% |
+__**Request body :**__
+<wrap hi>Aucun</wrap>
+__**Réponses  :**__
+^ Code http    | 200      |
+^ Description  | Success  |
+__//Exemple modèle payload json//__
+<code>
+{
+   "success": true,
+   "code": 200,
+   "message": "Sauf omission* de notre part votre nouveau solde est de 142000  FCFA ",
+   "data": [
+       {
+           "numeroCarte": "7019800100009569",
+           "soldeOnline": 142000.0,
+           "dateSolde": "23-08-2021 10:11:42"
+       }
+   ]
+}
+</code>
+^ Code http    | 400         |
+^ Description  | Bad request |
+__//Exemple modèle payload json//__
+<code>
+{
+   "success": false,
+   "code": "412",
+   "message": "Utilisateur inexistant ou invalide",
+   "debugMessage": "Utilisateur inexistant ou invalide",
+   "moreInfo": null
+}
+</code>
+==== API de vérification de validité d’une carte ====
+^ Type         | <color #22b14c>**GET**</color>                                 |
+^ URI          | /check-card-validity                                           |
+^ Description  | envoi d’une requête pour la validité d’une carte               |
+__**Paramètres :**__
+^ Nom          ^ Description                    ^
+| numeroCarte  | Numéro de la carte du client   |
+| walletId     | Numéro de téléphone du client  |
+| clientId     | Identifiant du client          |
+__**Header :**__
+^ Content-type   | application/json           |
+^ Authorization  |Bearer %%{{ACCESS_TOKEN}}%% |
+__**Request body :**__
+<wrap hi>Aucun</wrap>
+__**Réponses  :**__
+^ Code http    | 200      |
+^ Description  | Success  |
+__//Exemple modèle payload json//__
+<code>
+{
+   "success": true,
+   "code": 200,
+   "message": "Votre carte est valide et valable jusqu'au 18/07/2029",
+   "data": [
+       {
+           "numeroCarte": "7019800100009569",
+           "finValidite": "18/07/2029",
+           "nom": "xxx",
+           "prenom": "xxx",
+           "email": "",
+           "telephone": "",
+           "numeroPiece": "",
+           "dateNaissance": ""
+       }
+   ]
+}
+</code>
+^ Code http    | 400         |
+^ Description  | Bad request |
+__//Exemple modèle payload json//__
+<code>
+{
+   "success": false,
+   "code": "405",
+   "message": "Paramètere numeroCarte manquant ou invalide",
+   "debugMessage": null,
+   "moreInfo": null
+}
+</code>
+==== API de vérification de validité d’une carte en fonction d’un membre ====
+==== API de récupération de la liste de carte d’un membre ou client  ====
+==== API crédit carte (recharge) ====
+==== API dédit carte  (paiement) ====
+==== API access token ====
-II. Présentation de la plateforme monétique
-A. Vue d'ensemble de la plateforme
-B. Architecture de la plateforme
-C. Fonctionnalités principales
-III. API internes
-A. Description des API internes
-B. Liste des endpoints et méthodes disponibles
-C. Paramètres d'entrée et de sortie
-D. Exemples d'utilisation
-E. Authentification et autorisation
-IV. API externes
-A. Description des API externes
-B. Liste des endpoints et méthodes disponibles
-C. Paramètres d'entrée et de sortie
-D. Exemples d'utilisation
-E. Authentification et autorisation
-V. Guides de développement
-A. Bonnes pratiques de développement des API
-B. Recommandations de sécurité
-C. Gestion des erreurs et des exceptions
-D. Gestion des versions des API
-VI. Documentation supplémentaire
-A. Glossaire des termes techniques
-B. FAQ (Foire aux questions)
-C. Références et liens utiles
-VII. Processus de mise à jour de la documentation
-A. Responsabilités des membres de l'équipe
-B. Procédure de soumission des changements
-VIII. Conclusion
-A. Récapitulatif des informations clés
-B. Contact pour toute question ou assistance supplémentaire