Développement Apex sur REDA

Le code Apex personnalisé autour de REDA Financials obéit à une règle d’or : s’appuyer sur la surface globale et les objets, jamais sur les éléments internes. Voici la boîte à outils stable et les modèles qui en tirent le meilleur parti.

La surface globale — treize classes et interfaces

Dans un package géré, seul le code Apex global est visible par votre code ; tout ce qui est public reste derrière la barrière de l’espace de noms. REDA Financials maintient délibérément cette surface prise en charge réduite — treize types globaux pour le code des clients et des partenaires. Cinq d’entre eux portent les points d’entrée du quotidien ; les autres sont les contrats d’extension de facturation électronique et les types de données qu’ils échangent :

Les contrats de fournisseur abstraits sont présentés dans Packages d’extension ; cet article se concentre sur les deux classes que vous appelez. Toutes les classes de l’API sont livrées en version d’API 65.0, et la garantie standard des packages gérés s’applique : une fois publiées, les signatures globales ne peuvent être ni supprimées ni modifiées à votre insu — elles constituent le contrat stable.

Ce que vous ne pouvez pas appeler

La couche de services interne qui fait le vrai travail — comptabilisation, import des relevés bancaires, rendu des PDF, appels sortants d’IA et de taux de change, mises à jour de statut en masse, initialisation des taxes — est public, et non globale. Le code Apex de l’abonné ne peut pas du tout appeler ces classes : le compilateur ne les voit tout simplement pas au-delà de la frontière de l’espace de noms, et leur structure interne peut changer à chaque version. Si une capacité dont vous avez besoin n’existe que derrière une classe publique, la voie prise en charge est le comportement qu’elle alimente — la comptabilisation via le champ Statut, la génération de PDF via refin.PDFGeneratorAPI, l’initialisation des taxes via l’assistant d’initialisation des taxes fourni avec le package — et non la classe elle-même.

refin.GlobalTaxService — le calcul des taxes en tant que service

Deux méthodes statiques donnent à votre code accès aux mêmes moteurs que ceux qu’utilisent les documents, sans aucun effet de bord :

• calculateTax(TaxRequest) — taxe indirecte (TVA/GST/taxe sur les ventes). Fournissez-lui l’entité, le compte, la date, le côté ('Sales'/'Purchase') et les lignes (montant + produit ou profil fiscal explicite, avec votre propre lineKey pour la corrélation) ; vous récupérez, pour chaque ligne, des lignes de taxe entièrement résolues — taux, montant, indicateur de récupérabilité, et le compte général sur lequel chaque taxe serait comptabilisée.
• calculateWithholdingTax(WHTRequest) — le moteur de retenue à la source, avec la même structure : des lignes en entrée, la retenue de chaque ligne en sortie (taux, base, montant, motifs d’exonération, compte général).
• Le contrat : aucun DML, aucun enregistrement créé, aucune exception levée — les erreurs reviennent sous la forme success=false avec un message. La persistance vous appartient entièrement : idéal pour les devis, les calculateurs, les estimations avant comptabilisation ou les contrôles de concordance avec des systèmes externes.

La référence complète

Les deux points d’entrée sont statiques :

global static TaxResponse calculateTax(TaxRequest request)
global static WHTResponse calculateWithholdingTax(WHTRequest request)

La documentation de la classe énonce clairement le contrat : « Aucun DML n’est effectué. Aucun enregistrement Source_Line_Tax ou WHT_Transaction n’est créé. L’appelant est responsable de la persistance et de la comptabilisation. » Une réponse est « toujours renvoyée, sans jamais lever d’exception vers l’appelant » — les problèmes de validation (entité, compte, date, côté ou lignes manquants, ou valeur de côté non valide) reviennent sous la forme success=false, avec le motif dans errorMessage, dans le même langage de validation que celui des documents eux-mêmes. Une classe GlobalTaxServiceException existe dans la surface globale, mais dans le cadre du contrat normal, vous lisez la réponse plutôt que d’intercepter une exception.

Les DTO de requête et de réponse sont des classes globales dotées de membres globaux — vous pouvez définir ou lire tout ce qui suit :

L’ensemble dédié à la retenue à la source en est le reflet :

Comment les comptes généraux sont résolus. Les comptes généraux de la taxe indirecte proviennent des enregistrements de correspondance comptable par type de taxe (refin__Tax_Type_GL_Mapping__c) : une correspondance propre à l’entité l’emporte sur une correspondance valable pour toute l’organisation, la recherche se faisant par type de taxe et par récupérabilité pour le côté de la requête ; les taxes incluses reçoivent en outre un compte général de déduction issu du côté « Déduction sur ventes » / « Purchase Deduction » de la correspondance. Les comptes généraux de retenue proviennent du champ Compte général du taux de retenue à la source correspondant, avec repli sur le compte Retenue à payer par défaut de l’entité. Autrement dit, la réponse vous indique non seulement combien, mais aussi où le montant serait comptabilisé — la même résolution que celle qu’effectue la comptabilisation.

Un appel minimal, à la manière de Meridian — l’entité américaine chiffre la ligne de loyer d’un locataire avant qu’aucune facture n’existe :

refin.GlobalTaxService.TaxRequest req = new refin.GlobalTaxService.TaxRequest();
req.entityId = meridianUsEntityId;
req.accountId = brightlineAccountId;
req.transactionDate = Date.today();
req.side = 'Sales';

