Ciama : convertir chaque vente à sa date et résoudre la TVA par produit et pays

1. Ciama, un OMS qui reçoit des ventes de plusieurs univers et plusieurs pays

Marketplace, e-commerce et B2B n’envoient pas les mêmes formes de données

Ciama collecte des commandes marketplace, e-commerce et B2B. Selon la source, le pays peut venir de l’adresse de livraison, du pays du client ou d’un code porté par le canal. La devise accompagne la commande et ses lignes, tandis que le compte utilisateur possède sa propre devise de référence.

Le modèle conserve le montant source et le montant converti. Une commande en dollars ne devient donc pas artificiellement une commande en euros : l’objet garde la devise reçue, la devise cible et le résultat comparable utilisé par le cockpit.

Le pays de livraison intervient aussi dans la décomposition TTC, TVA et HT. Le produit peut nécessiter un taux particulier dans un pays donné ; à défaut, un taux standard du catalogue s’applique. Sans pays résolu, Ciama ne fabrique pas un taux par défaut silencieux.

Cette brique se situe au cœur du calcul financier : elle alimente les commandes, les commissions normalisées, la finance de ligne et les agrégats du module Ciama Marketplace.

2. Séparer référentiels, résolution et recalcul

Trois responsabilités pour rendre chaque valeur explicable

Le premier étage porte les référentiels. Un pays possède un nom, des codes ISO alpha-2 et alpha-3 et, lorsqu’elles existent, des coordonnées. Une devise possède son identifiant et son nom ; un taux de conversion relie une devise de base, une cible et un jour précis.

Le deuxième étage résout les valeurs au moment de la vente. Il choisit le pays, la devise cible du compte, le taux de conversion du jour puis la TVA applicable. Les services retournent une absence ou une erreur structurée lorsqu’un élément indispensable manque.

Le troisième étage permet de changer une règle sans perdre la maîtrise de son périmètre. Une exception TVA peut viser seulement les prochaines ventes ou réécrire les champs fiscaux des lignes existantes du même compte, produit et pays, puis demander leur recalcul financier.

Ce découpage explique la progression du projet : référentiels en novembre, consultations API en décembre, puis règles de conversion, configuration TVA, synchronisation et contrôles renforcés en mars.

3. Le risque initial : calculer une marge avec des unités monétaires différentes

Un montant sans devise, date ou pays ne suffit pas à produire un HT comparable

Une marketplace peut renvoyer le total d’une ligne dans la devise du canal. Le compte Ciama, lui, peut piloter en euros ou dans une autre devise. Additionner directement les deux nombres créerait un chiffre d’affaires sans unité cohérente.

Utiliser le taux de change actuel pour une vente ancienne poserait un autre problème : le résultat évoluerait avec la date de consultation alors que la transaction, elle, n’a pas changé. La conversion doit donc être liée à la date d’achat.

La TVA agit ensuite sur la base hors taxes. À partir d’un montant TTC, un taux absent empêche de retrouver le HT ; un mauvais taux modifie le revenu qui alimente la marge. Le pays de livraison et le produit deviennent des données financières, pas seulement des informations d’adresse.

Le projet devait donc préserver la valeur source, produire une valeur comparable et garder assez de contexte pour expliquer chaque transformation.

4. Résoudre le pays de livraison à partir de deux sources possibles

Code de livraison d’abord, pays du client ensuite

Lorsqu’une commande entre dans Ciama, le service examine d’abord le code ISO du pays de livraison, puis le code pays du client. Les valeurs sont nettoyées, mises en majuscules et dédupliquées avant recherche.

Pour chaque valeur, Ciama cherche le code alpha-2 puis le code alpha-3. Cette double lecture absorbe les formats les plus courants des connecteurs sans réduire le pays à une chaîne libre différente sur chaque commande.

Si aucune correspondance n’existe, le pays reste absent. Le traitement n’assigne pas automatiquement la France ou le pays du compte, car ce repli rendrait une TVA calculable au prix d’une fausse localisation.

Le pays résolu est porté par la commande et par ses lignes. Il peut ensuite alimenter les filtres, les statistiques de destination, la TVA et le périmètre d’un éventuel recalcul.

5. Conserver la devise source et une valeur convertie séparée

La comparaison n’efface jamais la transaction d’origine

La devise reçue du connecteur est recherchée dans le référentiel par son identifiant. Le montant TTC source reste associé à cette devise sur la commande et sur la ligne.

Ciama calcule en parallèle un montant converti. La devise cible provient du compte utilisateur lorsqu’elle est configurée ; si elle ne peut pas être résolue, l’euro sert de repli explicite.

Une conversion réussie associe la valeur à la devise cible. Si la source, la cible ou le taux manque, le montant converti reste absent au lieu de reprendre silencieusement le nombre source sous une autre unité.

