Événements de la demande¶

Chaque demande de signature génère des événements qui tracent son cycle de vie : sa création, l'envoi de l'invitation, l'ouverture d'une session de signature, les relances, chaque signature, l'achèvement, l'annulation, les notifications de fin. Ces événements sont visibles dans le Tableau de bord, et exposés par l'API publique via le paramètre expand de l'endpoint Get request status :

GET /api/v1/requests/{request_id}?expand=events&expand=emails

expand=events ajoute le tableau events à la réponse, expand=emails le tableau emails. Les deux champs sont toujours présents : null signifie « non demandé ». Un tableau vide signifie « demandé, mais rien à montrer » : le cas se présente pour emails, jamais pour events, qui porte au minimum l'événement created de la demande.

Types d'événements¶

Les 14 types actuels, dans l'ordre du cycle de vie d'une demande.

Champs d'un événement¶

Le tableau est trié par occurred_at croissant. Il n'est jamais vide lorsqu'il est demandé : toute demande porte au minimum son événement created.

occurred_at¶

Pour les sept types adossés à un e-mail (invite_sent, programmed_reminder_sent, manual_reminder_sent, cancelled_notice_sent, partial_signed_notice_sent, completed_notice_sent, signer_completed_notice_sent), occurred_at est l'instant où l'e-mail a été accepté par le fournisseur d'envoi. C'est l'horodatage que rapporte le webhook correspondant, et celui affiché dans le Tableau de bord.

Pour les quatre types d'action (signer_session_accessed, cancelled, public_link_generated, embed_token_generated), occurred_at est l'horodatage de l'événement lui-même : ces types ne sont adossés à aucun e-mail.

Les trois derniers types (created, signer_signed, completed) ne sont adossés ni à un e-mail ni à une ligne d'événement : ils rapportent l'horloge de la donnée qu'ils décrivent, respectivement la date de création de la demande (le champ created_at de la réponse), le signed_at du signataire concerné (celui de son entrée dans le tableau signers) et le signed_at de la demande. Le occurred_at de completed est donc toujours égal au signed_at de la réponse, et à l'horodatage du webhook request.completed.

link_expires_at¶

Cinq types portent un lien de signature et renseignent donc link_expires_at ; les neuf autres le laissent à null.

Pour la signature embarquée, un jeton expiré se renouvelle par l'endpoint Refresh iframe token ; voir Intégrer la signature sur votre application.

Types d'e-mail¶

expand=emails renvoie les e-mails que VoidSign a envoyés pour cette demande. Chaque ligne porte email_id, email_type, to_signer_id (le signataire destinataire, ou null lorsque le destinataire est un membre de votre équipe) et sent_at, l'instant de l'envoi, identique au occurred_at de l'événement correspondant. Le tableau est trié par sent_at croissant.

Ce qui n'apparaît pas dans emails¶

Seuls les e-mails effectivement remis au fournisseur d'envoi apparaissent : un envoi en échec n'apparaît ni dans emails ni dans events.

Les autres types d'e-mail que VoidSign envoie n'apparaissent jamais dans ce tableau, pour deux raisons distinctes :

• Ils ne concernent pas de demande de signature. Réinitialisation de mot de passe, invitations d'équipe et d'organisation, reçus de facturation, communications produit et messages d'accueil ne sont rattachés à aucune demande.
• Ils concernent la demande mais ne produisent pas d'événement. L'e-mail de code à usage unique (OTP) de signature est rattaché à la demande et au signataire, mais ne génère aucun événement de demande. Ce tableau étant construit à partir des événements, l'OTP n'y figure pas et n'est pas traçable via cet endpoint.

Exemples de chronologie¶

Demande à deux signataires¶

Le premier signataire demande à recevoir le document final une fois la demande entièrement signée.

sequenceDiagram
    participant I as Initiateur
    participant V@{ "type" : "entity" } as VoidSign
    participant S1 as Signataire 1
    participant S2 as Signataire 2

    I->>V: created
    V->>S1: invite_sent
    V->>S2: invite_sent
    S1->>V: signer_session_accessed
    S1->>V: signer_signed
    V->>I: partial_signed_notice_sent
    V->>S2: programmed_reminder_sent
    S2->>V: signer_session_accessed
    S2->>V: signer_signed
    V-->>V: completed
    V->>I: completed_notice_sent
    V->>S1: signer_completed_notice_sent

Lien public¶

Le signataire est invité par un lien généré depuis la plateforme, que vous lui transmettez par vos propres moyens. Aucun e-mail d'invitation n'est envoyé : pour ce signataire, public_link_generated remplace invite_sent.

sequenceDiagram
    participant I as Initiateur
    participant V@{ "type" : "entity" } as VoidSign
    participant S as Signataire

    I->>V: created (mode public_link)
    I->>V: [Génère un lien public]
    V-->>I: public_link_generated
    I->>S: [Transmet le lien]
    S->>V: signer_session_accessed
    S->>V: signer_signed
    V-->>V: completed
    V->>I: completed_notice_sent

Signature embarquée¶

Le signataire signe dans une iframe affichée par votre application. Le jeton est émis à la création de la demande et renvoyé dans la réponse. Aucun e-mail d'invitation n'est envoyé : pour ce signataire, embed_token_generated remplace invite_sent.

sequenceDiagram
    participant A as Votre application
    participant V@{ "type" : "entity" } as VoidSign
    participant S as Signataire

    A->>V: created (mode caller_embed)
    V-->>A: embed_token_generated
    A->>S: [Affiche l'iframe de signature]
    S->>V: signer_session_accessed
    S->>V: signer_signed
    V-->>V: completed