Récupérer la traçabilité d'un processus

GET/document/roadmapclé publiquepuk_

Ce service renvoie la traçabilité complète d'un processus de signature : qui l'a créé, qui y participe et ce qui s'est passé à chaque instant. C'est le service à utiliser pour auditer un processus, reconstituer son historique en cas de réclamation ou alimenter un tableau de bord de suivi.

La réponse contient les données du processus, la liste des participants et un journal d'activité trié par ordre chronologique croissant, de l'événement le plus ancien au plus récent. Il n'y a ni pagination ni filtres : le processus complet est renvoyé en un seul appel.

Ce que couvre cette page

Cette page documente la traçabilité du processus : événements de notification, de relance, de lecture, de signature, d'approbation, de rejet, d'annulation et de réactivation. Pour consulter le statut actuel du processus et de chaque participant, utilisez GET /document ; pour lire les messages individuels d'une conversation WhatsApp, utilisez GET /whatsapp/records.

Authentification

Incluez votre clé publique dans l'en-tête Authorization.

Authorization: puk_xxx...

Paramètres de requête

Nom	Type	Description
`code`	String obligatoire	Code du processus dont vous souhaitez la traçabilité. 9 ou 10 caractères.

code accepte le code d'un contrat (9 caractères) ou d'un document (10 caractères) ; c'est la même valeur que renvoie GET /document dans le champ code.

Le processus doit appartenir à votre organisation

La requête est limitée à l'organisation propriétaire de la clé publique. Un code inexistant et un code appartenant à une autre organisation renvoient la même erreur, DOCUMENT_NOT_FOUND.

🧪 Exemples d'utilisation

astuce

Vous pouvez copier n'importe lequel des exemples selon votre langage préféré.

🔹 Récupérer la traçabilité d'un processus

curl
Python
Node.js

curl --location 'https://api.auco.ai/v1.5/ext/document/roadmap?code=CODEDOCUM' \
  --header 'Authorization: puk_yourPublicKey'

import requests

response = requests.get(
  "https://api.auco.ai/v1.5/ext/document/roadmap",
  headers={"Authorization": "puk_yourPublicKey"},
  params={"code": "CODEDOCUM"}
)
print(response.json())

const axios = require('axios');

axios
  .get('https://api.auco.ai/v1.5/ext/document/roadmap', {
    headers: { Authorization: 'puk_yourPublicKey' },
    params: { code: 'CODEDOCUM' },
  })
  .then((response) => console.log(response.data));

📥 Exemples de réponse

🔹 Processus signé via WhatsApp

{
  "name": "Contrat de services",
  "documentCode": "CODEDOCUM",
  "createdAt": "2026-06-26T21:48:42.755Z",
  "author": {
    "name": "Sarah Miller",
    "email": "example@auco.ai"
  },
  "participants": [
    {
      "id": "01",
      "name": "John Smith",
      "role": "SIGNER",
      "phone": "+573001234567"
    }
  ],
  "activityLog": [
    {
      "action": "NOTIFICATION_SIGN",
      "platform": "WHATSAPP",
      "participant": "01",
      "timestamp": "2026-06-26T21:48:44.307Z",
      "by": "+573001234567"
    },
    {
      "action": "PARTICIPANT_READ",
      "platform": "WHATSAPP",
      "participant": "01",
      "timestamp": "2026-06-26T21:49:47.523Z",
      "by": "+573001234567"
    },
    {
      "action": "PARTICIPANT_SIGN",
      "platform": "WHATSAPP",
      "participant": "01",
      "timestamp": "2026-06-26T21:50:10.940Z",
      "by": "+573001234567"
    }
  ]
}

🔸 Processus avec plusieurs participants, un rejet et une annulation

