Importer les soldes initiaux des cartes cadeaux et des avoirs

Quand la caisse Apitail remplace votre ancien logiciel, vos clients ont encore en poche des cartes cadeaux et des avoirs qu'il a émis. L'import de soldes initiaux les crée dans Apitail, avec leur code et leur solde restant : la caisse les accepte ensuite comme une carte vendue ou un avoir émis dans Apitail.

Avant de commencer#

• Un import concerne un seul magasin, le Magasin d'émission, et un seul type : les cartes cadeaux, ou les avoirs. Préparez un fichier par magasin et par type.
• Le magasin doit avoir une règle de validité du même type : Règles des cartes cadeaux pour des cartes, Règles des avoirs pour des avoirs (voir Régler la validité). Elle doit couvrir la date d'émission de chaque carte : laissez son Début de validité de la règle (optionnel) vide, ou placez-le avant la carte la plus ancienne.
• Dans « Paramètres › Rôles », votre rôle doit accorder, sur Paramètres de caisse :
  • Consulter le détail, pour ouvrir la liste des imports et leur détail ;
  • Créer, pour importer un fichier, et pour télécharger le fichier source ou les anomalies d'un import enregistré.
• Selon votre rôle, seuls les magasins qui vous sont attribués sont proposés, et la liste n'affiche que leurs imports.

Préparer le fichier#

Le fichier est un CSV encodé en UTF-8, aux colonnes séparées par des points-virgules : dans votre tableur, choisissez l'enregistrement au format CSV UTF-8, avec le point-virgule comme séparateur. Partez du modèle : le bouton Télécharger le modèle, dans la fenêtre d'import (étape 4 ci-dessous), donne un fichier qui ne contient que la ligne d'en-tête.

La première ligne reprend les six en-têtes du modèle, dans cet ordre et sans les modifier. Ensuite, une ligne par carte ou par avoir :

Colonne	Contenu	Obligatoire
code	Le code de la carte ou de l'avoir, exactement comme il est imprimé ou lu au scanner. Lettres et chiffres seulement : ni espace, ni tiret, ni point	Oui
valeur_origine	Le montant de la carte à sa vente, ou de l'avoir à son émission, en euros : 50 ou 50,00	Oui
solde_disponible	Ce qui reste à utiliser. Il ne dépasse pas la valeur d'origine	Oui
date_emission	La date de vente de la carte ou d'émission de l'avoir : 15/03/2026 ou 2026-03-15	Oui
date_expiration	La date de fin de validité, au même format. Vide, elle est calculée d'après la règle du magasin	Non
external_id	Laissez cette colonne vide	Non

N'y mettez que les cartes et les avoirs encore utilisables : un solde à zéro ou une date de fin de validité passée sont refusés. Un fichier compte au plus 20 000 lignes et 10 Mo : au-delà, découpez-le en plusieurs imports.

Importer#

1. Ouvrez « Points de vente › Paramètres », puis Imports de soldes initiaux (les autres vignettes de cet écran sont décrites dans Paramétrer la caisse). Cliquez sur Nouveau, en haut à droite.

2. Dans la fenêtre Nouvel import, cliquez sur Cartes cadeaux ou sur Avoirs.

3. Sous Général, choisissez le Magasin d'émission : celui où les cartes ont été vendues, ou les avoirs émis. Sa règle fixe la date de fin de validité des lignes qui n'en ont pas.

4. Sous Valeurs à importer, cliquez sur Importer. Dans la fenêtre Analyser le fichier CSV, cliquez sur Ajouter un fichier et choisissez votre fichier, ou faites-le glisser dans la zone. Télécharger le modèle, en bas à gauche, donne le fichier vide aux bons en-têtes.

   

5. Cliquez sur Importer. Apitail lit le fichier et contrôle chaque ligne ; Arrêter l'analyse l'interrompt. Le tableau affiche, pour chaque ligne, le Code avec la date d'émission et la valeur d'origine, le Client, les Soldes avec la date de fin de validité retenue, et le Statut. Le Résumé, à droite, totalise les lignes et le Solde disponible importable.

   

6. Traitez les lignes signalées : voir Traiter les anomalies.

7. Cliquez sur Enregistrer, dans la barre du haut. Le bouton reste inactif tant que l'analyse n'est pas terminée ou qu'aucune ligne n'est importable. La fenêtre Enregistrer les soldes initiaux ? rappelle le magasin, le type, le nombre de lignes et le Solde disponible importé. Cliquez sur Enregistrer l'import.

   

Si la page se ferme ou se recharge avant l'enregistrement, l'analyse et vos corrections sont conservées sur ce navigateur : vous les retrouvez en rouvrant le même type d'import. Une fois le fichier analysé, le magasin ne se change plus : Réinitialiser efface tout, magasin compris, pour recommencer.

Traiter les anomalies#

Chaque ligne reçoit un statut :

• Valide : la ligne sera importée ;
• Avertissement : elle sera importée, mais demande votre attention ;
• Doublon : elle ne sera pas importée, car son code existe déjà dans Apitail ou figure plusieurs fois dans le fichier ;
• Invalide : elle ne sera pas importée tant que l'anomalie n'est pas corrigée.

1. Cliquez sur le filtre À corriger : il ne garde que les lignes Doublon et Invalide. Avertissements et Importables filtrent de la même façon.

2. Survolez le statut d'une ligne : le motif s'affiche.

   

