bceao-pispi-qrcode 1.0.2

Pyhton SDK pour générer et décoder des QR Codes PI-SPI conformes EMV.

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 :

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

2️⃣ Importer la bibliothèque

from bceao_pispi_qrcode import *

3️⃣ Générer un payload QR

    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 • 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 • 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

    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

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

    is_valid = PispiQrPayload.isValidAlias(
        '111c3e1b-4312-49ec-b75e-4c8c74c10fd7'
    )

---

Exemple

---

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 : [e-mail]

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