{
  "name": "Contrat de services",
  "documentCode": "CODEDOCUM",
  "createdAt": "2026-02-10T14:02:11.418Z",
  "author": {
    "name": "Sarah Miller",
    "email": "example@auco.ai"
  },
  "participants": [
    {
      "id": "01",
      "name": "John Smith",
      "role": "SIGNER",
      "email": "john@example.com",
      "phone": "+573001234567",
      "location": {
        "lat": 4.6533326179999995,
        "lng": -74.05834928765297,
        "street": "Calle 98 15-17, 110221 Bogotá, Colombia"
      },
      "ipAddress": "190.24.10.55 Bogotá, Bogota D.C., Colombia"
    },
    {
      "id": "02",
      "name": "Emily Clark",
      "role": "APPROVER",
      "email": "emily@example.com"
    },
    {
      "name": "Audit interne",
      "role": "READER",
      "email": "audit@example.com"
    }
  ],
  "activityLog": [
    {
      "action": "NOTIFICATION_SIGN",
      "platform": "EMAIL",
      "participant": "01",
      "timestamp": "2026-02-10T14:02:13.902Z",
      "by": "john@example.com"
    },
    {
      "action": "PARTICIPANT_READ",
      "platform": "EMAIL",
      "participant": "01",
      "timestamp": "2026-02-10T15:31:08.114Z",
      "by": "john@example.com",
      "ip": "190.24.10.55"
    },
    {
      "action": "PARTICIPANT_SIGN",
      "platform": "EMAIL",
      "participant": "01",
      "timestamp": "2026-02-10T15:33:44.660Z",
      "by": "john@example.com",
      "ip": "190.24.10.55"
    },
    {
      "action": "NOTIFICATION_APPROVER",
      "platform": "EMAIL",
      "participant": "02",
      "timestamp": "2026-02-10T15:33:47.201Z",
      "by": "emily@example.com"
    },
    {
      "action": "REMINDER_APPROVE",
      "platform": "EMAIL",
      "participant": "02",
      "timestamp": "2026-02-11T15:33:47.318Z",
      "by": "emily@example.com"
    },
    {
      "action": "PARTICIPANT_REJECT",
      "platform": "EMAIL",
      "participant": "02",
      "timestamp": "2026-02-11T16:10:29.775Z",
      "by": "emily@example.com",
      "message": "L'annexe 2 ne correspond pas au service souscrit."
    },
    {
      "action": "CANCEL_SIGN",
      "platform": "ARCHIVE",
      "participant": "ARCHIVE",
      "timestamp": "2026-02-11T16:44:02.031Z",
      "by": "example@auco.ai"
    }
  ]
}

🔸 Processus créé sans notification

Un processus créé avec notification: false existe et comporte des participants, mais n'a encore généré aucun événement : activityLog est renvoyé vide.

{
  "name": "Contrat de services",
  "documentCode": "CODEDOCUM",
  "createdAt": "2026-02-10T14:02:11.418Z",
  "author": {
    "name": "Sarah Miller",
    "email": "example@auco.ai"
  },
  "participants": [
    {
      "id": "01",
      "name": "John Smith",
      "role": "SIGNER",
      "email": "john@example.com"
    }
  ],
  "activityLog": []
}

📋 Champs de la réponse

