Packages d’extension

Certaines intégrations sont des produits à part entière — des flux bancaires avec les identifiants du prestataire, la facturation électronique auprès des API gouvernementales. REDA Financials les structure en packages d’extension : le package principal définit un contrat abstrait global, l’extension l’implémente, et un enregistrement de configuration relie les deux. Deux contrats de base sont livrés aujourd’hui, ainsi que trois interfaces de capacité facultatives qu’un prestataire n’implémente que s’il en a besoin.

Fonctionnement du modèle

Les deux contrats suivent la même architecture, et les en-têtes des deux classes la décrivent dans les mêmes termes : « The core package resolves the provider at runtime via: Type.forName(setup.Provider_Class__c).newInstance() ». Aucun des deux contrats n’impose un prestataire en dur. Il y a quatre composants, chacun avec un responsable clairement identifié :

refin.BankFeedProvider — relevés bancaires automatisés

• Le contrat : trois méthodes que fournit une implémentation — connect (le processus de liaison du prestataire), sync (récupérer les transactions depuis le curseur et livrer les lignes de relevé), disconnect (révoquer l’accès). Les résultats sont renvoyés sous une forme standard (réussite, transactions importées, curseur mis à jour, solde, erreur).
• Le câblage : un enregistrement Configuration de flux bancaire par compte connecté — nom du prestataire, environnement (Sandbox/Production), nom de la classe d’implémentation, curseur et statut de synchronisation (Actif / En pause / Erreur / Déconnecté), dernière synchronisation. Les configurations se trouvent sur la page d’enregistrement du compte bancaire.
• Les identifiants restent dans l’extension — le package principal ne voit jamais les jetons du prestataire ; l’extension gère son authentification de bout en bout.
• Le bénéfice : les relevés arrivent sous forme de relevés bancaires ordinaires (avec la source d’import renseignée en conséquence) et suivent le même rapprochement des lignes et le même rapprochement bancaire qu’un fichier CSV — l’automatisation en amont, un processus familier en aval.

Le contrat de flux bancaire, méthode par méthode

Chaque méthode reçoit l’enregistrement de configuration comme contexte. La documentation de la classe décrit le modèle : « Each method receives the Bank_Feed_Setup__c record as the primary context — the provider reads the linked bank account and its own credentials to execute sync logic. »

global abstract BankFeedResult sync(refin__Bank_Feed_Setup__c setup);

global abstract BankFeedResult connect(
    refin__Bank_Feed_Setup__c setup,
    Map<String, String> params
);

global abstract void disconnect(refin__Bank_Feed_Setup__c setup);

BankFeedResult est une classe interne globale — chaque membre est @AuraEnabled global, et le constructeur initialise success à false et transactionsImported à 0 ; une implémentation doit donc mériter sa réussite :

refin__Bank_Feed_Setup__c — référence des champs

Un squelette d’implémentation

Voici la forme d’un prestataire — l’équipe de Meridian en esquisse un pour l’API directe de sa banque américaine. Seuls les éléments du contrat sont réels ; les commentaires indiquent où placer la logique de votre prestataire :

global class MeridianBankFeedProvider extends refin.BankFeedProvider {

    global override refin.BankFeedProvider.BankFeedResult connect(
            refin__Bank_Feed_Setup__c setup, Map<String, String> params) {
        refin.BankFeedProvider.BankFeedResult result =
            new refin.BankFeedProvider.BankFeedResult();
        // Échangez les paramètres de connexion (p. ex. public_token) avec le
        // prestataire. Stockez les identifiants dans VOTRE package — jamais dans les objets du package principal.
        result.success = true;
        return result;
    }

    global override refin.BankFeedProvider.BankFeedResult sync(
            refin__Bank_Feed_Setup__c setup) {
        refin.BankFeedProvider.BankFeedResult result =
            new refin.BankFeedProvider.BankFeedResult();
        // 1. Récupérez les transactions depuis setup.refin__Sync_Cursor__c
        // 2. Livrez-les sous forme de lignes de relevé bancaire
        // 3. Renvoyez le nouveau curseur pour qu’il puisse être enregistré
        result.transactionsImported = 42;
        result.updatedCursor = 'cursor-after-this-batch';
        result.success = true;
        return result;
    }

    global override void disconnect(refin__Bank_Feed_Setup__c setup) {
        // Révoquez les jetons et les webhooks côté prestataire ; le package
        // principal passe Sync_Status à Disconnected une fois cette méthode terminée.
    }
}

refin.EInvoiceProvider — facturation électronique réglementaire

