Piste d'Audit

Chaque demande de signature dans Firma dispose d’une piste d’audit complète. Chaque affichage de document, interaction avec un champ, signature, refus et action administrative est enregistré avec horodatage, identité de l’acteur et adresses IP. Cas d’usage courants :

Conformité et preuve juridique — prouver qui a signé quoi, quand et depuis où
Débogage des problèmes de signataires — voir exactement ce qu’un destinataire a fait pendant sa session de signature
Reporting interne — suivre les actions administratives comme la création, les modifications et les annulations

La piste d’audit capture deux catégories d’événements :

Événements signataire — affichages de document, interactions avec les champs, signature, refus, téléchargements de certificat
Événements administrateur — création, modifications, envoi, annulation, renvoi (via le tableau de bord ou l’API)

Chaque événement inclut un horodatage, une description lisible par un humain, l’identité de l’acteur et (pour les événements signataire) l’adresse IP du signataire.

Consulter la piste d’audit dans le tableau de bord

Ouvrez n’importe quelle demande de signature dans le tableau de bord Firma et cliquez sur l’onglet Piste d’Audit. Vous verrez une chronologie de tous les événements, avec les actions des signataires et des administrateurs visuellement distinguées. Les événements répétitifs consécutifs (comme le défilement ou les interactions répétées avec un champ) sont automatiquement condensés avec un indicateur de nombre.

Récupérer la piste d’audit via l’API

Utilisez le endpoint audit pour récupérer l’historique complet des événements d’une demande de signature :

GET /signing-requests/{id}/audit

curl

curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"

Node.js

const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);

Python

import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]

Exemple de réponse

{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}

Champs de la réponse

Champ	Type	Description
`id`	`uuid`	ID de l’événement
`timestamp`	`datetime`	Quand l’événement s’est produit
`source`	`string`	`"signer"` ou `"admin"`
`event`	`string`	Identifiant du type d’événement (voir la référence des événements ci-dessous)
`description`	`string`	Description lisible de l’événement
`actor`	`object \| null`	Qui a effectué l’action (voir ci-dessous)
`ip_address`	`string \| null`	Adresse IP du signataire (événements signataire uniquement)
`details`	`object \| null`	Métadonnées spécifiques à l’événement
`condensed_count`	`integer`	Présent lorsque des événements identiques consécutifs du même acteur sont regroupés

Comprendre les sources d’événements

Le champ source indique si un événement provient d’un signataire ou d’un administrateur, et le champ actor a une forme différente selon le cas.

Événements signataire

Les événements avec source: "signer" sont des actions effectuées par les destinataires pendant le flux de signature. L’objet actor contient le name et l’email du signataire. Le champ ip_address est renseigné.

{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}

Événements administrateur

Les événements avec source: "admin" sont des actions effectuées via le tableau de bord ou l’API. L’objet actor contient un champ type ("api_key" ou "user") et éventuellement un user_id. Le champ ip_address est null.

{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}

{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}

Suivi en temps réel via les webhooks

Si vous avez besoin d’une notification en temps réel des événements signataire plutôt que d’interroger le endpoint audit, Firma prend en charge les webhooks. Consultez le guide Webhooks pour les instructions de configuration.

Référence des événements

Cycle de vie du document

Événement	Description	A des `details`
`document_opened`	Document ouvert	Non
`document_viewed`	Document consulté	Non
`document_saved`	Valeurs des champs enregistrées	Non
`document_finished`	Signature terminée	Non
`document_signed`	Document signé	Non
`document_hidden`	Page quittée	Non
`document_visible`	Retour sur la page	Non
`document_closed`	Document fermé	Non

Signature et vérification

Événement	Description	A des `details`
`signature_finalized`	Signature finalisée	Non
`signing_declined`	Signature refusée	Non
`terms_accepted`	Conditions générales acceptées	Non
`otp_verified`	Identité vérifiée via OTP	Non
`certificate_download`	Certificat téléchargé	Non

Interactions avec les champs

Les interactions avec les champs sont suivies comme des événements field_interaction. L’objet details contient l’action spécifique et les métadonnées du champ.

Action	Description
`field_focused`	Champ sélectionné
`field_completed`	Champ complété pour la première fois
`field_modified`	Valeur d’un champ existant modifiée
`field_cleared`	Valeur d’un champ effacée
`field_blur`	Édition du champ terminée

L’objet details pour les interactions avec les champs inclut :

Champ	Type	Description
`field_type`	`string`	Type de champ (signature, texte, date, etc.)
`action`	`string`	L’action spécifique du tableau ci-dessus
`interaction_count`	`integer`	Nombre de fois où ce champ a été utilisé
`value_length`	`integer`	Longueur de la valeur du champ (le cas échéant)
`time_spent_ms`	`integer`	Temps passé sur le champ en millisecondes (le cas échéant)

Événement	Description	A des `details`
`page_viewed`	Page spécifique consultée	Oui — `page_number`
`document_scrolled`	Défilement jusqu’à une page	Oui — `page_number`
`navigation_action`	Navigation dans le document	Oui — `action` (`next_page`, `prev_page`, `go_to_page`)
`zoom_changed`	Niveau de zoom modifié	Non
`modal_interaction`	Ouverture ou fermeture d’une boîte de dialogue	Oui — `modal_type`, `action`

Activité administrateur

Les événements administrateur utilisent event: "activity" avec un champ description lisible par un humain qui décrit l’action effectuée (par exemple, “Created signing request via API”, “Sent signing request”, “Cancelled signing request”).

​Consulter la piste d’audit dans le tableau de bord

​Récupérer la piste d’audit via l’API

​curl

​Node.js

​Python

​Exemple de réponse

​Champs de la réponse

​Comprendre les sources d’événements

​Événements signataire

​Événements administrateur

​Suivi en temps réel via les webhooks

​Référence des événements

​Cycle de vie du document

​Signature et vérification

​Interactions avec les champs

​Navigation

​Activité administrateur