Champ	Type	Description
`name`	String	Nom du processus, tel qu'il a été défini lors de sa création.
`documentCode`	String	Code du processus consulté. Il correspond au `code` que vous avez envoyé.
`createdAt`	String	Date et heure de création du processus, au format ISO 8601 et en UTC.
`author`	Object	Optionnel. Utilisateur de votre organisation ayant créé le processus. N'apparaît pas si le créateur n'existe plus en tant qu'utilisateur.
`author.name`	String	Nom du créateur du processus.
`author.email`	String	Optionnel. Adresse e-mail du créateur du processus.
`participants`	Array<Object>	Personnes impliquées dans le processus : signataires, approbateurs et lecteurs. Renvoyé vide (`[]`) si le processus n'a aucun participant.
`participants[].id`	String	Optionnel. Identifiant du participant au sein du processus. C'est la valeur vers laquelle pointe `activityLog[].participant`. Les lecteurs ne l'incluent pas, pas plus que les participants sans activité enregistrée.
`participants[].name`	String	Optionnel. Nom du participant.
`participants[].role`	String	Rôle du participant dans le processus. Voir Rôles.
`participants[].email`	String	Optionnel. Adresse e-mail du participant.
`participants[].phone`	String	Optionnel. Numéro de téléphone du participant au format international, avec l'indicatif du pays et le signe `+`.
`participants[].location`	Object	Optionnel. Localisation enregistrée pour le participant pendant le processus. N'apparaît que si Auco l'a capturée.
`participants[].location.lat`	Number	Latitude, en degrés décimaux.
`participants[].location.lng`	Number	Longitude, en degrés décimaux.
`participants[].location.street`	String	Adresse approximative déduite des coordonnées.
`participants[].ipAddress`	String	Optionnel. Texte libre contenant l'adresse IP enregistrée pour le participant. Il peut arriver sous plusieurs formats : l'IP seule, ou l'IP suivie de la localisation approximative qui en est déduite. Ne l'analysez pas comme une adresse IP simple.
`activityLog`	Array<Object>	Événements du processus, triés par ordre chronologique croissant : le premier élément est le plus ancien. Renvoyé vide (`[]`) s'il n'y a aucune activité.
`activityLog[].action`	String	Événement survenu. Voir Actions.
`activityLog[].platform`	String	Canal par lequel l'événement a eu lieu. Voir Plateformes.
`activityLog[].participant`	String	`id` du participant auquel appartient l'événement, ou la valeur spéciale `ARCHIVE` lorsque l'événement appartient au processus et non à une personne.
`activityLog[].timestamp`	String	Date et heure de l'événement, au format ISO 8601 et en UTC.
`activityLog[].by`	String	Optionnel. Identifiant avec lequel l'action a été effectuée ou auquel elle a été livrée : l'adresse e-mail lorsque `platform` vaut `EMAIL`, et le numéro de téléphone lorsqu'il vaut `WHATSAPP`.
`activityLog[].ip`	String	Optionnel. Adresse IP depuis laquelle l'événement a été enregistré. N'apparaît que lorsqu'Auco l'a reçue.
`activityLog[].message`	String	Optionnel. Texte associé à l'événement, par exemple le motif saisi par le participant lors d'un rejet.

Les champs optionnels n'arrivent que lorsqu'il y a des données

author, id, name, email, phone, location, ipAddress, by, ip, and message sont omis de la réponse lorsqu'il n'y a pas de valeur : ils n'arrivent ni sous forme de null ni de chaîne vide. Votre intégration doit vérifier que la clé existe avant de la lire, au lieu de supposer que l'objet a toujours la même forme.

participant n'est pas toujours une personne

activityLog[].participant est généralement l'id d'un élément de participants[], mais les événements qui concernent l'ensemble du processus arrivent avec participant: "ARCHIVE". Cette valeur ne correspond à aucun participants[].id : si vous essayez de la résoudre dans la liste des participants, vous ne trouverez aucune correspondance. Voir Événements au niveau du processus.

📖 Dictionnaire de traçabilité

