L’adaptateur fiscal Apex

Le problème

Le moteur fiscal standard ne calculait rien sur l’org testée : il acceptait la requête et rendait zéro. Un adaptateur custom était le seul moyen de produire une facture taxée.

Le contexte

Des taux déjà présents dans une table existante, plusieurs entités juridiques aux règles différentes, et aucun prestataire fiscal externe dans le périmètre. L’adaptateur est donc purement interne : il lit les taux dans l’org et les rend.

L’architecture recommandée

Une classe Apex qui implémente l’interface d’adaptateur fiscal, enregistrée via un provider et un engine. Le type de moteur qui fonctionne exige un named credential, un seller code et des champs d’adresse alors même que l’adaptateur ne sort jamais de l’org. Un named credential factice suffit.

N’écrivez pas l’adaptateur de zéro. Partez d’un qui tourne déjà. Le moteur acceptera une réponse structurellement valide et lira quand même zéro s’il manque les détails de montants, le drapeau taxable, les adresses de réponse ou les totaux d’en-tête — ce qui fait d’un adaptateur écrit de zéro une longue suite d’échecs silencieux.

Mise en œuvre

L’ordre qui marche : les permissions d’abord, puis l’enregistrement du moteur, puis la classe, puis les données, puis une vraie transaction. Chacune de ces étapes peut échouer d’une manière qui ressemble à la précédente.

Ce que ça coûte

Un adaptateur, c’est de l’Apex : il lui faut une classe de test et de la couverture d’org avant d’atteindre la production. Sur un projet, le point d’entrée de traitement de la requête s’est révélé intestable — Salesforce n’expose pas de constructeur pour ses classes de requête — ce qui a plafonné la couverture et est devenu le vrai bloqueur du déploiement.

Si la règle peut s’exprimer en lignes de taux plus un traitement sur la ligne, préférez la configuration. Voir code de TVA par pays, qui a résolu un problème comparable sans une ligne d’Apex.

Attention

• Type de moteur. Le mauvais échoue sur « Commerce Tax Service isn't accessible ». Celui qui marche exige un named credential et un seller code quoi qu’il arrive.
• Version d’API de la classe. ZipCode et ProductCode sur l’objet de taux n’existent qu’à partir de l’API 66.0. Une classe plus ancienne répond « No such column » même en SOQL dynamique — et vous accuserez la requête, pas la version.
• Accès Apex. L’utilisateur qui déclenche le calcul doit avoir accès à la classe, sinon le calcul ne rend rien.
• Adresses. Lues sur la ligne, jamais sur l’en-tête — et sur une org elles arrivaient entièrement nulles, forçant un repli sur le compte de la transaction.
• Nom de taxe. Le nom requis vient de la juridiction, pas de l’objet de réponse, qui n’a pas de setter pour ça.
• Ne filtrez pas les taux par produit. Le code de la ligne est un code fiscal, pas un type de produit. Filtrer sur le produit casse les taux identiques d’un produit à l’autre.
• Les permission sets standard ont été refusés dans un permission set group déployé en métadonnée ; les ajouter par API a fonctionné, et chaque ajout reverrouillait le groupe — l’insert a donc besoin d’un retry.
• Un traitement actif ne peut plus changer de moteur. Désactivez-le d’abord.

Composants Salesforce