Metadata-Version: 2.4
Name: bceao-pispi-qrcode
Version: 1.0.2
Summary: Pyhton SDK pour générer et décoder des QR Codes PI-SPI conformes EMV.
Home-page: https://github.com/pi-spi/qrcode-python.git
Author: BCEAO PI-SPI
Author-email: BCEAO PI-SPI <piz@bceao.int>
License: MIT
Keywords: bceao,pispi,pi-spi,pi,spi,qr,emv,uemoa,payment
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: segno>=1.5.0
Requires-Dist: qrcode[pil]>=7.4.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# BCEAO PI-SPI QR Code Python Module

Le package Phyton `bceao_pispi_qrcode` fournit une interface robuste, sécurisée et conforme aux standards EMV pour intégrer les QR Codes PI-SPI, permettant aux applications python d'interagir avec l'écosystème PI-SPI de la BCEAO.

---

## Structure du projet

```
└── 📁bceao-pispi-qrcode
    └── 📁bceao_pispi_qrcode
        └── 📁assets
            ├── __init__.py
            ├── ic_qr.png
            ├── logo_spi_dark.png
            ├── logo_spi_light.png
            ├── logo_spi.png
        └── 📁models
            ├── __init__.py
            ├── const.py
            ├── enums.py
            ├── exceptions.py
            ├── models.py
        ├── __init__.py
        ├── pispi_qr_generator.py
        ├── pispi_qr_payload.py
    └── 📁example
        ├── example.py
    └── 📁tests
        ├── __init__.py
        ├── test_generator.py
        ├── test_payload.py
    ├── .env
    ├── .gitignore
    ├── CHANGELOG.md
    ├── DEPLOIEMENT.md
    ├── LICENSE
    ├── MANIFEST.in
    ├── pyproject.toml
    ├── pyrightconfig.json
    ├── README.md
    ├── setup.cfg
    ├── setup.py
    └── TEST.md
```

## Fonctionnalités principales

- Génération de QR Codes **statiques** et **dynamiques**.
- Construction de payloads **conformes EMV**.
- Décodage et vérification des payloads QR.
- Calcul automatique du **CRC16** pour l'intégrité des données.
- Validation des **alias (UUID v4)** pour la sécurité des comptes.
- Gestion complète des **exceptions** avec codes d'erreur structurés.
- Génération de QR Codes en **SVG** pour export ou impression.

Ce package est conçu pour les systèmes de paiement dans les pays de l'UEMOA.

---

## Intégration

### 1️⃣ Installation

Dans le dossier racine :

```sh
pip install build
python -m build
pip install bceao-pispi-qrcode
```


2️⃣ Importer la bibliothèque
```py
from bceao_pispi_qrcode import *
```

3️⃣ Générer un payload QR
```py
    input_data = PispiQrPayloadInput(
        qr_type= PispiQrType.STATIC,              # QR Code dynamique
        alias= '111c3e1b-4312-49ec-b75e-4c8c74c10fd7', # Alias du compte (UUID v4)
        country_code= PispiQrCountry.CI,               # Code pays
        amount= 5000,                             # Montant de la transaction (optionnel)
        reference_label= 'TX000000001',            # Label de référence (optionnel pour statique, obligatoire pour dynamique)
    )
    payload = PispiQrPayload.encode(input_data)
```
### PispiQrPayloadInput
| Champ               | Type               | Valeurs possibles                                                                                                                            | Contrainte    | Description                          |
| ------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------ |
| **qr_type**          | `PispiQrType`      | • `STATIC`<br>• `DYNAMIC`                                                                                                                    | ✅ Obligatoire | Type de QR Code à générer            |
| **alias**           | `str` (UUID v4) | Format UUID v4                                                                                                                               | ✅ Obligatoire | Alias du compte PI-SPI               |
| **country_code**         | `PispiQrCountry`   | • `BJ` • `BF` • `CI` • `GW`<br>• `ML` • `NE` • `SN` • `TG`                                                                                   | ✅ Obligatoire | Code pays ISO 3166-1 alpha-2         |
| **amount**          | `float`           | Valeur numérique                                                                                                                             | ⚪ Optionnel   | Montant de la transaction            |
| **reference_label**  | `str`           | Max. 25 caractères                                                                                                                           | ⚪ Optionnel   | Référence unique de transaction (ID) |



4️⃣ Générer un QR Code en SVG
```py
    svg_qr = PispiQrGenerator.svg(
        payload,
        size= 200,                  # Taille du QR
        logo_size= 40,           # Taille du logo PI-SPI
        background_color= 'white',
        dot_color= 'black',
        margin= 10,
    )
```
| Paramètre           | Type     | Défaut  | Description                 |
| ------------------- | -------- | ------- | --------------------------- |
| **payload**         | `str` | —       | Payload EMV à encoder       |
| **size**            | `float` | `200`   | Taille totale du QR         |
| **logo_size**      | `float` | `40`    | Taille du logo central      |
| **background_color** | `Optional[str]`  | `white` | Couleur de fond             |
| **dot_color**       | `str`  | `black` | Couleur des modules         |
| **margin**          | `float` | `10`    | Marge externe (quiet zone)  |

Vous pouvez ensuite l'afficher dans un widget SvgPicture

5️⃣ Décoder un payload QR
```py
result = PispiQrPayload.decode(payload)
print(result.to_dict())
print(result.alias)
print(result.amount)
```
### PispiQrPayloadDecodeResult
| Champ                          | Type                         |
| ------------------------------ | ---------------------------- |
| **qr_type**     | `PispiQrType`                     |
| **merchant_channel**               | `str`                     |
| **alias** | `str` |
| **country_code**       | `PispiQrCountry`                     |
| **amount**        | `Optionnel[float]`                     |
| **reference_label**                | `Optionnel[str]`                     |



6️⃣ Valider un alias
```py
    is_valid = PispiQrPayload.isValidAlias(
        '111c3e1b-4312-49ec-b75e-4c8c74c10fd7'
    )
```

---

## Exemple

---

```py
from bceao_pispi_qrcode.pispi_qr_payload import PispiQrPayload
from bceao_pispi_qrcode.pispi_qr_generator import PispiQrGenerator

from bceao_pispi_qrcode.models.enums import PispiQrCountry, PispiQrType
from bceao_pispi_qrcode.models.models import PispiQrPayloadInput


input = PispiQrPayloadInput(
    PispiQrType.DYNAMIC,
    "550e8400-e29b-41d4-a716-446655440000",
    PispiQrCountry.CI,
    amount=2000,
    reference_label= "Tx-caise1"
)

payload = PispiQrPayload.encode(input)

print("================ PAYLOAD ENCODÉ ==============")
print(payload)

decode = PispiQrPayload.decode(payload)
print("================ PAYLOAD DECODÉ ==============")
print(decode.to_dict())

svg = PispiQrGenerator.svg(payload,background_color='white')
print("================ PAYLOAD SVG STRING ==============")
print(svg)
```



Support

Pour toute question, problème ou contribution :

Email : piz@bceao.int

GitHub : [https://github.com/pi-spi/qrcode-python.git]
