API et webhooks
Archivez depuis votre logiciel de paie, de facturation ou votre GED, et soyez notifié des événements de vos archives. Les clés d’API et les webhooks se créent dans l’application, page « API et webhooks », par un administrateur de l’organisation.
Authentification
Chaque appel porte une clé d’API dans l’en-tête Authorization. Une clé n’est affichée qu’à sa création ; elle a ses propres permissions, ses coffres et ses limites (requêtes par minute, dépôts par jour, budget mensuel de crédits, durée et taille maximales, formats, adresses IP autorisées, expiration).
Authorization: Bearer ma_live_8f3c… Adresse : https://api.mon-archivage.com. Les réponses sont en JSON (snake_case), les dates en ISO 8601 (UTC). Une clé régénérée garde son ancienne valeur valable 24 heures.
Clés de test
Pour construire votre intégration sans toucher à vos archives, créez une clé de l’environnement « Test » : elle commence par ma_test_ et s’utilise sur les mêmes routes. Ses requêtes sont vérifiées comme en production (permissions, coffres, formats, taille, durée, limites, doublons), mais :
- aucun fichier n’est conservé et aucun crédit n’est consommé ;
- les documents ne sont pas horodatés et n’apparaissent ni dans l’application ni au journal de l’organisation ;
- le téléchargement renvoie toujours le même fichier de test, la preuve et l’attestation sont marquées comme des tests ;
- les réponses portent
"test": trueet un numéroTEST-…; les données de test sont effacées après 30 jours. - les dépôts et prolongations ne partent que vers vos webhooks de l’environnement « Test », avec
"test": true; un webhook de production ne les reçoit jamais.
Une clé de test ne voit que les documents de test, une clé de production jamais. Pour recevoir un webhook pendant vos essais, utilisez « Envoyer un test » sur le webhook.
Déposer un document
curl https://api.mon-archivage.com/v1/documents \
-H "Authorization: Bearer ma_live_•••" \
-F file=@bulletin-octobre.pdf \
-F vault_id=6f1c2e1a-… \
-F type=PAYSLIP \
-F retention_years=5
→ 201 { "id": "…", "sha256": "4be1f0…", "proof_number": "PRV-2026-…",
"retain_until": "2031-11-17", "deposited_by": "API · Logiciel de paie" }Le fichier (PDF, Word, XML, PNG ou JPEG, 20 Mo au plus) est horodaté par une autorité qualifiée eIDAS, stocké en France et verrouillé jusqu’à son échéance. Chaque tranche de 5 ans entamée consomme 1 crédit. Types :
INVOICEFactureACCOUNTINGPièce comptableTAXDocument fiscalPAYSLIPBulletin de paieEMPLOYMENTContrat de travailCOMMERCIALContrat commercialBYLAWSStatuts et actes
Routes
| Route | Permission | Rôle |
|---|---|---|
| GET /v1/vaults | — | Les coffres de la clé. |
| GET /v1/documents | docs.read | Les documents, les plus récents d’abord. Paramètres : vault, q (titre, référence ou empreinte), limit (200 au plus), offset. |
| GET /v1/documents/{id} | docs.read | Un document. |
| POST /v1/documents | docs.create | Dépôt (multipart/form-data) : file, vault_id, type, retention_years, title et reference facultatifs. Consomme des crédits. |
| GET /v1/documents/{id}/file | docs.download | Le fichier d’origine. |
| GET /v1/documents/{id}/proof | docs.download | La preuve d’horodatage (JSON) et ses ré-horodatages, vérifiables hors ligne. |
| GET /v1/documents/{id}/certificate | docs.download | L’attestation de dépôt (PDF). |
| POST /v1/documents/{id}/extend | retention.extend | Prolonge la conservation de 5 ans pour 1 crédit (50 ans au plus depuis le dépôt). |
| GET /v1/journal | journal.read | Le journal des documents des coffres de la clé (limit, offset). |
Chaque dépôt, téléchargement et prolongation est inscrit au journal de l’organisation, au nom de la clé.
Erreurs
Au format Problem Details (RFC 9457) : status, code stable, title et detail en français.
| 401 invalid-api-key | Clé absente, inconnue, révoquée, suspendue ou expirée. |
| 403 api-key-permission | La clé n’a pas la permission de cette action. |
| 403 api-key-address-refused | L’adresse IP de l’appel n’est pas autorisée pour cette clé. |
| 400 api-key-refused | Le dépôt dépasse une limite de la clé (format, taille, durée). |
| 402 insufficient-credits | Le solde de crédits de l’organisation ne suffit pas. |
| 404 vault-not-found, document-not-found | Hors des coffres de la clé, ou inexistant. |
| 409 document-already-archived | Un fichier identique est déjà archivé. |
| 429 api-key-limit | Requêtes par minute, dépôts par jour ou budget mensuel atteints. |
Webhooks
À chaque événement choisi, mon archivage envoie un POST JSON à votre adresse HTTPS. Une réponse 2xx confirme la réception ; sinon l’envoi est retenté 5 fois sur 24 heures. Après 3 jours d’échecs consécutifs, le webhook est suspendu et les administrateurs prévenus.
| document.archived | Un document est archivé (dans l’app ou par l’API). |
| document.destroyed | Un document est détruit le lendemain de son échéance. |
| retention.due | Un document arrive à échéance dans 3 mois. |
| retention.extended | Une conservation est prolongée. |
| credits.low | Le solde de crédits devient bas. |
POST https://exemple.fr/webhooks/archivage
X-Archivage-Event: document.archived
X-Archivage-Delivery: 2b7c…
X-Archivage-Signature: t=1794931200,v1=5f0e…
{ "id": "…", "event": "document.archived", "test": false, "created_at": "2026-11-17T09:00:00Z",
"organization_id": "…", "data": { "id": "…", "title": "…", "sha256": "…", … } } Vérifiez la signature : calculez HMAC-SHA256(secret, t + "." + corps) en hexadécimal et comparez-la à une des valeurs v1 (deux pendant les 24 heures qui suivent un changement de secret). Refusez un t trop ancien.
// Node.js
const [t, ...v1] = header.split(',').map((p) => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
const valid = v1.includes(expected) && Date.now() / 1000 - Number(t) < 300;