Aller au contenu principal

V1 vs V2 — aide-mémoire

L'API B2B coexiste en V1 et V2. Les versions sont sélectionnées par segment d'URL (/b2b/v1/…, /b2b/v2/…) ou par les en-têtes / query-string api-version, X-Version. Le SDK cible directement la version dans chaque méthode — pas de réglage global.

Règle simple : pour un nouveau projet, allez en V2 partout où la V2 existe. N'utilisez V1 que pour les CRUD unitaires (un employé à la fois) ou les domaines sans V2.

1. Cheat sheet par domaine​

DomaineV1V2Recommandation
Sync employésIEmployesClient.Add/Update/Delete (un par un)ISyncClient.Sync(syndicats, employes, objetsConsentement)V2 pour 10+ employés. V1 OK pour CRUD ponctuel.
Lecture adhésionsISignatureClient.GetSignaturesDepuis / GetSignaturesParIdExterneISignatureClient.GetSignaturesV2Depuis / …V2ParIdExterne / SearchSignaturesV2V2 — payload riche, filtres avancés, snapshots.
Recherche emploisIEmploisClient.GetAllEmplois (sans filtres)IEmploisClient.SearchEmplois(req)V2 dès que vous avez un filtre.
Suppression d'adhésion(n/a, V1 ne supprime pas)ISignatureClient.DeleteAdhesionByIdUnique / DeleteAdhesionsByMembreV2 uniquement.
Employeur, Syndicat, Emploi (CRUD)IEmployeursClient, ISyndicatsClient, IEmploisClient(pas de CRUD V2 distinct — DTO V2 nested via Sync)V1 pour les unitaires, V2 nested via Sync pour les batchs.
ObjetConsentementIObjetsConsentementClient(DTO V2 nested via Sync)V1 pour CRUD, V2 nested pour batch.
FormulairesIFormulaireClient.GetAllFormulaires(n/a)V1 uniquement, suffisant.
ConsentementsIConsentementClient(n/a)V1 uniquement.
CourrielsICourrielClient (5 méthodes)(n/a)V1 uniquement.
Champs utilisateurIChampUtilisateurClient(DTO V2 nested via ValeursChampUtilisateur dans B2BUpsertEmployeDtoV2)V1 pour la définition, V2 nested pour l'assignation.
ConciliationIConciliationClient(pas de client V2 distinct, mais les ValeursChampUtilisateur du DTO de réponse utilisent le type V2 polymorphe)V1 uniquement.
Votez (campagnes, votants, questions, liste électorale)Tous les clients Votez(n/a)V1 uniquement.
Test / sandboxITestClient(n/a)V1 uniquement.

2. Pièges fréquents​

Mélanger les DTOs V1 et V2​

B2BUpdateEmployeDto (V1) et B2BUpsertEmployeDtoV2 (V2) ne sont pas interchangeables :

ChampV1 (B2BUpdateEmployeDto)V2 (B2BUpsertEmployeDtoV2)
Matricule au niveau racineOuiNon — descend dans Emplois[].Matricule
IdentifiantExterneEmployeur au niveau racineOuiNon — descend dans Emplois[].IdentifiantExterneEmployeur
Adhesions[]NonOui (avec DateAdhesion)
Emplois[] (nested)NonOui (avec DateDebut, DateFin)
ValeursChampUtilisateur[] (écriture sync)Type B2BValeurChampUtilisateurItem (typé : ValeurString/ValeurDate/...)Type plat B2BValeurChampUtilisateurDto (NomChamp + Valeur string)
ValeursChampUtilisateur[] (lecture adhésion / webhook / conciliation)Type B2BValeurChampUtilisateurItem (multi-colonnes nullables, libellé pour les choix)Type polymorphe B2BValeurChampUtilisateur (sous-type par kind, IdExterneChoix pour les choix)

Symptôme : un sync V2 « marche » mais le matricule disparaît → vous passez un V1 dans une méthode V2. Recompilez avec types stricts.

Filtrer une adhésion V1 avec une date V2​

GetSignaturesDepuis(DateTime) (V1) ne renvoie qu'un sous-ensemble des champs. Si vous avez besoin de Paiement ou ASignatureManuscripte, passez en SearchSignaturesV2 (V2).

Supprimer côté V1​

Il n'y a pas d'endpoint V1 de suppression d'adhésion. Utilisez V2 — DeleteAdhesionByIdUnique ou DeleteAdhesionsByMembre.

Sync V1 (POST /b2b/v1/employe/sync)​

L'endpoint existe encore côté API mais n'est pas exposé par le SDK. Migrez vers ISyncClient.Sync (V2). Si votre intégration appelle directement l'URL V1 en HTTP brut, basculez : la V1 ne reçoit plus d'évolutions.

3. Quand rester en V1​

  • Vous maintenez une intégration existante stable, et la migration V2 n'apporte aucun bénéfice fonctionnel.
  • Vous faites du CRUD unitaire (création de membre par formulaire interne, par exemple).
  • Le domaine ne propose tout simplement pas de V2 (Votez, Courriel, Conciliation, Formulaires, Consentements).

4. Migration​

Voir le guide complet de migration V1 → V2. Cheminement type :

  1. Identifier les appels IEmployesClient.AddEmploye/Update/Delete qui pourraient être groupés. Les remplacer par ISyncClient.Sync.

  2. Remplacer ISignatureClient.GetSignaturesDepuis/ParIdExterne par les variantes V2 (SearchSignaturesV2 quand des filtres sont nécessaires).

  3. Réenregistrer un seul DI (AddMcmApiClient) — pas besoin de duplication.

  4. Vérifier que les valeurs de champs utilisateur sont sérialisées correctement :

    • Écriture (sync V2) : type plat B2BValeurChampUtilisateurDto (NomChamp + Valeur string).
    • Lecture (adhésions V2, webhook adhesion.signee, conciliation) : type polymorphe B2BValeurChampUtilisateur avec un sous-type par kind. Pour les choix, la valeur retournée est l'IdExterne du choix sélectionné — pas son libellé.

    Voir le guide de migration V2.

Voir aussi​