3. Pour corriger une ligne à l'écran, cliquez sur le crayon au bout de la ligne. La fenêtre Modifier la ligne porte le numéro de la ligne dans votre fichier, l'en-tête étant la ligne 1, et rappelle l'Anomalie détectée. Corrigez les valeurs, puis cliquez sur Enregistrer : la ligne est contrôlée à nouveau.

   

4. Pour corriger dans votre fichier, cliquez sur Télécharger les anomalies : vous obtenez un CSV des lignes Doublon et Invalide, avec leur numéro de ligne, leur statut et leurs motifs. Corrigez votre fichier, cliquez sur Réinitialiser, puis recommencez l'import.

Vous n'êtes pas obligé de tout corriger : les lignes Doublon et Invalide qui restent ne sont simplement pas importées.

Motif	Que faire
« Aucune règle n'est applicable »	Le magasin n'a pas de règle de ce type à la date d'émission. Ajoutez-la ou élargissez sa période, puis cliquez sur Réinitialiser et relancez l'analyse
« Le code doit être alphanumérique et différent de 0 »	Retirez les espaces, tirets et points du code. En caisse, ce code se saisira alors sans eux
« La valeur d'origine est invalide », « Le solde disponible est invalide »	Montant vide, à zéro, négatif ou avec plus de deux décimales
« Le solde dépasse la valeur d'origine »	Vérifiez les deux montants
« La date d'émission est invalide », « La date d'expiration est invalide »	Date manquante pour l'émission, ou écrite autrement que 15/03/2026 ou 2026-03-15
« La date d'émission est dans le futur », « La date d'expiration précède la date d'émission »	Corrigez la date
« L'instrument est déjà expiré »	La date de fin de validité, lue dans le fichier ou calculée par la règle, est passée : la carte n'est plus utilisable
« Ce code existe déjà »	Une carte cadeau ou un avoir porte déjà ce code dans Apitail, par exemple parce qu'il a déjà été importé
« Ce code apparaît plusieurs fois dans le fichier »	Toutes les lignes de ce code sont en doublon : gardez-en une, ou corrigez le code des autres
« Client introuvable », « Plusieurs clients correspondent »	Avertissement : la ligne est importée sans client. Videz la colonne external_id pour le faire disparaître

Résultat#

Le message « Les soldes initiaux ont été importés. » s'affiche et la page de l'import s'ouvre, titrée Import n°1 pour le premier :

• Général : le Magasin, l'Opérateur et la Date d'import ;
• Valeurs importées : les lignes créées, avec seulement les 4 derniers caractères du code ;
• Résumé : les nombres de lignes et le Solde disponible total. Votre fichier y est conservé tel quel, sous Pièce jointe, et Télécharger les lignes en doublon ou invalides donne les lignes écartées. Le fichier conservé peut contenir des formules : ne l'ouvrez dans un tableur que si vous avez confiance dans son origine.

Chaque ligne Valide ou Avertissement est devenue une carte cadeau ou un avoir au statut Actif, dans « Points de vente › Cartes cadeaux » ou « Points de vente › Avoirs ». Sur sa fiche, le Montant initial est la valeur d'origine, le Restant le solde disponible, la Date celle d'émission et Valable jusqu'au la date de fin de validité retenue. Sa partie Mouvements n'a qu'une ligne, Solde transféré.

En caisse, la carte ou l'avoir s'utilise avec son code, comme décrit dans Encaisser avec une carte cadeau ou un avoir.

L'import reste dans la liste Imports de soldes initiaux, avec sa Date, son Type, son Magasin, sa Quantité et son Solde importé. Dans Rechercher et filtrer, le critère Type de titre restreint la liste aux cartes cadeaux ou aux avoirs ; la recherche porte sur le nom du fichier. Enregistrer, puis Enregistrer la vue, conserve vos critères dans le sélecteur de vues à gauche de la barre.

Cas particuliers#

Le fichier est refusé dès l'analyse#

Le message s'affiche dans la fenêtre Analyser le fichier CSV, et aucune ligne n'est lue :

• « Les en-têtes ne correspondent pas au modèle Apitail. » : la première ligne doit reprendre les six en-têtes du modèle, dans l'ordre ;
• « Le fichier doit être encodé en UTF-8. » : enregistrez-le à nouveau au format CSV UTF-8 ;
• « Une ligne ne contient pas le bon nombre de colonnes. » : chaque ligne doit avoir six colonnes, même vides. Vérifiez les points-virgules, et supprimez les lignes vides ;
• « Le fichier dépasse la taille maximale autorisée. » ou « Le fichier contient plus de lignes que la limite autorisée. » : découpez le fichier.

« Les données ont changé depuis la confirmation »#

Si une carte, un avoir ou une règle a changé entre l'analyse et l'enregistrement, l'import est refusé avec ce message et rien n'est créé. La page se rouvre avec votre fichier : cliquez sur Importer pour relancer l'analyse. Les corrections faites à l'écran sont alors à refaire.

Importer à nouveau le même fichier#

Les lignes déjà importées sortent en Doublon, avec le motif « Ce code existe déjà », et ne sont pas créées une seconde fois. Pour reprendre une ligne écartée, importez un fichier qui ne contient qu'elle.

Points de fidélité#

Les points de fidélité ne se reprennent pas depuis cet écran : la fenêtre Nouvel import ne propose que Cartes cadeaux et Avoirs.