Créer ou utiliser un avoir

Les avoirs corrigent une facture émise sans modifier son historique fiscal figé. Invoice prend en charge les avoirs totaux et partiels via des services PHP, puis enregistre le résultat dans la même chaîne de conformité Factur-X.

Consultez d’abord Avoirs pour le modèle comptable et Données de facture pour le contrat d’instantané immuable.

Préconditions communes

Il faut :

• l’entité facture Sylius d’origine ;
• son ImmutableInvoiceSnapshot ;
• un numéro d’avoir unique géré par votre application ;
• une date d’émission qui n’est pas antérieure à la facture corrigée ;
• un rendu PDF de l’avoir servant de base visuelle à l’enregistrement Factur-X.

La facture source reste inchangée pendant toute l’opération.

Créer un avoir total

Injectez TotalCreditNoteFactory et construisez l’avoir électronique depuis l’instantané figé :

use DateTimeImmutable;
use SyliusInvoicePlugin\CreditNote\TotalCreditNoteFactory;

$creditNote = $totalCreditNoteFactory->create(
    $sourceSnapshot,
    'AV-2026-0001',
    new DateTimeImmutable('2026-08-21'),
);

$sourceSnapshot est l’instantané immuable de la facture corrigée. La factory rejette un numéro d’avoir vide et une date antérieure à celle de la facture source. Le résultat référence le numéro/la date d’origine et reprend les lignes, taxes et totaux figés sans modifier l’instantané source.

Un avoir total est la primitive Invoice adaptée à une contrepassation commerciale complète. Voir Annuler une facture.

Créer un avoir partiel

Injectez PartialCreditNoteService et sélectionnez les lignes source par index de ligne commençant à zéro et par quantité :

use DateTimeImmutable;
use SyliusInvoicePlugin\CreditNote\PartialCreditNoteLineSelection;
use SyliusInvoicePlugin\CreditNote\PartialCreditNoteService;

$creditNote = $partialCreditNoteService->create(
    $sourceSnapshot,
    'AV-2026-0002',
    new DateTimeImmutable('2026-08-21'),
    [
        new PartialCreditNoteLineSelection(lineIndex: 1, quantity: 1),
    ],
);

Le service exécute transactionnellement la réservation des quantités et l’enregistrement des allocations. Il recalcule les quantités, remises et taxes sélectionnées depuis les données source figées.

Il rejette :

• une liste de sélection vide ;
• un index de ligne négatif ;
• une quantité inférieure ou égale à zéro ;
• un index de ligne absent de l’instantané source ;
• une quantité supérieure au reliquat encore créditable sur la ligne ;
• les allocations d’avoir en doublon qui violent l’unicité source/numéro/ligne.

Enregistrer l’avoir comme document de conformité

Après génération du PDF de l’avoir par votre application, enregistrez-le avec CreditNoteComplianceDocumentRegistrar :

use SyliusInvoicePlugin\CreditNote\CreditNoteComplianceDocumentRegistrar;

$document = $creditNoteRegistrar->register(
    $sourceInvoice,
    $creditNote,
    $creditNotePdfContent,
);

$sourceInvoice est l’entité facture Sylius d’origine et $creditNotePdfContent est le rendu PDF de l’avoir, pas un remplacement mutable du PDF de la facture d’origine.

L’enregistrement vérifie que le document électronique est bien un avoir et que sa référence à la facture corrigée correspond à la facture Sylius liée. Il :

1. génère le PDF Factur-X et le XML structuré ;
2. stocke leurs empreintes d’intégrité ;
3. valide le document électronique ;
4. persiste le document de conformité ;
5. déclenche la transmission uniquement lorsque le mode automatique est configuré.

L’enregistrement est déterministe pour la même facture source et le même numéro d’avoir. Réenregistrer un document complet correspondant le réutilise ; un document existant incomplet ou en échec d’intégrité est rejeté plutôt qu’écrasé silencieusement.

Résultat attendu

Une opération réussie représente explicitement les deux documents :

• la facture d’origine reste immuable et traçable ;
• l’avoir possède son propre numéro et sa propre date d’émission ;
• l’avoir référence la facture corrigée ;
• ses artefacts Factur-X/XML sont validés et gouvernés par les mêmes règles d’intégrité que les factures.

Utilisez Télécharger une facture pour récupérer les artefacts de conformité gouvernés depuis l’Admin une fois le document de conformité de l’avoir enregistré.