Migration V1 > V2

Cette page s'adresse à une intégration écrite pour la V1 de l'API, celle de 2025, et à l'agent IA qu'on chargerait de la passer à la V2, celle que décrit cette documentation. Chaque rupture dit ce qui change et ce qu'il faut faire. Les routes de la V1 sont écrites sans adresse (POST Account/token) ; celles de la V2 avec la sienne (POST https://staging-api.docage.com/Account/CreateToken). Ce qui ne change pas est à la fin de la page.

L'essentiel

Les ruptures qui arrêtent une intégration, à traiter d'abord :

• La connexion : POST Account/token devient POST https://staging-api.docage.com/Account/CreateToken, et les jetons de la V1 ne valent plus — voir S'authentifier.
• Le rôle d'un participant : un participant envoyé sans MemberRole n'a plus aucune action, et le lancement du parcours est refusé — voir Les participants et les observateurs.
• Le statut d'un parcours : Status cède la place à GlobalStatus, dont les nombres diffèrent — voir Les parcours.
• Les téléchargements : authentifiés, ils rendent le fichier lui-même, plus une chaîne en base64 — voir Les documents d'un parcours.
• La lecture d'une fiche : GET Contacts/ById/{id} devient GET https://staging-api.docage.com/Contacts/{id}, sur tous les types de fiches — voir Lire et écrire une fiche.
• Les codes de refus : 404, 403, 409 et 422, là où la V1 rendait 409 ou 400 — voir Les codes de refus.
• Les listes : un critère qui ne se lit pas ne retient plus aucune fiche — voir Les listes.
• Les webhooks : envoyés par une file, signés, et le statut d'un parcours s'y lit en GlobalStatus ; vos abonnements sont repris, mais pas l'adresse posée sur un parcours en cours, et l'ancien nom TransactionStatusTarget est refusé — voir Les webhooks.

Chaque route déplacée ou retirée, avec ce qui la remplace, est dans un seul tableau.

S'authentifier

• POST Account/token devient POST https://staging-api.docage.com/Account/CreateToken, sans alias : l'ancienne adresse répond 404. Le corps ne change pas (Email, Password), la réponse non plus (JWToken, DocageUser). Voir S'authentifier.
• Une connexion refusée répond 400. Un compte bloqué est refusé dès la connexion, là où la V1 rendait un jeton qui échouait ensuite, et dix mots de passe faux de suite verrouillent le compte dix minutes. Une organisation qui impose son fournisseur d'identité (authentification unique) refuse le mot de passe (403, sso_required) : passez alors par la clé API.
• Les jetons de la V1 ne sont plus acceptés : demandez-en un nouveau. En règle générale, redemandez un jeton à tout 401. Un jeton est désormais signé en RS256 ; sa clé publique se lit à https://staging-api.docage.com/.well-known/jwks.json, pour qui veut le vérifier lui-même.
• Un jeton vaut toujours 24 heures et se prolonge par POST https://staging-api.docage.com/Account/refreshtoken, qui remplace le jeton prolongé.
• Les connexions s'ajoutent au lieu de s'évincer : deux jetons du même utilisateur, employés dans la même minute, font deux connexions simultanées, facturées à l'heure selon les conditions de l'organisation. Gardez un seul jeton et prolongez-le — ou authentifiez-vous par la clé API, qui n'ouvre aucune session et n'est jamais comptée comme une connexion.
• La clé API de la V1 reste valable, en Basic (email:clé). La générer ou la retirer se fait désormais en PUT : PUT https://staging-api.docage.com/DocageUsers/GenerateApiKey/{id} et PUT https://staging-api.docage.com/DocageUsers/RemoveApiKey/{id} (l'ancien GET répond 405), et demande le droit d'administrer l'utilisateur. La clé n'est plus rendue dans la fiche d'un utilisateur, ni à la connexion : elle se lit par GET https://staging-api.docage.com/DocageUsers/ApiKey/{id}.

Les codes de refus

La V2 rend le même code pour le même cas, sur toutes ses routes — voir Erreurs :

• GET https://staging-api.docage.com/Contacts/{id} — comme toute lecture par identifiant — rend 200 et null pour une fiche inconnue et pour une fiche invisible (la V1 répondait 400 pour la seconde) : testez le corps, pas seulement le code.
• Les messages sont rédigés dans la langue de l'utilisateur authentifié, là où la V1 mêlait l'anglais et le français. Décidez d'après le code, jamais d'après le texte.

Lire et écrire une fiche

