Download the PHP package banelsems/lara-sgmef-qr without Composer

LaraSgmefQR

Package Laravel pour intégrer l'API e-MECeF / SyGM-eMCF de la Direction Générale des Impôts du Bénin.

LaraSgmefQR v4.0.0 fournit un client API, des DTOs, une interface web, des jobs Laravel et des outils de conformité pour créer, confirmer, annuler, vérifier, exporter et documenter des factures e-MECeF.

Fonctionnalites v4

• Client API aligne sur les endpoints officiels DGI : groupes de taxe, types de facture, types de paiement, creation, lecture, confirmation et annulation de facture.
• Annulation alternative : POST /invoice/cancel (body-based) en plus du PUT /cancel existant.
• VerificationService : verification post-confirmation structuree (8 controles) avec URL de verification DGI.
• SgmefSecurityGuard : pre-validation JWT + rate limiting outgoing (configurable via SGMEF_RATE_LIMIT_PER_MINUTE).
• Types de facture FV, FA, EV, EA, avec reference obligatoire pour les avoirs FA/EA.
• Paiements officiels : ESPECES, VIREMENT, CARTEBANCAIRE, MOBILEMONEY, CHEQUES, CREDIT, AUTRE.
• Articles avec groupes de taxe A-F, taxe specifique taxSpecific, prix original originalPrice et modification priceModification.
• Validation locale : IFU a 13 chiffres, paiements egaux au total, coherence des avoirs et erreurs API errorCode/errorDesc.
• Support multi-IFU via IfuResolverInterface.
• Jobs Laravel pour creation, confirmation et expiration locale des factures en attente apres 2 minutes.
• Export STAT CSV et generation du dossier d'auto-declaration e-MECeF.
• Dashboard v4 : KPIs cliquables, graphique 30 jours, Top 5 clients, alertes visuelles (factures expirees, taux d'erreur API).
• Interface responsive : dark mode complet (auto-detection + toggle), sidebar mobile, notifications temps reel.
• Liste factures : tri par colonnes cliquables, filtres persistants dans l'URL, pagination avec query string.
• CI/CD : GitHub Actions (PHP 8.2/8.3/8.4 x Laravel 10/11/12, PHPStan level 8, PHP-CS-Fixer).

Installation

Publier les vues est optionnel :

Configuration

Ajoutez les variables utiles dans .env :

En production, protegez toujours l'interface web :

L'interface est disponible sur /sgmef par defaut :

• /sgmef : dashboard
• /sgmef/invoices : liste et filtres
• /sgmef/invoices/create : creation de facture
• /sgmef/invoices/{uid}/verify : verification post-confirmation
• /sgmef/config : configuration

Utilisation PHP

Creer et confirmer une facture de vente

Multi-paiement

Le total des paiements doit etre egal au total des lignes.

Types acceptes : ESPECES, VIREMENT, CARTEBANCAIRE, MOBILEMONEY, CHEQUES, CREDIT, AUTRE.

Avoir FA/EA avec reference obligatoire

Pour une facture d'avoir, reference doit contenir l'UID de la facture originale.

Taxe specifique et modification de prix

Multi-IFU

Par defaut, le package lit SGMEF_DEFAULT_IFU. Pour une application multi-etablissements, fournissez votre propre resolver :

Puis liez-le dans un service provider de l'application :

Vous pouvez ensuite injecter le resolver pour construire vos DTOs :

Jobs Laravel et API async

Le package fournit une API async additive via InvoiceQueueDispatcher qui dispatche des jobs sur la queue configuree. Les jobs appellent les memes services metier (InvoiceManager) que l'API synchrone — aucune logique metier n'est dupliquee.

Configuration

Dispatcher async (recommande)

Tous les dispatchs utilisent afterCommit() pour ne s'envoyer qu'apres commit de la transaction DB courante.

Jobs directs (bas niveau)

Securite des retries

Les jobs Create/Confirm/Cancel sont ShouldBeUnique pour eviter deux operations concurrentes sur la meme facture.

Expiration des factures pending

La commande sgmef:cleanup-expired marque les factures pending dont expires_at est depasse au statut EXPIRED (distinct d'ERROR).

Le scheduling est automatiquement enregistre par le ServiceProvider si SGMEF_CLEANUP_ENABLED=true (defaut). L'event InvoiceExpired est dispatche pour chaque facture expiree.

QR code PNG

QrCodeService::png() produit desormais de vrais PNG (signature \x89PNG). Necessite ext-gd. Sans ext-gd, une RuntimeException explicite est levee (png() ne retourne jamais silencieusement du SVG). Utilisez svg() pour un format vectoriel sans dependance.

Verification post-confirmation

Apres confirmation, verifiez l'integrite d'une facture via le VerificationService :

Le service verifie 8 controles : statut confirmed, UID present, QR code present et valide, code MECeF present, date/heure, counters, NIM.

Annulation alternative (POST)

En plus du PUT /cancel standard, une annulation alternative via POST /invoice/cancel est disponible :

Securite : rate limiting et pre-validation JWT

Le SgmefSecurityGuard valide le token JWT avant chaque appel API et limite le nombre de requetes sortantes par minute :

L'event SgmefAuthenticationAlert est dispatche sur les reponses 401/403. Ecoutez-le pour integrer un systeme d'alerte de securite :

Commandes

Generer un export STAT CSV :

Generer le dossier d'auto-declaration e-MECeF :

La configuration emecef_test_cases contient 20 cas de test DGI automatisables. Les appels reseau restent mockables dans les tests; les appels reels exigent un token et un IFU valides fournis par l'application hote.

Services utiles

Cycle de vie et statuts

Le modele Banelsems\LaraSgmefQr\Models\Invoice stocke les factures locales et l'audit API.

Statuts disponibles :

Champs importants :

• uid : UID retourne par l'API e-MECeF.
• ifu et customer_ifu : IFU emetteur/client.
• type : FV, FA, EV, EA.
• reference : facture originale pour FA/EA.
• security_elements, qr_code_data, mecf_code : elements de confirmation.
• error_code, error_description : erreurs locales ou API.
• expires_at : date limite locale de confirmation.

Gestion des erreurs

Les logs du client API evitent de persister les tokens et payloads complets. En production, gardez les logs applicatifs dans un canal protege.

Tests et qualite

Resultats actuels :

• 368 tests, 665 assertions — tous passants.
• PHPStan level 8 — 0 erreurs.
• composer validate — valide.
• CI/CD GitHub Actions — PHP 8.2/8.3/8.4 x Laravel 10/11/12.

Remarques :

• PHPUnit peut signaler No code coverage driver available si Xdebug/PCOV n'est pas installe.
• Les annotations @method sur le modele Invoice documentent les methodes magiques Eloquent pour PHPStan.

Compatibilite

• PHP ^8.1|^8.2|^8.3|^8.4
• Laravel ^10.0|^11.0|^12.0|^13.0
• Extensions PHP : curl, json, gd (optionnel, pour PNG QR codes)
• Base de donnees compatible Laravel migrations

Ressources

• Repository : https://github.com/Banelsems/laraSgmefQR
• Issues : https://github.com/Banelsems/laraSgmefQR/issues
• API developpeur DGI : https://developper.impots.bj/sygmef-emcf/swagger/v1/swagger.json
• Portail e-MECeF : https://e-mecef.impots.bj/

Licence

MIT. Voir LICENSE.