External API reference (v2)

Complete reference of the external public API (/api/external/v2/*), rendered from a versioned OpenAPI 3.0 snapshot. The API is regional: servers are https://api.eu.mearchiver.com (EU) and https://api.us.mearchiver.com (US). The v1 API (/api/external/v1/*) is removed (returns 410 Gone).

MEA — API externe v2 v2.0.0

API REST publique de MEA (My Electronic Archiver) destinée aux intégrations tierces (ERP, applications métier). Authentification par clé scopée via l'en-tête `X-Api-Key: mea_ext_{prefix}_{secret}` (scheme `ExternalApiKey`). Toutes les réponses suivent l'enveloppe `{ success, data, message? }` et utilisent le `snake_case` JSON. Limitation de débit : fenêtre fixe de 1 minute par clé d'API, 60 requêtes/minute par défaut (`429 RATE_LIMIT_EXCEEDED`). **Durcissements v2 :** (1) une clé peut être restreinte à certains **types d'archives** — elle ne voit/agit que dans ce périmètre ; (2) **lecture** limitée aux archives **validées et actives** (les brouillons et archives non validées ne sont jamais exposés) ; (3) **provenance** : une clé ne peut modifier ou alimenter que les archives **qu'elle a elle-même créées** ; (4) un dépôt d'archive atterrit en attente de validation humaine ; (5) le **plan de classement** est requis si le tenant en a publié un ; (6) tout document déposé passe l'**antivirus** (refus `503` si indisponible). Contrainte E2EE : un document `is_encrypted=true` renvoie `403 DOCUMENT_E2EE_PROTECTED` au téléchargement ; les documents créés via l'API externe sont toujours stockés non chiffrés.

Servers

https://api.eu.mearchiver.com/api/external/v2 — Région Europe (EU)
https://api.us.mearchiver.com/api/external/v2 — Région Amérique (US)

Authentication

ExternalApiKey — apiKey (header X-Api-Key)
Clé d'API externe au format `mea_ext_{prefix}_{secret}`. Scopes : `external:archives:read`, `external:archives:write`, `external:documents:read`, `external:documents:write`.

Available scopes

external:archives:read
external:archives:write
external:documents:read
external:documents:write

Endpoints

GET/archives

Lister les archives validées

Retourne une page d'archives **validées et actives** du tenant, limitée aux types autorisés pour la clé. Scope `external:archives:read`. **Filtres par champ dynamique** : ajoutez un ou plusieurs paramètres `field.<field_key>=<valeur>` (ex. `?field.annee=2026&field.service=Achats`). Correspondance **exacte**, sémantique **ET** (le dossier doit satisfaire tous les filtres). Les `field_key` proviennent de `/archive-types/{id}/fields`.

Required scopes: external:archives:read

Parameters

Name	Location	Type	Description
`offset` optional	query	`integer`
`limit` optional	query	`integer`
`search` optional	query	`string`	Recherche plein-texte : titre + mots-clés du dossier ET contenu OCR des documents. Limitée aux dossiers du périmètre de la clé (validés, types autorisés).
`external_ref` optional	query	`string`	Résout le dossier par sa référence ERP (clé d'idempotence).
`type` optional	query	`string (uuid)`	Filtre par type d'archive.

Responses

Status	Description
`200`	Page d'archives.
`401`	Clé d'API absente ou invalide.
`403`	La clé d'API ne porte pas les scopes requis (`EXTERNAL_API_KEY_INVALID_SCOPES`, 400/403).
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.

POST/archives/with-document

Déposer une archive avec son premier document (atomique)

Crée une archive **et** son premier document en une seule requête `multipart/form-data` — garantit qu'un dépôt naît toujours avec du contenu (jamais d'archive vide). L'antivirus est obligatoire (`503` si indisponible). Contraintes : type autorisé, classement conditionnel, champs requis. L'archive est ensuite **auto-soumise** à validation si le type a un workflow actif. **Idempotence (`get-or-create`)** : si `archiveExternalRef` est fourni et qu'un dossier de même référence existe déjà pour ce tenant, il est **réutilisé** (réponse `200`) au lieu d'en recréer un — le document est lui-même dédupliqué par son `externalRef`. Un retry réseau ne crée donc jamais de doublon. Si la référence appartient à une autre clé : `409 ARCHIVE_EXTERNAL_REF_CONFLICT`. Scope `external:documents:write`.

Required scopes: external:documents:write

Request body required

multipart/form-data — object

Responses

Status	Description
`200`	Dossier existant réutilisé (idempotence get-or-create) : le document a été ajouté ou était déjà présent.
`201`	Archive et document déposés (nouveau dossier).
`400`	Aucun fichier fourni dans la requête multipart (`DOCUMENT_UPLOAD_NO_FILE`, 400).
`401`	Clé d'API absente ou invalide.
`403`	Le type d'archive ciblé n'est pas autorisé pour cette clé (`EXTERNAL_ARCHIVE_TYPE_FORBIDDEN`, 403).
`409`	Un dossier avec cette référence externe existe déjà et appartient à une autre clé (`ARCHIVE_EXTERNAL_REF_CONFLICT`, 409).
`422`	Métadonnées incomplètes : champ obligatoire manquant (`ARCHIVE_REQUIRED_FIELD_MISSING`) ou plan de classement requis (`ARCHIVE_CLASSIFICATION_REQUIRED`). HTTP 422.
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.
`503`	Le dépôt requiert l'antivirus, actuellement indisponible (`DOCUMENT_AV_UNAVAILABLE`, 503).

GET/archives/{archiveId}

Récupérer une archive

Retourne une archive validée et active, si son type est autorisé pour la clé. Scope `external:archives:read`.

Required scopes: external:archives:read

Parameters

Name	Location	Type	Description
optional		`—`

Responses

Status	Description
`200`	Archive trouvée.
`401`	Clé d'API absente ou invalide.
`404`	Archive introuvable, non validée, ou hors du périmètre de types de la clé (`ARCHIVE_NOT_FOUND`, 404).
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.

PUT/archives/{archiveId}

Mettre à jour une archive

Met à jour les métadonnées d'une archive **créée par cette clé** (provenance). Le type d'archive ne peut pas changer. Scope `external:archives:write`.

Required scopes: external:archives:write

Parameters

Name	Location	Type	Description
optional		`—`

Request body required

application/json — UpdateArchiveRequest

Responses

Status	Description
`200`	Archive mise à jour.
`401`	Clé d'API absente ou invalide.
`403`	L'archive n'a pas été créée par cette clé : modification interdite (`EXTERNAL_ARCHIVE_NOT_OWNED`, 403).
`404`	Archive introuvable, non validée, ou hors du périmètre de types de la clé (`ARCHIVE_NOT_FOUND`, 404).
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.

GET/archives/{archiveId}/documents

Lister les documents d'une archive

Retourne les documents d'une archive validée et active. Scope `external:documents:read`.

Required scopes: external:documents:read

Parameters

Name	Location	Type	Description
optional		`—`

Responses

Status	Description
`200`	Documents de l'archive.
`401`	Clé d'API absente ou invalide.
`404`	Archive introuvable, non validée, ou hors du périmètre de types de la clé (`ARCHIVE_NOT_FOUND`, 404).
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.

POST/archives/{archiveId}/documents

Déposer un document (multipart)

Téléverse un document dans une archive **créée par cette clé** (provenance), via `multipart/form-data`. Tout dépôt passe l'antivirus ; si le scanner est indisponible, la requête est refusée (`503`). Le document est stocké non chiffré. Scope `external:documents:write`.

Required scopes: external:documents:write

Parameters

Name	Location	Type	Description
optional		`—`

Request body required

multipart/form-data — object

Responses

Status	Description
`201`	Document importé.
`400`	Aucun fichier fourni dans la requête multipart (`DOCUMENT_UPLOAD_NO_FILE`, 400).
`401`	Clé d'API absente ou invalide.
`403`	L'archive n'a pas été créée par cette clé : modification interdite (`EXTERNAL_ARCHIVE_NOT_OWNED`, 403).
`404`	Archive introuvable, non validée, ou hors du périmètre de types de la clé (`ARCHIVE_NOT_FOUND`, 404).
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.
`503`	Le dépôt requiert l'antivirus, actuellement indisponible (`DOCUMENT_AV_UNAVAILABLE`, 503).

GET/archives/{archiveId}/documents/{documentId}

Métadonnées d'un document

Retourne les métadonnées d'un document (sans contenu binaire). Scope `external:documents:read`.

Required scopes: external:documents:read

Parameters

Name	Location	Type	Description
optional		`—`
optional		`—`

Responses

Status	Description
`200`	Métadonnées du document.
`401`	Clé d'API absente ou invalide.
`404`	Document introuvable (`DOCUMENT_NOT_FOUND`, 404).
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.

GET/archives/{archiveId}/documents/{documentId}/content

Télécharger le contenu d'un document

Retourne le contenu binaire du document. Un document chiffré de bout en bout (`is_encrypted=true`) renvoie `403 DOCUMENT_E2EE_PROTECTED` : le serveur ne possède aucune clé utilisateur. Scope `external:documents:read`.

Required scopes: external:documents:read

Parameters

Name	Location	Type	Description
optional		`—`
optional		`—`

Responses

Status	Description
`200`	Contenu binaire du document.
`401`	Clé d'API absente ou invalide.
`403`	Document chiffré de bout en bout : contenu inaccessible via l'API serveur (`DOCUMENT_E2EE_PROTECTED`, 403).
`404`	Document introuvable (`DOCUMENT_NOT_FOUND`, 404).
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.

GET/archive-types

Lister les types d'archives autorisés

Retourne les types d'archives **autorisés pour la clé** (filtrés par sa restriction de type). Scope `external:archives:read`.

Required scopes: external:archives:read

Responses

Status	Description
`200`	Types autorisés.
`401`	Clé d'API absente ou invalide.
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.

GET/archive-types/{id}/fields

Champs d'un type d'archive

Retourne les champs dynamiques du type (pour construire `dynamic_fields`). Un type hors du périmètre de la clé renvoie `404`. Scope `external:archives:read`.

Required scopes: external:archives:read

Parameters

Name	Location	Type	Description
`id` required	path	`string (uuid)`

Responses

Status	Description
`200`	Champs du type.
`401`	Clé d'API absente ou invalide.
`404`	Type d'archive introuvable ou hors périmètre de la clé (`ARCHIVE_TYPE_NOT_FOUND`, 404).
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.

POST/uploads

Ouvrir une session de versement chunké

Démarre une session de versement par morceaux pour un **fichier volumineux** (au-delà de ~8 Mio). Renvoie un `upload_id` et la taille de chunk à utiliser. La session appartient à la clé qui l'a ouverte et expire après 48 h. Chaque clé est limitée à 50 sessions actives (`429 RATE_LIMIT_EXCEEDED`). Scope `external:documents:write`.

Required scopes: external:documents:write

Request body required

application/json — UploadInitRequest

Responses

Status	Description
`201`	Session ouverte.
`401`	Clé d'API absente ou invalide.
`403`	La clé d'API ne porte pas les scopes requis (`EXTERNAL_API_KEY_INVALID_SCOPES`, 400/403).
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.

GET/uploads/{uploadId}

État d'une session (reprise)

Retourne l'état de la session et la liste des index de chunks déjà reçus (`received_chunks`) — pour ne réémettre que les manquants après une coupure. Scope `external:documents:write`.

Required scopes: external:documents:write

Parameters

Name	Location	Type	Description
optional		`—`

Responses

Status	Description
`200`	État de la session.
`401`	Clé d'API absente ou invalide.
`404`	Session de versement introuvable, expirée, ou appartenant à une autre clé (`UPLOAD_NOT_FOUND`, 404).
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.

PUT/uploads/{uploadId}/chunks/{index}

Envoyer un chunk

Téléverse un morceau du fichier (octets bruts). Découpez le fichier en tranches de `chunk_size` octets (renvoyé à l'ouverture). En-tête `X-Chunk-Sha256` (SHA-256 hexadécimal de la tranche) recommandé : il est vérifié côté serveur. Idempotent : ré-envoyer un index déjà reçu est sans effet. Scope `external:documents:write`.

Required scopes: external:documents:write

Parameters

Name	Location	Type	Description
optional		`—`
`index` required	path	`integer`	Index du chunk (à partir de 0).
`X-Chunk-Sha256` optional	header	`string`	SHA-256 hexadécimal de la tranche (vérifié côté serveur).

Request body required

application/octet-stream — string (binary)

Responses

Status	Description
`200`	Chunk reçu.
`401`	Clé d'API absente ou invalide.
`404`	Session de versement introuvable, expirée, ou appartenant à une autre clé (`UPLOAD_NOT_FOUND`, 404).
`409`	Opération incompatible avec l'état de la session (ex. envoyer un chunk après finalisation) (`UPLOAD_INVALID_STATE`, 409).
`422`	Chunk invalide : index hors borne, taille incohérente, SHA-256 ne correspondant pas, ou total à la finalisation incohérent (`UPLOAD_CHUNK_INVALID`, 422).
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.

POST/uploads/{uploadId}/complete

Finaliser la session

Assemble les chunks reçus et bascule la session à l'état `STAGED`. Fournissez `total_chunks` et `total_size` attendus (vérifiés). La session est alors prête à être consommée : passez son `upload_id` en `stagedUploadId` à `with-document` ou à l'ajout de document. Scope `external:documents:write`.

Required scopes: external:documents:write

Parameters

Name	Location	Type	Description
optional		`—`

Request body required

application/json — UploadCompleteRequest

Responses

Status	Description
`200`	Session finalisée (STAGED).
`401`	Clé d'API absente ou invalide.
`404`	Session de versement introuvable, expirée, ou appartenant à une autre clé (`UPLOAD_NOT_FOUND`, 404).
`409`	Opération incompatible avec l'état de la session (ex. envoyer un chunk après finalisation) (`UPLOAD_INVALID_STATE`, 409).
`422`	Chunk invalide : index hors borne, taille incohérente, SHA-256 ne correspondant pas, ou total à la finalisation incohérent (`UPLOAD_CHUNK_INVALID`, 422).
`429`	Limite de débit dépassée (`RATE_LIMIT_EXCEEDED`, 429). Fenêtre fixe de 1 minute par clé.