• Le contrat : submit (construire la charge utile propre à la juridiction à partir du document et appeler l’administration fiscale), checkStatus (interroger les administrations asynchrones), cancel (des règles propres à chaque juridiction s’appliquent — la note du contrat cite elle-même le délai de 24 heures au Brésil et l’acceptation par le destinataire au Mexique).
• Le câblage : une Configuration de facturation électronique par entité/pays — prestataire, environnement, classe d’implémentation, types de documents concernés, et une option Soumission auto à la comptabilisation ; chaque tentative de soumission est enregistrée sous forme d’Historique de facturation électronique sur le document (statut, UUID et numéro fiscaux, charges utiles, réponse, nombre de tentatives) — la piste d’audit de conformité qu’attendent les autorités de contrôle.
• Note de disponibilité : les historiques et les listes associées sont visibles dans toute l’application (vous avez déjà vu Suivis de facture électronique sur les pages des factures) ; la soumission réelle nécessite l’extension du prestataire pour votre juridiction — vérifiez auprès de REDA ce qui est disponible pour votre pays.

Le contrat de facturation électronique, méthode par méthode

Les trois renvoient un EInvoiceResult — membres : success, status, fiscalUUID, fiscalNumber, responseCode, responseMessage, xmlPayload, responsePayload, errorMessage.

Les objets de facturation électronique — référence des champs

L’enregistrement refin__E_Invoice_Trail__c est la ligne d’audit propre à chaque soumission : des champs de relation vers la configuration et la facture source, Document_Type__c, Status__c, Fiscal_UUID__c, Fiscal_Number__c, XML_Payload__c, les champs de réponse (Response_Code__c/Message__c/Payload__c/Date__c), Submitted_Date__c, Retry_Count__c et Provider_Document_Id__c — la chaîne de preuves qu’attendent les autorités de contrôle, une ligne par tentative. Status__c compte huit valeurs : Brouillon, Prêt à envoyer, En file d’attente, Soumis, Accepté, Rejeté, Annulé, Erreur.

Interfaces de capacité facultatives — comment un contrat figé continue de s’enrichir

refin.EInvoiceProvider a été livré en tant que classe abstraite globale dans une version Managed-Released, ce qui signifie qu’aucune méthode ne pourra jamais y être ajoutée. Plutôt que de figer le framework avec elle, REDA ajoute les nouveaux comportements sous forme d’interfaces globales distinctes, ce que Salesforce autorise. Un prestataire étend EInvoiceProvider et implémente les interfaces de capacité qu’il prend en charge ; le package principal détecte cette prise en charge avec instanceof et ignore simplement la capacité pour les prestataires qui ne l’implémentent pas.

Les trois types de données qu’elles échangent

• refin.EInvoiceEvent — une étape de la vie d’un document auprès de l’administration. Le package principal la rattache à un historique grâce à erpDocumentId, une valeur que votre prestataire inscrit dans l’enveloppe sortante et que l’administration renvoie en écho. status est normalisé en Accepted, Rejected, Cancelled ou InProgress — le package principal fonde sa logique de nouvelle tentative et d’état final sur cette valeur, jamais sur le responseCode brut. L’événement contient aussi notificationId, processType (Outbound / Inbound), responseMessage, fiscalUUID, fiscalNumber, une liste documents facultative, payload et eventDate.
• refin.EInvoiceDocument — une pièce : title, fileExtension ('xml' ou 'pdf'), base64Body et documentKind ('Legal', 'LegalResponse' ou 'Representation'). Le package principal la décode et la joint à l’historique et à la facture source sous forme de fichiers Salesforce, afin que les utilisateurs voient les pièces conformes sur l’enregistrement qu’ils utilisent déjà.
• refin.EInvoiceProvisionResult — success (par défaut false), externalId (l’identifiant côté prestataire) et message.

documentKind, processType et status sont tous de type String plutôt que des énumérations — délibérément, afin que l’ensemble des valeurs autorisées puisse s’étendre sans casser une signature globale figée. N’écrivez pas de switch exhaustif sur ces valeurs ; traitez celles que vous connaissez et laissez passer les autres.

Erreurs courantes à éviter

Pour les équipes qui développent une extension

• Implémentez la classe abstraite dans l’espace de noms de votre package ; enregistrez le nom pleinement qualifié de la classe dans l’enregistrement de configuration.
• Maîtrisez vos identifiants (informations d’identification nommées dans votre package), votre mappage d’API, votre sémantique d’erreur — renvoyez des résultats honnêtes ; le package principal les affiche dans le Statut de synchronisation et les historiques.
• Développez uniquement en vous appuyant sur le contrat — la surface globale documentée est la seule qui soit stable (les règles).

Pour aller plus loin

1. Importer des relevés bancaires — le processus dans lequel arrivent les flux.
2. Intégrations AppExchange — la vue d’ensemble de l’écosystème.
3. Développement Apex sur REDA — les règles de la surface globale.

Questions fréquentes