• GET Contacts/ById/{id} devient GET https://staging-api.docage.com/Contacts/{id}, et de même sur tous les types de fiches (GET https://staging-api.docage.com/Transactions/{id}, GET https://staging-api.docage.com/PipelineItems/{id}…) et pour un droit (GET Rights/ById/{id}), sans alias : l'ancienne adresse répond 404. C'est désormais l'adresse de la fiche elle-même, celle de sa modification (PUT) et de sa suppression (DELETE).
• Créer depuis un modèle : GET …/CreateEntityFromTemplate/{templateid} prend un second segment, obligatoire — GET https://staging-api.docage.com/Contacts/CreateEntityFromTemplate/{templateid}/{createTemplate}, avec false pour composer une fiche et true pour composer un modèle. L'ancienne adresse répond 404, sur tous les types. La fiche rendue est composée, pas enregistrée : c'est le corps à envoyer ensuite par POST. Un modèle inconnu ou invisible répond 404.
• Dupliquer : POST https://staging-api.docage.com/Contacts/Duplicate rend un objet — pour chaque fiche source, son identifiant en clé et, en valeur, l'identifiant de sa copie ou le motif de l'échec —, là où la V1 ne rendait rien. Il ne répond 400 que si aucune copie n'a réussi.
• Modifier : PUT https://staging-api.docage.com/Contacts/{id} reçoit toujours les seules propriétés modifiées. Une propriété disparue ou réservée au serveur est ignorée sans erreur — voir La forme des données. Un modèle système ne se modifie pas (403).
• L'historique d'une fiche se lit par GET https://staging-api.docage.com/Contacts/History/{id}, sur chaque type de fiche. Les routes Logs/… de la V1, qui servaient en réalité les contacts, répondent 404.

Les listes

• Le corps d'une lecture de liste exige l'en-tête Content-Type: application/json (415 sans lui) ; un JSON mal formé répond 400, là où la V1 l'ignorait et rendait toute la liste.
• Un filtre ne s'élargit plus : un critère qui ne se lit pas ne retient aucune fiche, là où la V1 l'écartait et rendait davantage. Not est une vraie négation, un opérateur inconnu écarte son opérande, et un critère sans Comparison vaut =. Relisez vos filtres : une liste devenue vide trahit un nom de propriété faux.
• Un filtre ou un tri que la base refuse répond 500, avec un message, là où la V1 rendait une liste vide.
• Une liste se lit aussi par la méthode QUERY, avec le même corps — la forme à préférer : voir Lire des listes.

Les parcours

Le statut. Status est remplacé par GlobalStatus, dont les nombres diffèrent pour un même sens. Status reste rendu, mais ne se lit plus.

• La lecture groupée des statuts s'appelle POST https://staging-api.docage.com/Transactions/Statuses (l'ancien nom, TransactionsStatus, reste servi) : elle rend une liste [{ "Id", "Status" }] de GlobalStatus, au lieu d'un dictionnaire, pour cent identifiants au plus.
• GET https://staging-api.docage.com/Transactions/Status/{id} ne rend plus FormToFill : un parcours qui attend un formulaire est Active.
• Les statuts que liste Transactions/GetAllStatusForZapier sont ceux de GlobalStatus.

La signature. Les parcours sont signés par Docage : SignatureProvider vaut 0 et ne s'écrit plus (en V1, 0 désignait un autre prestataire). Le fichier de preuve d'un parcours signé en V2 n'a plus la forme de celui de la V1.

Les emails d'un parcours. Les quatorze textes d'email d'un parcours (InvitationEmailSubject, InvitationEmailBody…) sont acceptés mais plus lus par aucun envoi : la personnalisation passe par MailSettings — voir Personnaliser l'email d'invitation.

Les autres changements.

