> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Piste d'Audit

> Suivez chaque action sur une demande de signature à des fins de conformité et de reporting.

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

```bash theme={null}
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

```js theme={null}
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

```python theme={null}
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

```json theme={null}
{
  "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](#event-reference) 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é.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={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](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) |

### Navigation

| É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").