Intégration SFN / DGI

Lien isolé Accueil docs Formation
Modules métier

Facturation normalisée électronique conforme DGI RDC.

image.png# Intégration SFN DGI (Factures normalisées)

Ce document décrit le module SFN actuel (simulation) et comment brancher le SFN réel de la DGI une fois la validation obtenue.

Conformité des factures DGI

Les factures imprimées (web et POS mobile) sont conformes au format attendu par la DGI lorsque le module SFN est utilisé :

  • En-tête : nom de la boutique, adresse, RCCM, NIF, téléphone, email.
  • Corps : titre « FACTURE », numéro, date, caissier, client (si applicable), lignes (désignation, quantité × prix, total), sous-total, remise, TVA, TOTAL.
  • Bloc DGI/SFN : code fiscal (affiché lorsque la facture a été transmise et acceptée) et QR code (payload fourni par le SFN/DGI).
  • Paiement : montant payé, rendu, mode de paiement.
  • Pied de page : message de remerciement, date, nom boutique.

Sur web : les vues receipt-thermal.blade.php et receipt.blade.php reçoivent le code fiscal et l’URL du QR depuis la facture SFN acceptée liée à la vente.
Sur POS mobile : l’API /pos/sales/{id}/receipt renvoie fiscal_code et qr_payload lorsque la vente a une facture SFN acceptée ; le reçu généré (HTML) affiche alors le code fiscal et le QR. Les ventes hors ligne n’ont pas encore de facture SFN ; le reçu affiche « QR DGI (SFN) — à intégrer » jusqu’à synchronisation et émission SFN.


1. Ce qui est en place (simulation)

Création des factures SFN à partir des ventes

  • À la finalisation d’une vente (POS ou API)
    Si la feature sfn.core est activée pour la boutique, une facture SFN en statut brouillon est créée automatiquement et liée à la vente (source_type = Sale, source_id = id de la vente).

  • Depuis la fiche vente
    Pour les ventes déjà enregistrées avant l’activation du module SFN, un bouton « Générer facture SFN » permet de créer une facture SFN (brouillon) à partir de cette vente, si aucune facture SFN n’existe déjà pour elle.

Données enregistrées

  • Numéro interne : INV-{référence vente} (ex. INV-SAL-XXXXXXXX).
  • Payload (snapshot fiscal, dans payload_json) : date d’émission, référence vente, lignes (produit, quantité, prix unitaire, total), sous-total, remise, total, canal de distribution, méthode de paiement.
  • Client : hash anonymisé (client_hash) pour conformité (pas de données personnelles dans le payload envoyé au SFN).

Flux utilisateur (simulation)

  1. Vente finalisée → facture SFN en brouillon créée.
  2. Menu SFN / Factures normalisées → liste des factures (avec colonne N° / Vente).
  3. Détails → voir la facture, puis « Verrouiller et envoyer ».
  4. La facture passe en queued ; un job en file d’attente appelle le provider SFN.
  5. Avec le provider actuel (NullSfnProvider, sandbox), l’envoi est simulé : pas d’appel DGI, un code fiscal et un payload QR factices sont enregistrés, statut accepted.
  6. Imprimer : vue d’impression avec code fiscal et QR (simulés).
  7. Archiver : possible une fois la facture acceptée.

Ce qui ne manque pas pour la simulation

  • Création automatique depuis les ventes (POS + service API).
  • Création manuelle depuis une vente existante (bouton sur la fiche vente).
  • Liste, détail, verrouillage, envoi (job), impression, archivage.
  • Provider de simulation (NullSfnProvider) qui renvoie succès + code fiscal + QR sans appeler la DGI.

Vous pouvez donc valider tout le parcours métier (vente → facture SFN → envoi simulé → impression → archivage) avant de brancher la DGI.


2. Intégrer le SFN réel de la DGI

Une fois que vous avez validé la simulation et obtenu l’accord / les spécifications de la DGI :