refin.GlobalTaxService.TaxLineRequest line = new refin.GlobalTaxService.TaxLineRequest();
line.lineKey = 'unit-4b-rent';
line.amount = 9000;
line.productId = officeRentProductId;
req.lines = new List<refin.GlobalTaxService.TaxLineRequest>{ line };

refin.GlobalTaxService.TaxResponse res = refin.GlobalTaxService.calculateTax(req);
if (res.success) {
    for (refin.GlobalTaxService.TaxResultLine t : res.lines) {
        System.debug(t.lineKey + ' -> rate ' + t.taxRate + ', tax ' + t.taxAmount
            + ', GL ' + t.glAccountId);
    }
} else {
    System.debug(res.errorMessage);
}

Le pendant pour la retenue à la source suit le même rythme. L’entité indienne de Meridian estime la retenue TDS sur la facture d’un prestataire avant sa saisie : construisez un WHTRequest avec side = 'Purchase', un WHTLineRequest par ligne de facture portant lineSubtotal, appelez calculateWithholdingTax, puis lisez chaque WHTResultLine — rate, base, amount et isExempt avec son exemptReason lorsqu’un certificat ou un seuil exempte la ligne. Comme rien n’est persisté, l’équipe des comptes fournisseurs peut annoncer au fournisseur le montant net à payer, et les chiffres correspondront au paisa près au document comptabilisé.

refin.PDFGeneratorAPI — des documents depuis le code

generateOne(sourceRecordId, sourceObjectApiName) génère et joint le PDF d’un document comptabilisé — facture de vente, avoir, encaissement, décaissement ou bon de commande — et renvoie les ID de contenu ainsi que, lorsque le territoire active les liens publics, l’URL. Le pendant côté flux est présenté dans Intégration avec les flux Salesforce.

La signature :

global static PDFResult generateOne(Id sourceRecordId, String sourceObjectApiName)

Selon les termes mêmes de la classe, « les packages d’extension l’appellent depuis Apex lorsqu’ils ont besoin d’une génération de PDF programmatique en dehors d’un contexte de flux ». Le paramètre sourceObjectApiName doit désigner l’un des objets source pris en charge :

Le PDF produit est joint à l’enregistrement source sous forme de ContentVersion avec un ContentDocumentLink — un fichier Salesforce ordinaire que vous pouvez interroger, partager ou envoyer par e-mail. Le publicUrl du résultat n’est renseigné que « si l’entité a l’option Auto Public URL activée ; null sinon » — le code qui envoie des liens aux clients par e-mail doit donc tester la valeur null plutôt que de supposer qu’une URL existe. Et vous n’aurez peut-être même pas besoin de code : chaque entité dispose d’options de génération automatique par type de document (refin__Auto_Gen_PDF_Sales_Invoice__c, refin__Auto_Gen_PDF_Cash_Receipt__c, refin__Auto_Gen_PDF_Cash_Disbursement__c, refin__Auto_Gen_PDF_Purchase_Order__c, refin__Auto_Gen_PDF_Credit_Memo__c) — generateOne sert aux cas qui sortent de ce cadre, comme une régénération à la demande ou l’ajout du PDF à un envoi personnalisé.

Comptabiliser depuis Apex — le champ Statut est l’API

Il n’existe pas de méthode post() à appeler, et c’est voulu : le moteur de comptabilisation s’exécute dans la phase des déclencheurs de la mise à jour de l’objet source lui-même. Votre code Apex comptabilise un document de la même manière qu’un utilisateur — faites passer refin__Status__c de « Brouillon » à « Comptabilisé » par une mise à jour DML, et toute la mécanique s’exécute : moteurs de taxe et de retenue à la source, inscription du taux de change lors du passage au statut Comptabilisé, et chaque garde-fou (contrôle d’approbation, validation de la période, blocages sur une entité ou un compte général inactif). Une comptabilisation refusée se manifeste par une exception DML portant le message exact du garde-fou — traitez-la comme le contrat de l’API, pas comme du bruit.

Le modèle de création fiable se déroule en deux temps : insérer en Brouillon (en-tête et lignes), puis passer le statut à « Comptabilisé » dans un second appel. À l’insertion, un statut nul prend par défaut la valeur « Brouillon », les numéros de document sont attribués automatiquement à partir de la séquence de documents de l’entité (prédéfinir le champ Name revient à une numérotation manuelle, dont l’unicité est validée), et les valeurs par défaut de l’entité sont renseignées automatiquement — le Grand livre, la Période comptable et la Date d’échéance d’après la Condition de paiement du fournisseur. Notez que modifier l’Entité ou le Type de facture d’un document en Brouillon le renumérote : effectuez donc vos modifications avant de comptabiliser.

Réagir aux événements comptables

Vos déclencheurs et vos flux déclenchés par un enregistrement sur les objets refin__ cohabitent sans problème avec ceux du package (l’ordre d’exécution entre les packages et les automatisations de l’organisation suit les règles standard de la plateforme — gardez les vôtres idempotents). Le modèle le plus rentable : réagir aux transitions de statut — un déclencheur sur la facture de vente qui détecte le passage Brouillon→Comptabilisé peut alimenter votre système en aval avec un document déjà entièrement validé et numéroté. Réagissez après le travail du package : lisez l’état final de l’enregistrement plutôt que d’essayer de vous interposer.

Les règles qui préservent la compatibilité avec les mises à niveau

Erreurs courantes à éviter

Pour aller plus loin

1. Packages d’extension — les contrats de fournisseur destinés aux ISV.
2. Lightning Web Components — le pendant côté interface utilisateur.
3. Présentation de l’API — la vue d’ensemble.

Questions fréquentes