Les trois colonnes que vous interprétez pour chaque événement sont action (ce qui s'est passé), platform (par quel canal) et participant (pour qui). Ces tableaux listent les valeurs qu'Auco émet aujourd'hui.

Le catalogue n'est pas fermé

Des valeurs de action, platform et role absentes de ces tableaux peuvent apparaître : le catalogue évolue avec le produit. Ne construisez pas votre intégration en supposant que la liste est fermée. Traitez une valeur inconnue comme un événement que vous ne pouvez pas encore classer — affichez-la telle quelle, journalisez-la — au lieu de l'ignorer ou de faire échouer votre traitement.

Actions (`activityLog[].action`)

Notifications envoyées par Auco

`action`	Signification
`NOTIFICATION_SIGN`	Invitation à signer envoyée
`NOTIFICATION_APPROVER`	Invitation à approuver envoyée
`NOTIFICATION_FINISH`	Notification de finalisation envoyée
`NOTIFICATION_FAILED_SIGN`	Échec de l'invitation à signer

Relances

`action`	Signification
`REMINDER_SIGN`	Relance de signature envoyée
`REMINDER_APPROVE`	Relance d'approbation envoyée
`REMINDER_UPLOAD`	Relance de téléversement
`REMINDER_PAYMENT`	Relance de paiement

Les relances peuvent provenir de la planification automatique du processus ou d'un envoi manuel via POST /document/reminder.

Actions des participants

`action`	Signification
`PARTICIPANT_READ`	Document consulté
`PARTICIPANT_SIGN`	Document signé
`PARTICIPANT_APPROVE`	Document approuvé
`PARTICIPANT_REJECT`	Document rejeté
`READ_PARTICIPANT`	Document consulté

READ_PARTICIPANT est équivalent à PARTICIPANT_READ

Certains processus enregistrent l'événement de lecture sous le nom READ_PARTICIPANT. Il signifie exactement la même chose que PARTICIPANT_READ : le participant a ouvert le document. Si vous classez les événements selon leur valeur action, traitez les deux comme un même événement.

Modifications du processus

`action`	Signification
`UPDATE_SIGNER`	Participant mis à jour
`UPDATE_SIGN`	Signature mise à jour
`CANCEL_SIGN`	Processus annulé
`REACTIVATION_SIGN`	Processus réactivé

Rôles (`participants[].role`)

Valeur	Signification	Description
`SIGNER`	Signataire	Doit signer le document. C'est le rôle par défaut.
`APPROVER`	Approbateur	Doit approuver ou rejeter le document, sans le signer.
`READER`	Lecteur	Reçoit le document pour le consulter ; ne signe ni n'approuve.

Le rôle est défini lors de la création du processus et renvoyé tel quel ; vous pouvez donc aussi rencontrer des valeurs propres à votre intégration.

Plateformes (`activityLog[].platform`)

Valeur	Description
`EMAIL`	L'événement a eu lieu par e-mail.
`WHATSAPP`	L'événement a eu lieu via WhatsApp.
`ARCHIVE`	L'événement a été réalisé depuis les archives web d'Auco, et non depuis un canal vers un participant.

Lorsque platform vaut WHATSAPP, vous pouvez obtenir le détail de la conversation — les messages et leurs statuts de livraison — avec GET /whatsapp/records.

Événements au niveau du processus (`participant: "ARCHIVE"`)

Certains événements n'appartiennent pas à un participant mais au processus dans son ensemble : une annulation effectuée depuis les archives web d'Auco, par exemple. Ces événements arrivent avec participant: "ARCHIVE", et leur champ by identifie l'utilisateur de votre organisation qui a effectué l'action, et non un signataire.

Traitez-les comme des événements au niveau du processus : n'essayez pas de résoudre ARCHIVE par rapport à participants[].id, car il n'y aura jamais de correspondance.

⚠️ Réponses d'erreur

Code	Description
400	Erreur de validation sur le paramètre `code` (manquant, ou dont la longueur n'est pas comprise entre 9 et 10 caractères), ou processus introuvable (`DOCUMENT_NOT_FOUND`).
401	Authentification invalide ou manquante

DOCUMENT_NOT_FOUND est renvoyé lorsque le processus n'existe pas ou n'appartient pas à l'organisation de la clé publique avec laquelle vous effectuez la requête.

Authentification​

Paramètres de requête​

🧪 Exemples d'utilisation​

🔹 Récupérer la traçabilité d'un processus​

📥 Exemples de réponse​

🔹 Processus signé via WhatsApp​

🔸 Processus avec plusieurs participants, un rejet et une annulation​

🔸 Processus créé sans notification​

📋 Champs de la réponse​

📖 Dictionnaire de traçabilité​

Actions (activityLog[].action)​

Rôles (participants[].role)​

Plateformes (activityLog[].platform)​

Événements au niveau du processus (participant: "ARCHIVE")​

⚠️ Réponses d'erreur​