fasoarzeka 0.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fasoarzeka-0.0.1/LICENSE +21 -0
- fasoarzeka-0.0.1/PKG-INFO +676 -0
- fasoarzeka-0.0.1/README.md +649 -0
- fasoarzeka-0.0.1/fasoarzeka.egg-info/PKG-INFO +676 -0
- fasoarzeka-0.0.1/fasoarzeka.egg-info/SOURCES.txt +16 -0
- fasoarzeka-0.0.1/fasoarzeka.egg-info/dependency_links.txt +1 -0
- fasoarzeka-0.0.1/fasoarzeka.egg-info/requires.txt +2 -0
- fasoarzeka-0.0.1/fasoarzeka.egg-info/top_level.txt +2 -0
- fasoarzeka-0.0.1/pyproject.toml +31 -0
- fasoarzeka-0.0.1/setup.cfg +4 -0
- fasoarzeka-0.0.1/setup.py +30 -0
- fasoarzeka-0.0.1/src/__init__.py +41 -0
- fasoarzeka-0.0.1/src/arzeka.py +1018 -0
- fasoarzeka-0.0.1/src/exceptions.py +39 -0
- fasoarzeka-0.0.1/src/utils.py +185 -0
- fasoarzeka-0.0.1/test/__init__.py +0 -0
- fasoarzeka-0.0.1/test/test.py +807 -0
fasoarzeka-0.0.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Mohamed Zeba
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,676 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fasoarzeka
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: API non officielle de paiement mobile pour le service FASO ARZEKA au Burkina Faso
|
|
5
|
+
Home-page: https://github.com/parice02/fasoarzeka
|
|
6
|
+
Author: Mohamed Zeba
|
|
7
|
+
Author-email: Mohamed ZEBA <m.zeba@mzeba.dev>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
Project-URL: Homepage, https://github.com/mzeba/fasoarzeka
|
|
10
|
+
Project-URL: Issues, https://github.com/mzeba/fasoarzeka/issues
|
|
11
|
+
Project-URL: Repository, https://github.com/mzeba/fasoarzeka.git
|
|
12
|
+
Keywords: fasoarzeka ,burkina payment api,mobile money,payment api,burkina faso
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Requires: request
|
|
17
|
+
Requires: urllib3
|
|
18
|
+
Requires-Python: >=3.8
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Requires-Dist: requests>=2.31.0
|
|
22
|
+
Requires-Dist: urllib3<1.27
|
|
23
|
+
Dynamic: author
|
|
24
|
+
Dynamic: home-page
|
|
25
|
+
Dynamic: license-file
|
|
26
|
+
Dynamic: requires
|
|
27
|
+
|
|
28
|
+
# FASO ARZEKA Mobile Money Payment API (Burkina Faso)
|
|
29
|
+
|
|
30
|
+
[](https://www.python.org/downloads/)
|
|
31
|
+
[](LICENSE)
|
|
32
|
+
|
|
33
|
+
API client Python non officiel pour les paiements mobiles FASO ARZEKA au Burkina Faso v3.0.1.
|
|
34
|
+
Client robuste, production-ready avec gestion automatique des erreurs, retry automatique, et réauthentification automatique.
|
|
35
|
+
|
|
36
|
+
## ✨ Fonctionnalités principales
|
|
37
|
+
|
|
38
|
+
- ✅ **Authentification sécurisée** avec gestion automatique des tokens
|
|
39
|
+
- ✅ **Réauthentification automatique** quand le token expire
|
|
40
|
+
- ✅ **Gestion complète des erreurs** avec exceptions personnalisées
|
|
41
|
+
- ✅ **Retry automatique** avec backoff exponentiel
|
|
42
|
+
- ✅ **Logging intégré** pour traçabilité complète
|
|
43
|
+
- ✅ **Session persistante** pour meilleures performances
|
|
44
|
+
- ✅ **Type hints complets** pour meilleure auto-complétion
|
|
45
|
+
- ✅ **Context manager** pour gestion automatique des ressources
|
|
46
|
+
- ✅ **Validation des tokens** avec informations d'expiration
|
|
47
|
+
- ✅ **Tests unitaires complets** avec couverture >90%
|
|
48
|
+
|
|
49
|
+
## 📋 Prérequis
|
|
50
|
+
|
|
51
|
+
1. **Compte API Arzeka Money**
|
|
52
|
+
- Username
|
|
53
|
+
- Password
|
|
54
|
+
- Hash Secret
|
|
55
|
+
- Merchant ID
|
|
56
|
+
|
|
57
|
+
2. **Certificats SSL** (si fournis par l'opérateur)
|
|
58
|
+
|
|
59
|
+
3. **Python 3.9 ou supérieur**
|
|
60
|
+
|
|
61
|
+
## 📦 Dépendances
|
|
62
|
+
|
|
63
|
+
```txt
|
|
64
|
+
requests>=2.31.0
|
|
65
|
+
setuptools
|
|
66
|
+
urllib3
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Le client nécessite Python 3.9 ou supérieur.
|
|
70
|
+
|
|
71
|
+
## 🚀 Installation
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
# Avec pip
|
|
75
|
+
pip install git+https://github.com/parice02/fasoarzeka.git
|
|
76
|
+
|
|
77
|
+
# Avec poetry
|
|
78
|
+
poetry add git+https://github.com/parice02/fasoarzeka.git
|
|
79
|
+
|
|
80
|
+
# Installation en mode développement
|
|
81
|
+
git clone https://github.com/parice02/fasoarzeka.git
|
|
82
|
+
cd fasoarzeka
|
|
83
|
+
pip install -e .
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## 🎯 Guide de démarrage rapide
|
|
87
|
+
|
|
88
|
+
### Option 1 : Utilisation avec fonctions de convenance (Recommandé)
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
from arzeka import authenticate, initiate_payment, check_payment
|
|
92
|
+
|
|
93
|
+
# 1. Authentifiez-vous une fois
|
|
94
|
+
auth = authenticate("your_username", "your_password")
|
|
95
|
+
print(f"Token expires in: {auth['expires_in']} seconds")
|
|
96
|
+
|
|
97
|
+
# 2. Initiez un paiement
|
|
98
|
+
payment_data = {
|
|
99
|
+
"amount": 1000, # Montant en FCFA (minimum 100)
|
|
100
|
+
"merchant_id": "MERCHANT_123",
|
|
101
|
+
"additional_info": {
|
|
102
|
+
"first_name": "Jean",
|
|
103
|
+
"last_name": "Dupont",
|
|
104
|
+
"mobile": "22670123456" # Numéro avec indicatif
|
|
105
|
+
},
|
|
106
|
+
"mapped_order_id": "eT20220923.203221.24732",
|
|
107
|
+
"hash_secret": "your_hash_secret",
|
|
108
|
+
"link_for_update_status": "https://example.com/webhook",
|
|
109
|
+
"link_back_to_calling_website": "https://example.com/return"
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
response = initiate_payment(payment_data)
|
|
113
|
+
print(f"URL to redirect user for payment: {response['url']}")
|
|
114
|
+
|
|
115
|
+
# 3. Vérifiez le statut du paiement
|
|
116
|
+
payment_response = check_payment(payment_data['mapped_order_id'])
|
|
117
|
+
print(f"Payment status: {payment_response['status']}")
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Option 2 : Utilisation avec instance de classe
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
from arzeka import ArzekaPayment
|
|
124
|
+
|
|
125
|
+
# Utilisez le context manager pour gestion automatique
|
|
126
|
+
with ArzekaPayment() as client:
|
|
127
|
+
# 1. Authentification
|
|
128
|
+
auth = client.authenticate("your_username", "your_password")
|
|
129
|
+
|
|
130
|
+
# 2. Vérifiez la validité du token
|
|
131
|
+
if client.is_token_valid():
|
|
132
|
+
print("Token is valid")
|
|
133
|
+
|
|
134
|
+
# 3. Initiez un paiement
|
|
135
|
+
response = client.initiate_payment(
|
|
136
|
+
amount=1000,
|
|
137
|
+
merchant_id="MERCHANT_123",
|
|
138
|
+
additional_info={
|
|
139
|
+
"first_name": "Jean",
|
|
140
|
+
"last_name": "Dupont",
|
|
141
|
+
"mobile": "70123456"
|
|
142
|
+
},
|
|
143
|
+
mapped_order_id="eT20220923.203221.24732",
|
|
144
|
+
hash_secret="your_hash_secret",
|
|
145
|
+
link_for_update_status="https://example.com/webhook",
|
|
146
|
+
link_back_to_calling_website="https://example.com/return"
|
|
147
|
+
)
|
|
148
|
+
|
|
149
|
+
# 4. Vérifiez le statut
|
|
150
|
+
status = client.check_payment("eT20220923.203221.24732")
|
|
151
|
+
|
|
152
|
+
# Le client est automatiquement fermé
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## 📚 Exemples détaillés
|
|
156
|
+
|
|
157
|
+
### Authentification et gestion des tokens
|
|
158
|
+
|
|
159
|
+
```python
|
|
160
|
+
from arzeka import ArzekaPayment
|
|
161
|
+
|
|
162
|
+
client = ArzekaPayment()
|
|
163
|
+
|
|
164
|
+
# Authentification
|
|
165
|
+
auth = client.authenticate("username", "password")
|
|
166
|
+
print(f"Access Token: {auth['access_token']}")
|
|
167
|
+
print(f"Token Type: {auth['token_type']}")
|
|
168
|
+
print(f"Expires In: {auth['expires_in']} seconds")
|
|
169
|
+
|
|
170
|
+
# Vérifier la validité du token
|
|
171
|
+
if client.is_token_valid():
|
|
172
|
+
print("Token is still valid")
|
|
173
|
+
else:
|
|
174
|
+
print("Token has expired")
|
|
175
|
+
|
|
176
|
+
# Obtenir des informations détaillées sur le token
|
|
177
|
+
info = client.get_token_expiry_info()
|
|
178
|
+
print(f"Expires in {info['expires_in_minutes']:.1f} minutes")
|
|
179
|
+
print(f"Is expired: {info['is_expired']}")
|
|
180
|
+
|
|
181
|
+
client.close()
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### Réauthentification automatique
|
|
185
|
+
|
|
186
|
+
```python
|
|
187
|
+
from arzeka import ArzekaPayment
|
|
188
|
+
|
|
189
|
+
client = ArzekaPayment()
|
|
190
|
+
client.authenticate("username", "password")
|
|
191
|
+
|
|
192
|
+
# Faites plusieurs requêtes sur une longue période
|
|
193
|
+
# La réauthentification est AUTOMATIQUE si le token expire
|
|
194
|
+
|
|
195
|
+
for i in range(10):
|
|
196
|
+
# Pas besoin de vérifier la validité du token !
|
|
197
|
+
# Le client se réauthentifie automatiquement si nécessaire
|
|
198
|
+
response = client.initiate_payment(
|
|
199
|
+
amount=1000,
|
|
200
|
+
merchant_id="MERCHANT_123",
|
|
201
|
+
additional_info={...},
|
|
202
|
+
hash_secret="secret",
|
|
203
|
+
link_for_update_status="https://...",
|
|
204
|
+
link_back_to_calling_website="https://..."
|
|
205
|
+
)
|
|
206
|
+
print(f"Payment {i+1}: {response['mappedOrderId']}")
|
|
207
|
+
|
|
208
|
+
client.close()
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
### Initialisation de paiement avec reçu
|
|
212
|
+
|
|
213
|
+
```python
|
|
214
|
+
from arzeka import initiate_payment, authenticate
|
|
215
|
+
|
|
216
|
+
# Authentifiez-vous d'abord
|
|
217
|
+
authenticate("username", "password")
|
|
218
|
+
|
|
219
|
+
# Paiement avec génération de reçu
|
|
220
|
+
payment_data = {
|
|
221
|
+
"amount": 5000,
|
|
222
|
+
"merchant_id": "MERCHANT_123",
|
|
223
|
+
"additional_info": {
|
|
224
|
+
"first_name": "Marie",
|
|
225
|
+
"last_name": "Kaboré",
|
|
226
|
+
"mobile": "70987654",
|
|
227
|
+
"generateReceipt": True, # Activer la génération de reçu
|
|
228
|
+
"paymentDescription": "Facture N°12345",
|
|
229
|
+
"accountingOffice": "Bureau Principal",
|
|
230
|
+
"accountantName": "Jean Traoré",
|
|
231
|
+
"address": "Ouagadougou, Burkina Faso"
|
|
232
|
+
},
|
|
233
|
+
"hash_secret": "your_secret",
|
|
234
|
+
"link_for_update_status": "https://example.com/webhook",
|
|
235
|
+
"link_back_to_calling_website": "https://example.com/return",
|
|
236
|
+
"mapped_order_id": "ORDER-2025-001" # ID personnalisé
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
response = initiate_payment(payment_data)
|
|
240
|
+
print(f"Payment URL: {response.get('payment_url')}")
|
|
241
|
+
print(f"Order ID: {response.get('mappedOrderId')}")
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
### Vérification de paiement
|
|
245
|
+
|
|
246
|
+
```python
|
|
247
|
+
from arzeka import check_payment, authenticate
|
|
248
|
+
|
|
249
|
+
authenticate("username", "password")
|
|
250
|
+
|
|
251
|
+
# Vérification simple
|
|
252
|
+
status = check_payment("ORDER-2025-001")
|
|
253
|
+
print(f"Status: {status}")
|
|
254
|
+
|
|
255
|
+
# Vérification avec transaction ID
|
|
256
|
+
status = check_payment(
|
|
257
|
+
mapped_order_id="ORDER-2025-001",
|
|
258
|
+
transaction_id="TXN-12345"
|
|
259
|
+
)
|
|
260
|
+
print(f"Transaction Status: {status}")
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### Utilisation des fonctions utilitaires
|
|
264
|
+
|
|
265
|
+
```python
|
|
266
|
+
from arzeka import get_reference, format_msisdn, validate_phone_number
|
|
267
|
+
|
|
268
|
+
# Générer un ID de référence unique
|
|
269
|
+
ref = get_reference()
|
|
270
|
+
print(f"Reference: {ref}") # Ex: REF-20251023-123456
|
|
271
|
+
|
|
272
|
+
# Formater un numéro de téléphone
|
|
273
|
+
msisdn = format_msisdn("70 12 34 56")
|
|
274
|
+
print(f"Formatted: {msisdn}") # 22670123456
|
|
275
|
+
|
|
276
|
+
# Valider un numéro burkinabè
|
|
277
|
+
is_valid = validate_phone_number("70123456")
|
|
278
|
+
print(f"Valid: {is_valid}") # True
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
## 🔒 Gestion des erreurs
|
|
282
|
+
|
|
283
|
+
Le client fournit des exceptions spécifiques pour différents types d'erreurs :
|
|
284
|
+
|
|
285
|
+
```python
|
|
286
|
+
from arzeka import ArzekaPayment
|
|
287
|
+
|
|
288
|
+
from exceptions import (
|
|
289
|
+
ArzekaPaymentError,
|
|
290
|
+
ArzekaConnectionError,
|
|
291
|
+
ArzekaValidationError,
|
|
292
|
+
ArzekaAPIError,
|
|
293
|
+
ArzekaAuthenticationError
|
|
294
|
+
)
|
|
295
|
+
|
|
296
|
+
client = ArzekaPayment()
|
|
297
|
+
|
|
298
|
+
try:
|
|
299
|
+
# Tentative d'authentification
|
|
300
|
+
client.authenticate("username", "password")
|
|
301
|
+
|
|
302
|
+
# Tentative de paiement
|
|
303
|
+
response = client.initiate_payment(
|
|
304
|
+
amount=1000,
|
|
305
|
+
merchant_id="MERCHANT_123",
|
|
306
|
+
additional_info={...},
|
|
307
|
+
hash_secret="secret",
|
|
308
|
+
link_for_update_status="https://...",
|
|
309
|
+
link_back_to_calling_website="https://..."
|
|
310
|
+
)
|
|
311
|
+
|
|
312
|
+
except ArzekaAuthenticationError as e:
|
|
313
|
+
print(f"Authentication failed: {e}")
|
|
314
|
+
|
|
315
|
+
except ArzekaValidationError as e:
|
|
316
|
+
print(f"Invalid data: {e}")
|
|
317
|
+
|
|
318
|
+
except ArzekaConnectionError as e:
|
|
319
|
+
print(f"Connection error: {e}")
|
|
320
|
+
|
|
321
|
+
except ArzekaAPIError as e:
|
|
322
|
+
print(f"API error: {e}")
|
|
323
|
+
print(f"Status code: {e.status_code}")
|
|
324
|
+
print(f"Response: {e.response_data}")
|
|
325
|
+
|
|
326
|
+
except ArzekaPaymentError as e:
|
|
327
|
+
print(f"General error: {e}")
|
|
328
|
+
|
|
329
|
+
finally:
|
|
330
|
+
client.close()
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
## ⚙️ Configuration
|
|
334
|
+
|
|
335
|
+
### Variables d'environnement (recommandé)
|
|
336
|
+
|
|
337
|
+
```bash
|
|
338
|
+
# .env
|
|
339
|
+
ARZEKA_USERNAME=your_username
|
|
340
|
+
ARZEKA_PASSWORD=your_password
|
|
341
|
+
ARZEKA_MERCHANT_ID=MERCHANT_123
|
|
342
|
+
ARZEKA_HASH_SECRET=your_hash_secret
|
|
343
|
+
ARZEKA_BASE_URL=https://pwg-test.fasoarzeka.com/AvepayPaymentGatewayUI/avepay-payment/
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
```python
|
|
347
|
+
import os
|
|
348
|
+
from arzeka import ArzekaPayment
|
|
349
|
+
|
|
350
|
+
client = ArzekaPayment(
|
|
351
|
+
base_url=os.getenv('ARZEKA_BASE_URL'),
|
|
352
|
+
timeout=30
|
|
353
|
+
)
|
|
354
|
+
|
|
355
|
+
client.authenticate(
|
|
356
|
+
os.getenv('ARZEKA_USERNAME'),
|
|
357
|
+
os.getenv('ARZEKA_PASSWORD')
|
|
358
|
+
)
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
### Configuration du logging
|
|
362
|
+
|
|
363
|
+
```python
|
|
364
|
+
import logging
|
|
365
|
+
from arzeka import ArzekaPayment
|
|
366
|
+
|
|
367
|
+
# Configurer le niveau de log
|
|
368
|
+
logging.basicConfig(
|
|
369
|
+
level=logging.DEBUG,
|
|
370
|
+
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
|
|
371
|
+
)
|
|
372
|
+
|
|
373
|
+
client = ArzekaPayment()
|
|
374
|
+
# Les logs détaillés seront affichés
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
## 🧪 Tests
|
|
378
|
+
|
|
379
|
+
Le projet inclut des tests unitaires complets :
|
|
380
|
+
|
|
381
|
+
```bash
|
|
382
|
+
# Exécuter tous les tests
|
|
383
|
+
python -m pytest test/
|
|
384
|
+
|
|
385
|
+
# Exécuter avec couverture
|
|
386
|
+
python -m pytest test/ --cov=arzeka --cov-report=html
|
|
387
|
+
|
|
388
|
+
# Exécuter un test spécifique
|
|
389
|
+
python -m pytest test/test.py::TestArzekaPayment::test_authenticate
|
|
390
|
+
|
|
391
|
+
# Mode verbose
|
|
392
|
+
python -m pytest test/ -v
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
## 📖 Documentation complète
|
|
396
|
+
|
|
397
|
+
### Documentation style ReadTheDocs
|
|
398
|
+
|
|
399
|
+
**📚 Documentation HTML complète disponible dans `docs_sphinx/`**
|
|
400
|
+
|
|
401
|
+
Pour générer et consulter la documentation :
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
cd docs_sphinx
|
|
405
|
+
pip install -r requirements.txt
|
|
406
|
+
./build.sh
|
|
407
|
+
# Puis ouvrez _build/html/index.html dans votre navigateur
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
La documentation comprend :
|
|
411
|
+
- Guide d'installation détaillé
|
|
412
|
+
- Guide de démarrage rapide
|
|
413
|
+
- Guide d'authentification complet
|
|
414
|
+
- Référence API complète avec autodoc
|
|
415
|
+
- Exemples de code annotés
|
|
416
|
+
- Guide de gestion d'erreurs
|
|
417
|
+
- Fonctionnalités avancées
|
|
418
|
+
- Guide de contribution
|
|
419
|
+
|
|
420
|
+
### Guides Markdown
|
|
421
|
+
|
|
422
|
+
- **[Guide de démarrage rapide](docs/QUICKSTART.md)** - Commencer en 5 minutes
|
|
423
|
+
- **[Guide d'authentification](docs/AUTHENTICATION.md)** - Tout sur l'authentification
|
|
424
|
+
- **[Validation des tokens](docs/TOKEN_VALIDATION.md)** - Gestion des tokens
|
|
425
|
+
- **[Réauthentification automatique](docs/AUTO_REAUTH.md)** - Fonctionnalité avancée
|
|
426
|
+
|
|
427
|
+
### Exemples de code
|
|
428
|
+
|
|
429
|
+
- **[Exemples pratiques](examples/)** - Code exécutable
|
|
430
|
+
- `authentication_example.py` - Exemples d'authentification
|
|
431
|
+
- `token_validation_example.py` - Validation de tokens
|
|
432
|
+
- `shared_client_example.py` - Instance partagée
|
|
433
|
+
- `auto_reauth_example.py` - Réauthentification automatique
|
|
434
|
+
|
|
435
|
+
## 🏗️ Architecture
|
|
436
|
+
|
|
437
|
+
```
|
|
438
|
+
arzeka-payment/
|
|
439
|
+
├── arzeka.py # Module principal
|
|
440
|
+
├── utils.py # Fonctions utilitaires
|
|
441
|
+
├── __init__.py # Exports publics
|
|
442
|
+
├── requirements.txt # Dépendances
|
|
443
|
+
├── setup.py # Configuration d'installation
|
|
444
|
+
├── pyproject.toml # Configuration Poetry
|
|
445
|
+
├── docs/ # Documentation
|
|
446
|
+
│ ├── QUICKSTART.md
|
|
447
|
+
│ ├── AUTHENTICATION.md
|
|
448
|
+
│ └── TOKEN_VALIDATION.md
|
|
449
|
+
├── examples/ # Exemples de code
|
|
450
|
+
│ ├── authentication_example.py
|
|
451
|
+
│ ├── token_validation_example.py
|
|
452
|
+
│ ├── shared_client_example.py
|
|
453
|
+
│ └── auto_reauth_example.py
|
|
454
|
+
└── test/ # Tests unitaires
|
|
455
|
+
└── test.py
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
## 🔧 Classes et Exceptions
|
|
459
|
+
|
|
460
|
+
### Classes principales
|
|
461
|
+
|
|
462
|
+
- **`ArzekaPayment`** - Client principal pour interactions API
|
|
463
|
+
- **`BasePayment`** - Classe de base avec gestion session et requêtes
|
|
464
|
+
|
|
465
|
+
### Exceptions personnalisées
|
|
466
|
+
|
|
467
|
+
- **`ArzekaPaymentError`** - Exception de base
|
|
468
|
+
- **`ArzekaConnectionError`** - Erreurs de connexion réseau
|
|
469
|
+
- **`ArzekaValidationError`** - Erreurs de validation de données
|
|
470
|
+
- **`ArzekaAPIError`** - Erreurs retournées par l'API
|
|
471
|
+
- **`ArzekaAuthenticationError`** - Erreurs d'authentification
|
|
472
|
+
|
|
473
|
+
## 🚀 Fonctionnalités avancées
|
|
474
|
+
|
|
475
|
+
### 1. Retry automatique avec backoff exponentiel
|
|
476
|
+
|
|
477
|
+
```python
|
|
478
|
+
# Le client réessaie automatiquement en cas d'erreur réseau
|
|
479
|
+
# - Maximum 3 tentatives
|
|
480
|
+
# - Backoff exponentiel (1s, 2s, 4s)
|
|
481
|
+
# - Status codes: 429, 500, 502, 503, 504
|
|
482
|
+
client = ArzekaPayment()
|
|
483
|
+
# Les retries sont automatiques !
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
### 2. Session persistante avec connection pooling
|
|
487
|
+
|
|
488
|
+
```python
|
|
489
|
+
# Les connexions HTTP sont réutilisées pour meilleures performances
|
|
490
|
+
client = ArzekaPayment()
|
|
491
|
+
# La session est automatiquement gérée
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
### 3. Context manager
|
|
495
|
+
|
|
496
|
+
```python
|
|
497
|
+
# Gestion automatique des ressources
|
|
498
|
+
with ArzekaPayment() as client:
|
|
499
|
+
client.authenticate("user", "pass")
|
|
500
|
+
response = client.initiate_payment(...)
|
|
501
|
+
# Fermeture automatique de la session
|
|
502
|
+
```
|
|
503
|
+
|
|
504
|
+
### 4. Instance partagée pour fonctions de convenance
|
|
505
|
+
|
|
506
|
+
```python
|
|
507
|
+
from arzeka import authenticate, initiate_payment, get_shared_client, close_shared_client
|
|
508
|
+
|
|
509
|
+
# Les fonctions partagent une même instance
|
|
510
|
+
authenticate("user", "pass")
|
|
511
|
+
initiate_payment(payment_data)
|
|
512
|
+
|
|
513
|
+
# Accéder à l'instance partagée
|
|
514
|
+
client = get_shared_client()
|
|
515
|
+
print(client.is_token_valid())
|
|
516
|
+
|
|
517
|
+
# Nettoyer l'instance partagée
|
|
518
|
+
close_shared_client()
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
## 💡 Bonnes pratiques
|
|
522
|
+
|
|
523
|
+
### 1. Utiliser les variables d'environnement
|
|
524
|
+
|
|
525
|
+
```python
|
|
526
|
+
import os
|
|
527
|
+
from arzeka import authenticate
|
|
528
|
+
|
|
529
|
+
username = os.getenv('ARZEKA_USERNAME')
|
|
530
|
+
password = os.getenv('ARZEKA_PASSWORD')
|
|
531
|
+
authenticate(username, password)
|
|
532
|
+
```
|
|
533
|
+
|
|
534
|
+
### 2. Utiliser le context manager
|
|
535
|
+
|
|
536
|
+
```python
|
|
537
|
+
with ArzekaPayment() as client:
|
|
538
|
+
client.authenticate("user", "pass")
|
|
539
|
+
# ... opérations ...
|
|
540
|
+
# Nettoyage automatique
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
### 3. Gérer les exceptions spécifiques
|
|
544
|
+
|
|
545
|
+
```python
|
|
546
|
+
try:
|
|
547
|
+
response = client.initiate_payment(...)
|
|
548
|
+
except ArzekaValidationError:
|
|
549
|
+
# Données invalides
|
|
550
|
+
except ArzekaAuthenticationError:
|
|
551
|
+
# Problème d'authentification
|
|
552
|
+
except ArzekaConnectionError:
|
|
553
|
+
# Problème réseau
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
### 4. Vérifier les tokens avant longues opérations
|
|
557
|
+
|
|
558
|
+
```python
|
|
559
|
+
if client.is_token_valid(margin_seconds=300): # 5 minutes
|
|
560
|
+
# Token valide pour au moins 5 minutes
|
|
561
|
+
long_operation()
|
|
562
|
+
```
|
|
563
|
+
|
|
564
|
+
### 5. Utiliser le logging pour debug
|
|
565
|
+
|
|
566
|
+
```python
|
|
567
|
+
import logging
|
|
568
|
+
logging.basicConfig(level=logging.DEBUG)
|
|
569
|
+
# Logs détaillés des requêtes
|
|
570
|
+
```
|
|
571
|
+
|
|
572
|
+
## 🔍 API Reference
|
|
573
|
+
|
|
574
|
+
### ArzekaPayment
|
|
575
|
+
|
|
576
|
+
```python
|
|
577
|
+
class ArzekaPayment(base_url: str = BASE_URL, timeout: int = 30)
|
|
578
|
+
```
|
|
579
|
+
|
|
580
|
+
#### Méthodes
|
|
581
|
+
|
|
582
|
+
- **`authenticate(username, password)`** - Authentification et obtention du token
|
|
583
|
+
- **`initiate_payment(...)`** - Initialiser un paiement
|
|
584
|
+
- **`check_payment(mapped_order_id, transaction_id)`** - Vérifier statut paiement
|
|
585
|
+
- **`is_token_valid(margin_seconds=60)`** - Vérifier validité du token
|
|
586
|
+
- **`get_token_expiry_info()`** - Obtenir infos détaillées sur expiration
|
|
587
|
+
- **`close()`** - Fermer la session
|
|
588
|
+
|
|
589
|
+
### Fonctions utilitaires
|
|
590
|
+
|
|
591
|
+
- **`get_reference()`** - Générer ID de référence unique
|
|
592
|
+
- **`format_msisdn(phone)`** - Formater numéro de téléphone
|
|
593
|
+
- **`validate_phone_number(phone)`** - Valider numéro burkinabè
|
|
594
|
+
|
|
595
|
+
### Fonctions de convenance
|
|
596
|
+
|
|
597
|
+
- **`authenticate(username, password, base_url, timeout)`** - Authentification
|
|
598
|
+
- **`initiate_payment(payment_data, base_url, timeout)`** - Initialiser paiement
|
|
599
|
+
- **`check_payment(mapped_order_id, transaction_id, base_url, timeout)`** - Vérifier paiement
|
|
600
|
+
- **`get_shared_client()`** - Obtenir instance partagée
|
|
601
|
+
- **`close_shared_client()`** - Fermer instance partagée
|
|
602
|
+
|
|
603
|
+
## 📊 Statut du projet
|
|
604
|
+
|
|
605
|
+
- ✅ Authentification sécurisée
|
|
606
|
+
- ✅ Initialisation de paiements
|
|
607
|
+
- ✅ Vérification de statut
|
|
608
|
+
- ✅ Gestion complète des erreurs
|
|
609
|
+
- ✅ Retry automatique
|
|
610
|
+
- ✅ Réauthentification automatique
|
|
611
|
+
- ✅ Tests unitaires (>90% couverture)
|
|
612
|
+
- ✅ Documentation complète
|
|
613
|
+
- ✅ Type hints complets
|
|
614
|
+
- ✅ Logging intégré
|
|
615
|
+
- ⏳ Publication sur PyPI (à venir)
|
|
616
|
+
|
|
617
|
+
## 🤝 Contribution
|
|
618
|
+
|
|
619
|
+
Les contributions sont les bienvenues ! Voici comment contribuer :
|
|
620
|
+
|
|
621
|
+
1. **Fork** le projet
|
|
622
|
+
2. **Créez** une branche pour votre fonctionnalité (`git checkout -b feature/AmazingFeature`)
|
|
623
|
+
3. **Committez** vos changements (`git commit -m 'Add some AmazingFeature'`)
|
|
624
|
+
4. **Pushez** vers la branche (`git push origin feature/AmazingFeature`)
|
|
625
|
+
5. **Ouvrez** une Pull Request
|
|
626
|
+
|
|
627
|
+
### Guidelines de contribution
|
|
628
|
+
|
|
629
|
+
- Suivre le style de code existant
|
|
630
|
+
- Ajouter des tests pour nouvelles fonctionnalités
|
|
631
|
+
- Mettre à jour la documentation
|
|
632
|
+
- S'assurer que tous les tests passent
|
|
633
|
+
|
|
634
|
+
## 📝 Changelog
|
|
635
|
+
|
|
636
|
+
Voir [CHANGELOG.md](CHANGELOG.md) pour l'historique détaillé des modifications.
|
|
637
|
+
|
|
638
|
+
## �📄 Licence
|
|
639
|
+
|
|
640
|
+
Ce projet est sous licence MIT. Voir le fichier [LICENSE](LICENSE) pour plus de détails.
|
|
641
|
+
|
|
642
|
+
## 👥 Auteur
|
|
643
|
+
|
|
644
|
+
**Mohamed Zeba** - [m.zeba@mzeba.dev](mailto:m.zeba@mzeba.dev)
|
|
645
|
+
|
|
646
|
+
## 🙏 Remerciements
|
|
647
|
+
|
|
648
|
+
- L'équipe Arzeka pour l'API
|
|
649
|
+
- La communauté Python du Burkina Faso
|
|
650
|
+
- Tous les contributeurs
|
|
651
|
+
|
|
652
|
+
## 📞 Support
|
|
653
|
+
|
|
654
|
+
- **Issues** : [GitHub Issues](https://github.com/parice02/fasoarzeka/issues)
|
|
655
|
+
- **Email** : m.zeba@mzeba.dev
|
|
656
|
+
- **Documentation** : [GitHub Wiki](https://github.com/parice02/fasoarzeka/wiki)
|
|
657
|
+
|
|
658
|
+
## ⚠️ Avertissement
|
|
659
|
+
|
|
660
|
+
Ceci est un client **non officiel** pour l'API Arzeka. Utilisez-le à vos propres risques.
|
|
661
|
+
Assurez-vous de respecter les conditions d'utilisation de l'API Arzeka.
|
|
662
|
+
|
|
663
|
+
## 🌟 Soutenez le projet
|
|
664
|
+
|
|
665
|
+
Si ce projet vous aide, n'oubliez pas de lui donner une ⭐ sur GitHub !
|
|
666
|
+
|
|
667
|
+
---
|
|
668
|
+
|
|
669
|
+
**Note importante** : Ce client utilise l'environnement de test par défaut.
|
|
670
|
+
Pour la production, assurez-vous de configurer l'URL de production :
|
|
671
|
+
|
|
672
|
+
```python
|
|
673
|
+
from arzeka import ArzekaPayment
|
|
674
|
+
|
|
675
|
+
client = ArzekaPayment(base_url="https://pwg.fasoarzeka.com/...")
|
|
676
|
+
```
|