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
| Domaine | V1 | V2 | Recommandation |
|---|---|---|---|
| Sync employés | IEmployesClient.Add/Update/Delete (un par un) | ISyncClient.Sync(syndicats, employes, objetsConsentement) | V2 pour 10+ employés. V1 OK pour CRUD ponctuel. |
| Lecture adhésions | ISignatureClient.GetSignaturesDepuis / GetSignaturesParIdExterne | ISignatureClient.GetSignaturesV2Depuis / …V2ParIdExterne / SearchSignaturesV2 | V2 — payload riche, filtres avancés, snapshots. |
| Recherche emplois | IEmploisClient.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 / DeleteAdhesionsByMembre | V2 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. |
| ObjetConsentement | IObjetsConsentementClient | (DTO V2 nested via Sync) | V1 pour CRUD, V2 nested pour batch. |
| Formulaires | IFormulaireClient.GetAllFormulaires | (n/a) | V1 uniquement, suffisant. |
| Consentements | IConsentementClient | (n/a) | V1 uniquement. |
| Courriels | ICourrielClient (5 méthodes) | (n/a) | V1 uniquement. |
| Champs utilisateur | IChampUtilisateurClient | (DTO V2 nested via ValeursChampUtilisateur dans B2BUpsertEmployeDtoV2) | V1 pour la définition, V2 nested pour l'assignation. |
| Conciliation | IConciliationClient | (n/a) | V1 uniquement. |
| Votez (campagnes, votants, questions, liste électorale) | Tous les clients Votez | (n/a) | V1 uniquement. |
| Test / sandbox | ITestClient | (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 :
| Champ | V1 (B2BUpdateEmployeDto) | V2 (B2BUpsertEmployeDtoV2) |
|---|---|---|
Matricule au niveau racine | Oui | Non — descend dans Emplois[].Matricule |
IdentifiantExterneEmployeur au niveau racine | Oui | Non — descend dans Emplois[].IdentifiantExterneEmployeur |
Adhesions[] | Non | Oui (avec DateAdhesion) |
Emplois[] (nested) | Non | Oui (avec DateDebut, DateFin) |
ValeursChampUtilisateur[] | Type B2BValeurChampUtilisateurItem (typé : ValeurString/ValeurDate/...) | Type plat { NomChamp, Valeur } (toujours string) |
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 :
- Identifier les appels
IEmployesClient.AddEmploye/Update/Deletequi pourraient être groupés. Les remplacer parISyncClient.Sync. - Remplacer
ISignatureClient.GetSignaturesDepuis/ParIdExternepar les variantes V2 (SearchSignaturesV2quand des filtres sont nécessaires). - Réenregistrer un seul DI (
AddMcmApiClient) — pas besoin de duplication. - Vérifier que les valeurs de champs utilisateur sont sérialisées correctement (V1 utilise des propriétés typées, V2 utilise une chaîne unique
Valeur).