Étape 1 : Créer un provider DGI

  1. Créer une classe qui implémente l’interface App\Services\Sfn\SfnProvider :
<?php

namespace App\Services\Sfn;

use App\Models\SfnInvoice;

class DgiSfnProvider implements SfnProvider
{
    public function name(): string
    {
        return 'dgi';
    }

    public function submit(SfnInvoice $invoice): SfnSubmitResult
    {
        // 1. Mapper $invoice->payload_json (et éventuellement $invoice, $invoice->source)
        //    vers le format attendu par l’API DGI (selon leur documentation).
        // 2. Appeler l’API DGI (HTTP client : Guzzle, Http::post, etc.).
        // 3. Lire la réponse : code fiscal, payload QR, ou erreur.
        // 4. Retourner SfnSubmitResult::ok($fiscalCode, $qrPayload, $request, $response)
        //    ou SfnSubmitResult::fail($message, $request, $response).
    }
}
  1. Utiliser la documentation et le contrat d’API fournis par la DGI pour :

    • l’URL d’appel (production / préproduction),
    • l’authentification (token, certificat, etc.),
    • le format de la requête (JSON, champs obligatoires),
    • le format de la réponse (code fiscal, QR, codes d’erreur).
  2. Les données utiles sont dans :

    • $invoice->payload_json : snapshot de la vente (lignes, totaux, date, etc.),
    • $invoice->invoice_number, $invoice->uuid, $invoice->client_hash,
    • $invoice->source (relation morph) : la vente d’origine si besoin de champs supplémentaires.

Étape 2 : Enregistrer le provider

Dans App\Providers\AppServiceProvider, remplacer le binding du provider SFN par le provider DGI lorsque vous souhaitez utiliser la DGI (par exemple via une variable d’environnement) :

// Dans AppServiceProvider::register()

if (config('services.sfn.provider') === 'dgi') {
    $this->app->bind(SfnProvider::class, DgiSfnProvider::class);
} else {
    $this->app->bind(SfnProvider::class, NullSfnProvider::class);
}

Étape 3 : Configuration

Ajouter dans config/services.php (ou dans .env) :

'sfn' => [
    'provider' => env('SFN_PROVIDER', 'null'), // 'null' | 'dgi'
    // Optionnel : URL et clés pour la DGI
    'dgi' => [
        'base_url' => env('DGI_SFN_BASE_URL'),
        'api_key'  => env('DGI_SFN_API_KEY'),
        // ...
    ],
],

Dans .env (à ne pas commiter en clair en production) :

SFN_PROVIDER=null
# Pour la DGI (une fois prêt) :
# SFN_PROVIDER=dgi
# DGI_SFN_BASE_URL=https://...
# DGI_SFN_API_KEY=...

Étape 4 : Adapter le payload si la DGI exige un format précis

Le payload actuel (SfnInvoiceFromSaleService::buildPayload) est volontairement générique. Si la DGI impose un schéma précis (noms de champs, structure des lignes, etc.) :

  • soit vous adaptez buildPayload pour produire directement le format DGI,
  • soit vous gardez le payload actuel et vous faites la transformation dans DgiSfnProvider::submit() avant l’envoi (recommandé pour garder une trace identique en simulation et en DGI).

Résumé

Élément Rôle
SfnProvider (interface) Contrat : submit(SfnInvoice): SfnSubmitResult
NullSfnProvider Simulation : pas d’appel réseau, retour succès + code/QR factices
DgiSfnProvider (à créer) Appel API DGI, mapping payload → format DGI, retour SfnSubmitResult
AppServiceProvider Choisir le provider selon config('services.sfn.provider')
SendSfnInvoiceJob Appelle SfnProvider::submit() ; inchangé après intégration DGI

Une fois DgiSfnProvider créé et enregistré (avec SFN_PROVIDER=dgi), le même flux (Verrouiller et envoyer → job → impression → archivage) utilisera l’API DGI réelle au lieu de la simulation.