Skip to Content
Prise en main

Prise en main de l’API externe

L’API publique externe de MEA (/api/external/v2/*) permet à vos applications métier (ERP, intégrations tierces) d’archiver et de consulter des documents de façon programmatique, sans interface humaine. L’API est régionale : utilisez https://api.eu.mearchiver.com (EU) ou https://api.us.mearchiver.com (US). Une clé peut être restreinte à certains types d’archives et ne peut modifier que les archives qu’elle a elle-même créées (provenance).

1. Obtenir une clé d’API

Les clés d’API externes sont créées par un administrateur du tenant depuis Paramètres → Sécurité → Clés d’API externes. Une clé a la forme :

mea_ext_{prefix}_{secret}
  • mea_ext_ — préfixe fixe qui distingue une clé externe d’une clé de synchronisation inter-instances (mea_). Les deux ne sont jamais interchangeables.
  • {prefix} — identifiant public de la clé (visible dans les journaux).
  • {secret} — partie secrète, affichée une seule fois à la création. Stockez-la dans un coffre de secrets, jamais dans le code.

2. Le modèle de scopes

Chaque clé porte un ou plusieurs scopes. Une requête est refusée (400 EXTERNAL_API_KEY_INVALID_SCOPES) si la clé ne possède pas le scope requis par l’endpoint.

ScopeAutorise
external:archives:readLister et lire les dossiers d’archives
external:archives:writeCréer et mettre à jour les dossiers
external:documents:readLire les métadonnées et le contenu des documents
external:documents:writeTéléverser des documents

Appliquez le principe du moindre privilège : n’accordez que les scopes strictement nécessaires à l’intégration.

3. L’en-tête d’authentification

Toutes les requêtes doivent porter la clé dans l’en-tête X-Api-Key :

X-Api-Key: mea_ext_a1b2c3_VOTRE_SECRET

Le scheme d’authentification correspondant est ExternalApiKey. Aucune autre méthode (Bearer JWT, cookie) n’est acceptée sur /api/external/v2.

4. Première requête authentifiée

Listez les types autorisés pour votre clé, puis les archives (validées) :

curl -s https://api.eu.mearchiver.com/api/external/v2/archive-types \
  -H "X-Api-Key: mea_ext_a1b2c3_VOTRE_SECRET"
 
curl -s https://api.eu.mearchiver.com/api/external/v2/archives \
  -H "X-Api-Key: mea_ext_a1b2c3_VOTRE_SECRET"

5. L’enveloppe de réponse

Toutes les réponses utilisent une enveloppe JSON snake_case stable. Les endpoints de liste renvoient un objet paginé (items/total/offset/limit) :

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "8f1c0e2a-3b4d-4e5f-9a0b-1c2d3e4f5a6b",
        "title": "Contrats fournisseurs 2026",
        "submission_status": "VALIDATION_APPROVED",
        "created_at": "2026-06-08T09:30:00Z"
      }
    ],
    "total": 1,
    "offset": 0,
    "limit": 50
  }
}

En cas d’erreur, l’enveloppe contient un objet error typé :

{
  "success": false,
  "error": {
    "code": "EXTERNAL_API_KEY_INVALID_SCOPES",
    "message": "La clé d'API ne dispose pas des scopes requis."
  }
}

Poursuivez avec les concepts puis le guide d’intégration.

BienvenueAgent local