Cette séparation permet d’afficher la vérité du canal et la base commune du cockpit. Elle évite aussi qu’un changement de devise de compte réécrive le montant réellement encaissé.

6. Chercher un taux de change propre au jour de la vente

Paire de devises et date forment une clé unique

Le service de conversion exige une devise source, une devise cible et une date. Lorsque les deux devises sont identiques, le taux vaut 1 et le montant reste inchangé.

Dans les autres cas, Ciama recherche d’abord un taux déjà enregistré pour la paire et le jour de la transaction. Unicité et index temporels empêchent de conserver deux vérités concurrentes pour la même combinaison.

Si le taux manque, le service interroge Frankfurter avec la date d’achat, la devise de base et la cible. Seule une valeur numérique strictement positive est acceptée, puis enregistrée avant de multiplier le montant source.

Une réponse réseau invalide, un statut en erreur ou un taux absent aboutit à une conversion indisponible. Le calcul ne remplace pas l’échec par un taux de 1 qui rendrait deux devises artificiellement équivalentes.

7. Préparer les lectures du compte sans multiplier les appels externes

La devise de pilotage reste prioritaire ; EUR et USD servent les affichages disponibles

Pour le montant principal, la cible est la devise du compte, avec l’euro en repli. Cette règle donne à toutes les commandes du compte une unité de pilotage commune lorsqu’une conversion est possible.

Au passage d’une commande, Ciama vérifie également si les taux du jour vers l’euro et le dollar existent, à condition que ces devises soient présentes dans le référentiel. La devise source identique à une cible est naturellement exclue de la recherche.

Seules les paires manquantes déclenchent le service de conversion. Un taux déjà enregistré pour cette date est réutilisé, ce qui évite une requête externe à chaque ligne de la même journée.

Ces taux d’affichage ne remplacent pas la devise du compte. Ils préparent des vues complémentaires tout en conservant une seule cible métier pour les agrégats financiers.

8. Synchroniser un catalogue de taux par pays chaque nuit

Taux standard, réduits, super-réduit et parking restent nommés

Une tâche de production interroge chaque nuit à 2 h 30 la source VATComply. Elle accepte une réponse sous forme de liste ou de collection indexée par pays et rapproche chaque ligne du référentiel Ciama avec son code alpha-2.

Les codes GR et UK sont normalisés vers EL et GB avant recherche. Les taux standard, super-réduit, parking et réduits sont lus lorsqu’ils sont numériques et positifs ou nuls.

Deux taux identiques dans la réponse ne créent pas deux lignes équivalentes. Les valeurs sont dédupliquées puis triées ; le taux nommé STANDARD reçoit le marqueur qui permet au résolveur de le choisir par défaut.

La tâche possède un mode de simulation. Son bilan distingue créations, mises à jour, pays manquants, lignes ignorées et erreurs ; au moins une erreur d’écriture rend l’exécution globale défaillante.

9. Donner la priorité à l’exception produit et pays

Une règle locale au compte peut remplacer le standard sans modifier le catalogue commun

Pour une ligne de commande, Ciama reçoit le compte, le produit et le pays. Si le pays manque, aucun taux n’est retourné. Si le produit est connu, le résolveur cherche d’abord une exception propre à ce compte, ce produit et ce pays.

Lorsqu’une exception existe, elle est utilisée immédiatement. Sinon, le service demande le taux standard actif du pays dans le catalogue commun. Les taux réduits restent visibles mais ne sont pas choisis automatiquement sans configuration du produit.

Cette priorité protège deux réalités : le catalogue fournit un défaut partagé, tandis que le compte garde la capacité d’appliquer un taux adapté à un produit précis. Une exception d’un vendeur ne change pas le standard des autres.

Les services d’écriture refusent un compte, un produit ou un pays introuvable, un identifiant vide et un taux négatif. Une règle incohérente n’atteint donc pas le calcul de commande.

10. Décomposer le TTC et normaliser chaque coût avant la marge

TVA puis conversion donnent une base HT comparable

Lorsque le taux est disponible, le HT de la ligne est obtenu en divisant le TTC par 1 plus le taux exprimé en décimal. La TVA correspond à la différence entre le TTC et ce HT. Le montant HT est ensuite converti dans la devise cible à la date d’achat.

Les commissions reçues hors taxes restent HT ; lorsqu’elles arrivent TTC, le taux de TVA est obligatoire pour retrouver leur montant hors taxes. Les deux valeurs peuvent ensuite être converties par le même service de devise.

Les coûts d’achat ne sont acceptés qu’en hors taxes dans ce normaliseur. Cette contrainte évite d’appliquer un taux de vente à un achat dont le traitement fiscal peut suivre une autre logique.