• Webhook, l'adresse posée sur un parcours ou un formulaire, est retirée : celle d'un modèle devient un abonnement, celle d'un parcours qui n'est pas un modèle n'est pas reprise — voir Les webhooks.
• Transactions/ByName/{name}/{isTemplate} devient GET https://staging-api.docage.com/Transactions/ByName/{name} : isTemplate passe dans la requête (?isTemplate=true pour chercher un modèle, les parcours sinon) ; plusieurs parcours du même nom répondent 409 — lisez alors la liste filtrée par le nom.
• Annuler (PUT https://staging-api.docage.com/Transactions/Abort/{id}) et relancer (PUT https://staging-api.docage.com/Transactions/SendReminders/{id}) demandent le droit de modifier le parcours, plus seulement de le voir (403).
• Les lots de parcours (Transactions/batch/{templateId}, TransactionBatchEntries) sont remplacés par une campagne « Générer des parcours » : POST https://staging-api.docage.com/Campaigns, puis POST https://staging-api.docage.com/Campaigns/{id}/Launch — voir Lancer une campagne.
• La signature de plusieurs parcours en une fois passe par POST https://staging-api.docage.com/Transactions/ConsentBatches — voir Signer plusieurs parcours. Elle demande la session du signataire : une clé API y est refusée (403).
• Une création complète (POST https://staging-api.docage.com/Transactions/CreateFullTransaction) garde ses clés, mais enregistre le parcours en brouillon avant de l'envoyer : un envoi refusé laisse le brouillon, que vous relancez par POST https://staging-api.docage.com/Transactions/LaunchTransaction/{id} au lieu de le recréer.
• Propriétés renommées : IsBatchCompatible devient IsCampaignCompatible ; MemberSummariesJson et FileSummariesJson deviennent MemberSummaries et FileSummaries, des listes et non plus du texte ; DocageLinks devient Links, d'une autre forme.

Les participants et les observateurs

• MemberRole vaut désormais -1 par défaut : les actions du participant décident de son rôle. Un participant envoyé sans MemberRole n'a aucune action, et le lancement est refusé. Envoyez 0 (signataire) ou 1 (validateur) — la forme de la V1, encore convertie en actions tant que le parcours n'en a aucune —, ou ses actions explicites : TransactionMemberActions, ou POST https://staging-api.docage.com/TransactionActions (Type : 0 formulaire, 1 remplissage d'un document, 2 validation, 3 signature, 4 paiement, 5 vérification d'identité).
• À la lecture, un participant créé dans l'application a son MemberRole à -1 : ne déduisez plus son rôle de MemberRole, lisez ses actions (TransactionMemberActions, HasSignature…).
• IsSignatory, IsValidator, IsFollower, IsFormFiller et leurs rangs sont retirés, et ignorés : l'ordre se dit par Order.
• Le FormId d'un participant est retiré : son formulaire est une action Formulaire (Type 0), qui porte le FormId.
• MemberStatus n'est plus mis à jour au-delà du début : lisez le statut du parcours, ou celui de chaque action.
• SignUrl est toujours vide : un participant agit depuis le lien de son invitation. Les routes de ses écrans (TransactionMembers/FillForm, CanSign, CanFillForm, NextStep…) sont retirées.
• NotifySignatureCompletionByMail et NotifyTransactionRefusalByMail valent false par défaut, là où la V1 prévenait le participant de la signature et du refus : envoyez-les à true pour garder ce comportement. Les drapeaux de la V1, NotifySignature et NotifyRefusal, sont encore convertis quand ils valent true.
• WillBeReplacedByCreator devient ReplaceByCreator ; MemberType devient PersonType (mêmes valeurs, plus 5 pour un groupe).
• L'adresse email d'un participant est contrôlée (400 pour une adresse mal formée), et son nom convivial (FriendlyName) est unique dans le parcours (409 à la modification d'un nom déjà pris).
• Les observateurs ne sont plus des participants : ils ont leurs routes (POST https://staging-api.docage.com/TransactionObservers…) et n'apparaissent plus dans TransactionMembers. Un participant envoyé avec MemberRole à 2 devient un observateur, sous le même identifiant.

Les documents d'un parcours

• TransactionDocumentId devient InitialDocumentId, sans alias : le document ou le modèle choisi. FinalDocumentId, le document produit, est écrit par le serveur.
• À l'envoi d'un document, son format se lit sur son contenu — un PDF passe tel quel, une image ou un document Word est converti, tout autre format est refusé (400) ; FileExtension n'est plus lu. Ajouter un document demande le droit de modifier le parcours (403), qui ne doit pas être lancé.
• Les téléchargements demandent une authentification et rendent le fichier lui-même, avec son type et son nom, au lieu d'une chaîne en base64 : GET https://staging-api.docage.com/TransactionFiles/Download/{id} (ex-DownloadDocument), GET https://staging-api.docage.com/Transactions/DownloadDocuments/{id}, GET https://staging-api.docage.com/Transactions/DownloadDocumentsAndProofFile/{id} et GET https://staging-api.docage.com/Transactions/DownloadProofFile/{id}/{format}. Un document rédigé dans l'application, sans PDF, part en Word (en Excel pour un tableur) ; ?format=pdf le demande en PDF. Seul l'aperçu, GET https://staging-api.docage.com/TransactionFiles/GetPreview/{id}, reste une chaîne en base64. Le rapport d'une vérification d'identité ne se télécharge que par le créateur du parcours (403).
• La lecture anonyme des fichiers d'un parcours (Transactions/GetTransactionFiles) est retirée : GET https://staging-api.docage.com/Transactions/{id}, authentifiée.
• Un fichier peut avoir deux types de plus, posés par le serveur : Type 2, la preuve, et 3, le rapport d'une vérification d'identité.
• Les emplacements de signature s'appellent TransactionFields, et l'ancien préfixe TransactionMemberSignatureLocations reste servi ; SignatureLocations/… répond 404. Un corps de la V1 passe tel quel : FieldType vaut 0, la signature, sa valeur d'office.

Les autres fiches

• Documents : Variables devient Fields — voir les définitions des objets.
• Formulaires : Webhook et Type sont retirés, et le filtre FormType d'une liste est ignoré. L'envoi d'une réponse (Forms/SubmitForm/{formId}) ne lit que les champs du formulaire, et refuse un numéro de téléphone invalide (400).
• Organisations : les tarifs (PriceFor…), ClosedModules et les réglages de débit des crédits ne s'écrivent plus ; ils viennent de la politique de l'organisation. Créer une organisation cliente (POST Organizations) demande d'être gestionnaire de clients de l'intégrateur, qui doit avoir une politique de marque par défaut (400 sinon, avec le motif).
• Utilisateurs : POST DocageUsers/SendResetPasswordLink/{id} répond désormais 200, sans corps, et non plus par une redirection.
• Comptes email : leur partage se désigne par MailboxId, sur la fiche de l'utilisateur ou de l'organisation — voir le tableau des routes. GET Mailboxes/ByOrganizationId/{id} et GET Mailboxes/ByUserId/{id} rendent désormais le même objet en application/json, et non plus en text/plain.
• Droits : POST https://staging-api.docage.com/Rights demande d'administrer la fiche (403 sinon), là où la V1 se contentait du droit de la modifier.
• Commandes : ClientId, IntegratorId, OrderedCredits, FreeCredits et CreditsQuantity ne s'écrivent plus par PUT Orders/{id} ; IsEditable est vrai tant que la commande n'est ni traitée, ni payée, ni facturée, ni rejetée.
• Relevés de crédits : ils sortent de la référence, mais restent servis ; CreditReports/ById/{id} devient CreditReports/{id}.
• Contacts : un contact qui ressemble à une fiche existante peut être refusé (409) selon les règles de dédoublonnage de l'organisation ; le corps liste les fiches proches.
• Journal : une mise à la corbeille s'écrit MovedToTrash (12), plus Modification (2).

Les webhooks

• Les envois partent après l'enregistrement, par une file, et sont signés selon Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature) — vérifiez la signature : voir Webhooks.
• Seul un code 2xx est un succès ; une redirection (3xx) est un échec. Un envoi en échec est retenté dix fois, sur près de quatre jours ; 410, ou 72 heures d'échecs, met le webhook en panne.
• L'adresse d'un webhook neuf ou modifié est en HTTPS, publique.
• Un webhook ne reçoit que ce que son auteur voit : la fiche est projetée avec ses droits, là où la V1 prenait ceux du premier administrateur de l'organisation. En échange, tout utilisateur peut s'abonner à toutes les fiches d'un type, sans administrer l'organisation.
• Les portées s'additionnent : un abonnement à toutes les fiches d'un type, un autre aux fiches tirées d'un modèle et un troisième à une fiche partent chacun, sans que l'un masque l'autre ; un abonnement posé sur une fiche ne vaut que pour elle.
• Un abonnement neuf reçoit l'enveloppe décrite par la page Webhooks (« v2 »), sauf "PayloadVersion": 1.
• GET Webhooks?sortOrder= devient GET https://staging-api.docage.com/Webhooks, la liste générique : elle rend des fiches Webhook, et ne lit plus sortOrder — le tri passe par le corps, comme pour toute liste.
• DELETE Webhooks/{id} met désormais le webhook à la corbeille (PUT https://staging-api.docage.com/Webhooks/BatchRestore l'en sort), 404 s'il n'existe pas ; DELETE https://staging-api.docage.com/Webhooks/byurl ne retire que les webhooks que l'utilisateur a le droit de supprimer, et les met à la corbeille.
• L'événement 12 (une fiche rangée dans un classeur ou retirée) part désormais ; 30, le statut d'un email, est nouveau.

Ce qui est repris de la V1.

• Vos abonnements : même identifiant, même adresse, même type, même événement. Leur cible de statut passe dans l'échelle de GlobalStatus (voir le tableau des statuts) : un abonnement à « Signé » (5) ou à « Validé » (4) attend désormais « Terminé » (3). Ils reçoivent toujours la fiche seule (charge « v1 »), avec ses propriétés de la V2 (GlobalStatus, les actions, les observateurs), désormais signée : le secret de chacun se lit par POST https://staging-api.docage.com/Webhooks/{id}/Secret/Reveal. Un abonnement posé sur un parcours clos, à la corbeille ou disparu n'est pas repris : il ne se déclencherait plus.
• L'adresse posée sur un modèle de parcours ou de formulaire (Webhook, retirée) : elle devient un abonnement aux fiches tirées de ce modèle, en enveloppe v2 — les parcours appellent à chaque changement de statut et à chaque modification, les réponses du formulaire à leur création.

Ce qui ne l'est pas.

• L'adresse posée sur un parcours ou un formulaire qui n'est pas un modèle : un parcours en cours au passage à la V2 n'appelle plus son adresse. Pour le suivre, abonnez-vous à lui — un webhook sur ce seul parcours : "Scope": 2, et son identifiant dans ScopeRecordId — ou lisez son statut, GET https://staging-api.docage.com/Transactions/Status/{id}.
• L'ancien nom de la cible de statut : le corps d'abonnement de la V1 (Action, EntityTypeName, une clé …Id) est encore accepté par POST https://staging-api.docage.com/Webhooks, et traduit, mais TransactionStatusTarget n'est pas lu. Écrivez TransactionGlobalStatusTarget, avec les nombres de GlobalStatus (-100 pour tous les statuts). Un abonnement à un changement de statut (Action à 20) qui ne nomme sa cible que par l'ancien nom est refusé (422, la réponse nomme TransactionGlobalStatusTarget) : accepté, il ne partirait jamais. Sans aucun des deux noms, la cible vaut 0 (brouillon), et l'abonnement ne part jamais non plus. Une autre action ne lit pas la cible de statut : un corps qui porte encore l'ancien nom y est accepté. Les autres refus répondent aussi 422 (adresse qui n'est pas en HTTPS, type inconnu…), une fiche de périmètre introuvable 404.

La forme des données

• Une date rendue a toujours ses millisecondes (2026-11-04T09:12:05.000Z). Une date envoyée sans fuseau est lue en UTC ; la forme \/Date(…)\/ est refusée.
• Un nombre entier s'écrit sans décimale (12, pas 12.0). Envoyez un nombre en nombre (12.5), jamais en texte ("12.5").
• Un identifiant s'envoie sous sa forme à tirets (3f2c8a1e-…) ; un JSON qui porte une virgule finale ou un commentaire est refusé (400).
• Un numéro de téléphone est rendu au format international (+33612345678) ; un numéro envoyé y est ramené.
• Une propriété disparue ou réservée au serveur est ignorée sans erreur : relisez la fiche quand la valeur compte — voir Créer et modifier.

Les routes déplacées ou retirées

Une route déplacée répond 404 à son ancienne adresse, sans alias ; une route qui modifie ne se sert plus en GET, et l'ancien GET répond 405.

Ce qui ne change pas

• Le JSON en PascalCase, les énumérations en nombres (leur nom accepté à l'entrée), les dates en UTC suffixées de Z, l'en-tête Docage-TotalItems, le filtre (Filter) et la pagination (Skip, Take).
• Les routes génériques de chaque type de fiche, sauf la lecture d'une fiche et la création depuis un modèle (voir plus haut) : sa liste, POST, PUT https://staging-api.docage.com/Contacts/{id} (les seules propriétés modifiées), DELETE, BatchDelete.
• La clé API, les jetons de 24 heures et leur prolongation.
• La création d'un parcours en une requête, POST https://staging-api.docage.com/Transactions/CreateFullTransaction, avec ses clés, et POST https://staging-api.docage.com/Transactions/LaunchTransaction/{id} ; la lecture du statut d'un parcours, GET https://staging-api.docage.com/Transactions/Status/{id}.
• Le contrat de Zapier : POST https://staging-api.docage.com/Webhooks (le corps de la V1 y est encore traduit, sauf l'ancien nom TransactionStatusTarget, refusé sur un changement de statut — voir Les webhooks), DELETE https://staging-api.docage.com/Webhooks/byurl.
• Les anciennes adresses gardées, sans date de fin : TransactionMemberSignatureLocations, TransactionFiles/GetContent (qui rend ce que rend GET https://staging-api.docage.com/TransactionFiles/Download/{id}), Transactions/TransactionsStatus. Leur retrait sera annoncé comme une rupture.