Le taux de commission par rapport au prix HT n’est calculé que si le prix HT converti est strictement positif et si la commission HT convertie existe. Les valeurs incomplètes restent absentes plutôt que produire un ratio trompeur.

11. Configurer la TVA depuis la fiche du produit

Choisir le standard, une valeur du catalogue ou un taux personnalisé

La vue TVA du produit parcourt les pays qui disposent de taux actifs. Pour chacun, elle affiche le catalogue, le taux standard, la valeur actuellement sélectionnée et l’éventuelle exception du compte.

Si l’exception n’appartient pas aux valeurs courantes du catalogue, elle apparaît comme taux personnalisé. L’utilisateur peut ainsi relire une configuration historique sans la voir disparaître d’une liste devenue plus récente.

Choisir exactement le taux standard retire l’exception plutôt que conserver une copie inutile. Une exception peut aussi être réinitialisée pays par pays, ou toutes les exceptions du produit peuvent être supprimées en une seule action.

Chaque modification distingue deux portées : les ventes futures uniquement, ou les ventes existantes du même périmètre. Cette décision explicite empêche une correction de configuration de réécrire automatiquement tout l’historique.

12. Recalculer l’historique par compte, produit et pays

Un périmètre strict parcouru par lots de 500 lignes

Lorsque l’utilisateur choisit d’appliquer le taux aux commandes existantes, Ciama réécrit uniquement les lignes qui partagent le compte, le produit et le pays concernés. Le TTC source reste la base ; HT et TVA sont recalculés avec le nouveau diviseur.

Les montants convertis déjà présents sont décomposés selon la même règle afin de garder TTC, HT et TVA convertis cohérents. La date de mise à jour signale la modification.

Un message asynchrone recherche ensuite les identifiants par lots de cinq cents, triés dans l’ordre. Chaque ligne déclenche le calcul agrégé qui reconstruit sa finance et propage les synthèses concernées.

Le curseur reprend après le dernier identifiant du lot précédent. Le traitement reste borné en mémoire et ne charge pas tous les objets d’un historique important en une seule fois.

13. Conserver les paramètres utilisés dans la finance de ligne

Le calcul final reste relisible après la collecte

La finance de ligne enregistre la date d’achat, les quantités, le statut, le prix TTC converti, le taux de TVA et le prix HT converti. Elle conserve également les commissions, l’expédition et l’achat, avec leurs sources réelles ou estimées.

La devise cible, le taux de conversion utilisé et la date d’observation du taux sont mémorisés lorsque la conversion réussit. Le montant de marge n’est donc pas séparé des paramètres monétaires qui ont permis de le calculer.

Lors d’une reconstruction, le service tente d’abord de convertir la valeur source. Il n’utilise une ancienne valeur convertie qu’en repli, et seulement si sa devise correspond exactement à la cible actuelle.

La marge réelle et l’estimation sont ensuite recalculées sur des montants HT convertis. La normalisation pays, devise et TVA devient ainsi une dépendance visible du calcul de marge de chaque vente.

14. Donner aux référentiels leurs propres écrans de contrôle

Pays, taux de TVA et devises restent consultables hors de la commande

La liste des pays affiche par défaut ceux qui disposent d’une configuration TVA. La recherche accepte un nom, un code alpha-2 ou alpha-3 ; la fiche pays présente ensuite ses taux actifs avec le standard en premier.

Une matrice TVA rassemble les pays en lignes et les noms de taux en colonnes. Les drapeaux dérivés des codes alpha-2 facilitent la lecture sans remplacer le code de référence.

La liste des devises se recherche par identifiant et se trie indépendamment des commandes. Une API expose aussi recherche et détail des pays et des devises pour les consommateurs qui ont besoin du même référentiel.

Ces écrans ne modifient pas les règles fiscales depuis une ligne de vente. Ils offrent un point de contrôle commun avant d’ouvrir la configuration propre à un produit.

15. Tester les absences, les priorités et les replis dangereux

Les cas d’échec comptent autant que la conversion réussie

Les tests de conversion couvrent les identifiants de devises manquants, la date absente, une devise inconnue, une paire identique, un taux déjà enregistré, la récupération externe puis l’écriture, et l’impossibilité d’obtenir un taux.

Les tests TVA vérifient qu’une exception produit/pays évite la consultation du standard, puis qu’un standard prend le relais lorsque l’exception manque. L’absence de pays doit retourner une absence de taux.

Les services d’ajout contrôlent l’unicité et le format des pays et devises ; les taux journaliers exigent une paire valide, une date et une valeur positive. Les écrans pays et TVA disposent aussi de scénarios applicatifs.

Enfin, le recalcul historique est limité à trois clés de périmètre. Ce contrôle protège contre la correction d’un produit qui modifierait les lignes d’un autre compte ou d’un autre pays.

16. Faire vivre les taux sans rendre les ventes dépendantes d’un seul appel

Catalogue TVA nocturne et taux de change mis en cache par jour

Le catalogue TVA est rafraîchi en production à 2 h 30. Une indisponibilité de la source, une réponse vide ou un format invalide arrête la synchronisation en échec sans vider les taux déjà enregistrés.

Les changes suivent une logique à la demande : une paire déjà connue pour le jour de vente est réutilisée. La source externe n’est interrogée que lorsque ce taux manque, puis la valeur validée est persistée.

Le recalcul des anciennes lignes passe par la file de messages. La mise à jour de l’interface peut donc confirmer la règle sans attendre le retraitement financier de chaque commande historique.

Ces trois rythmes sont volontairement différents : taux de TVA du catalogue, change daté et recalcul des ventes n’ont ni la même source ni la même fréquence de changement.

17. Ce qui change après la consolidation

Des montants comparables qui gardent leur origine

Une commande conserve son pays et sa devise source tout en exposant un montant converti dans la devise du compte. La comparaison globale ne détruit plus l’information nécessaire pour revenir à la transaction.

Le taux de change correspond au jour de l’achat et peut être réutilisé pour toutes les lignes de la même paire à cette date. Une vente ancienne ne change pas de valeur uniquement parce qu’elle est consultée plus tard.

La TVA suit une priorité lisible : exception du compte pour un produit et un pays, sinon standard du catalogue. Le produit peut revenir au standard sans garder une exception redondante.

Une correction peut rester prospective ou reprendre l’historique choisi. Dans ce second cas, compte, produit et pays bornent la réécriture, puis des lots de cinq cents lignes propagent le nouveau calcul.

La finance de ligne conserve enfin le taux de TVA, la devise, le change et la date observée. Les écarts de marge peuvent être recherchés dans leurs paramètres au lieu d’être attribués à un total opaque.

18. Le parcours d’une vente étrangère dans Ciama

Du montant TTC source à la marge exprimée dans la devise du compte

Considérons une commande reçue en dollars avec un pays de livraison reconnu, un produit rattaché et une date d’achat précise. Le compte Ciama pilote en euros.

Le pays est retrouvé par son code ISO. La devise USD reste attachée à la commande, tandis que le service recherche le taux USD vers EUR du jour de l’achat. S’il n’existe pas encore, il est demandé puis enregistré pour cette paire et cette date.

Le résolveur cherche ensuite une exception TVA pour ce compte, ce produit et ce pays. Sans exception, il choisit le taux standard actif. Le TTC est décomposé en HT et TVA, puis le HT est converti en euros.

La commission suit la même normalisation selon qu’elle arrive TTC ou HT. La finance de ligne reçoit les montants convertis, le taux de TVA et le taux de change avant de recalculer la marge réelle ou estimée.

Si le taux produit/pays change ensuite, l’utilisateur peut l’appliquer uniquement aux prochaines ventes ou choisir les anciennes. Dans ce cas, seules les lignes du même périmètre sont réécrites puis recalculées par lots.

19. Les limites qui gardent la donnée honnête

Une règle manquante reste visible au lieu d’être remplacée par une supposition

Sans pays reconnu, aucun taux de TVA n’est choisi. Sans devise source ou cible, aucune conversion n’est produite. Sans taux de change valide, le montant comparable reste absent.

Le catalogue VATComply fournit des valeurs de référence, mais le choix du taux réellement applicable à un produit relève de sa configuration et du contexte fiscal de la vente. Ciama n’automatise pas cette qualification juridique.

Le taux de conversion est journalier, pas intrajournalier. Le modèle privilégie une base stable par date de transaction ; il ne prétend pas reconstruire l’instant exact d’un marché des changes.

Enfin, une correction TVA historique modifie les champs fiscaux et relance les calculs, mais elle ne modifie pas le TTC source reçu du canal. La donnée commerciale d’origine reste la frontière du retraitement.

20. Relier pays, devise et TVA aux autres preuves du cockpit

Normaliser d’abord, agréger et décider ensuite

La fiche marge réelle, estimée ou bloquée par vente montre comment les montants HT convertis rejoignent commission, expédition et achat.

La consolidation par produit, marque, catégorie et tag agrège ensuite ces finances de ligne sans mélanger réel, estimation et données manquantes.

Le dashboard de ventes multicanal compare B2B, marketplaces et e-commerce dans l’unité du compte. La lecture Buy Box et repricing prolonge enfin l’analyse lorsque le pays et la devise influencent un prix concurrent.

Le parcours reste cohérent : identifier la transaction, normaliser son unité et son HT, calculer sa marge, consolider les résultats puis préparer un arbitrage commercial.