# IA et outils de développement
Source: https://developers.marko.fr/ai-and-tools

Copier une page ou toute la documentation, récupérer OpenAPI et générer un client.

## Copier toute la documentation

<CopyDocumentation />

Le fichier regroupe les guides et le contrat OpenAPI enrichi des 158 opérations stables, avec ses schémas référencés. Il est volumineux : pour une tâche ciblée, fournir seulement les pages utiles évite de saturer le contexte de votre assistant.

## Copier une page

Le menu **Copy page** de chaque page permet de copier son Markdown, voir la version texte et l'ouvrir dans ChatGPT ou Claude. Les pages API contiennent le scope requis dans leur texte; les extensions `x-marko-*` du contrat ne sont pas le seul endroit où lire cette information.

L'[index des pages](https://developers.marko.fr/llms.txt) permet à un agent de découvrir la documentation. Les pages sont également disponibles en Markdown en ajoutant `.md` à leur URL. Le [texte complet généré par le site](https://developers.marko.fr/llms-full.txt) et le téléchargement ci-dessus permettent de lire plusieurs familles sans parcourir l'interface.

## Contrats machine

| Document | Usage |
| - | - |
| [OpenAPI enrichi de cette documentation](https://raw.githubusercontent.com/mathieuworoniecki/marko-developer-docs/main/openapi.json) | Types réels, champs obligatoires, réponses, scopes et exemples synthétiques. |
| [OpenAPI public de l'API](https://partner-api.marko.fr/v1/openapi.json) | Catalogue stable fourni directement par le service. |
| [Collection Postman publique](https://partner-api.marko.fr/v1/postman.json) | Explorer les appels du catalogue public. |
| Export filtré par clé dans MARKO | Voir les opérations autorisées par les scopes et restrictions d'une clé donnée. |

Le contrat enrichi contient `x-documentation-provenance`, qui identifie la version du backend utilisée pour les types et l'empreinte du catalogue public. Une référence documentée ne prouve pas que votre clé y a accès ni qu'une ressource d'exemple existe.

Le téléchargement complet est un fichier JSON dont le champ `markdown` contient le texte à fournir à votre assistant. Le bouton de copie extrait directement ce texte pour le presse-papiers.

## SDK et client généré

Cette documentation ne fournit pas de SDK officiel MARKO. Vous pouvez générer un client à partir d'OpenAPI avec un générateur compatible OpenAPI 3.1, puis ajouter l'échange HMAC et la gestion des reprises. Le client HTTP doit prendre en charge les timeouts, `application/problem+json`, les fichiers multipart et les réponses binaires.

Conservez les secrets dans l'environnement du serveur ou un gestionnaire de secrets. Les exemples sont synthétiques : remplacez leurs identifiants par ceux de votre contexte, sans les traiter comme des ressources de test disponibles.

## Contexte utile pour un assistant

```text theme={null}
Utilise la documentation MARKO Developers et son OpenAPI enrichi.
Base URL: https://partner-api.marko.fr/v1 (ou l'hôte fourni par notre équipe).
Authentification: HMAC-SHA256 vers POST /auth/token, puis bearer court.
Vérifie le scope de chaque route et les capacités de délégation nécessaires.
Préserve les identifiants externes et les clés d'idempotence entre les reprises.
Ne considère pas HTTP 202 comme la fin d'un traitement.
Consulte les taxonomies et le référentiel des champs plutôt que d'inventer des codes.
Pour un fichier neuf, utilise directement /documents/external/{external_id}/upload.
N'invente pas de route, de SDK officiel, de droit d'accès ou de donnée d'exemple réelle.
Ne place jamais un secret ou un bearer dans le code publié.
```


# Accuser réception d'une alerte
Source: https://developers.marko.fr/api-reference/alerts/accuser-réception-dune-alerte

/openapi.json post /alerts/{alert_id}/actions/acknowledge
Passe l'alerte au statut acknowledged.

**Scope requis :** `alerts:write`. [Scopes et délégation](/scopes-and-delegation).



# Lister les alertes
Source: https://developers.marko.fr/api-reference/alerts/lister-les-alertes

/openapi.json get /alerts
Expose la projection alertes de l'entité avec filtres.

**Scope requis :** `alerts:read`. [Scopes et délégation](/scopes-and-delegation).



# Mettre une alerte en snooze
Source: https://developers.marko.fr/api-reference/alerts/mettre-une-alerte-en-snooze

/openapi.json post /alerts/{alert_id}/actions/snooze
Snooze une alerte pour quelques jours.

**Scope requis :** `alerts:write`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer une alerte
Source: https://developers.marko.fr/api-reference/alerts/récupérer-une-alerte

/openapi.json get /alerts/{alert_id}
Retourne une alerte unitaire.

**Scope requis :** `alerts:read`. [Scopes et délégation](/scopes-and-delegation).



# Résoudre une alerte
Source: https://developers.marko.fr/api-reference/alerts/résoudre-une-alerte

/openapi.json post /alerts/{alert_id}/actions/resolve
Passe l'alerte au statut resolved.

**Scope requis :** `alerts:write`. [Scopes et délégation](/scopes-and-delegation).



# Obtenir un bearer court
Source: https://developers.marko.fr/api-reference/auth/obtenir-un-bearer-court

/openapi.json post /auth/token
Echange une cle API brute contre un bearer MARKO court. La signature HMAC-SHA256 est calculee avec la cle API brute sur le message canonique `MARKO-EXTERNAL-API-TOKEN-V1\n{key_id}\n{timestamp}\n{nonce}`. Utilisez ensuite `Authorization: Bearer YOUR_BEARER_HERE` sur les endpoints metier.

Cette route échange la signature HMAC contre un bearer; aucun bearer préalable n'est requis. [Authentification](/authentication).



# Accepter un événement IA
Source: https://developers.marko.fr/api-reference/calendar/accepter-un-événement-ia

/openapi.json post /calendar/events/{event_id}/actions/accept
Accepte un événement proposé.

**Scope requis :** `calendar:write`. [Scopes et délégation](/scopes-and-delegation).



# Créer un événement calendrier
Source: https://developers.marko.fr/api-reference/calendar/créer-un-événement-calendrier

/openapi.json post /calendar/events
Crée un événement manuel ou IA persisté.

**Scope requis :** `calendar:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Lister les événements calendrier
Source: https://developers.marko.fr/api-reference/calendar/lister-les-événements-calendrier

/openapi.json get /calendar/events
Expose les échéances et événements persistés de l'entité.

**Scope requis :** `calendar:read`. [Scopes et délégation](/scopes-and-delegation).



# Mettre à jour un événement calendrier
Source: https://developers.marko.fr/api-reference/calendar/mettre-à-jour-un-événement-calendrier

/openapi.json put /calendar/events/{event_id}
Met à jour un événement calendrier.

**Scope requis :** `calendar:write`. [Scopes et délégation](/scopes-and-delegation).



# Rejeter un événement IA
Source: https://developers.marko.fr/api-reference/calendar/rejeter-un-événement-ia

/openapi.json post /calendar/events/{event_id}/actions/reject
Rejette un événement proposé.

**Scope requis :** `calendar:write`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer un événement calendrier
Source: https://developers.marko.fr/api-reference/calendar/récupérer-un-événement-calendrier

/openapi.json get /calendar/events/{event_id}
Retourne un événement calendrier unitaire.

**Scope requis :** `calendar:read`. [Scopes et délégation](/scopes-and-delegation).



# Supprimer un événement calendrier
Source: https://developers.marko.fr/api-reference/calendar/supprimer-un-événement-calendrier

/openapi.json delete /calendar/events/{event_id}
Supprime un événement calendrier.

**Scope requis :** `calendar:write`. [Scopes et délégation](/scopes-and-delegation).



# Modifier une note de suivi
Source: https://developers.marko.fr/api-reference/comments/modifier-une-note-de-suivi

/openapi.json put /comments/{comment_id}
Modifie la date métier, le texte ou la catégorie d'une note MARKO.

**Scope requis :** `operations:write`. [Scopes et délégation](/scopes-and-delegation).



# Supprimer une note de suivi
Source: https://developers.marko.fr/api-reference/comments/supprimer-une-note-de-suivi

/openapi.json delete /comments/{comment_id}
Supprime la note; l'événement de suppression reste dans la chronologie.

**Scope requis :** `operations:write`. [Scopes et délégation](/scopes-and-delegation).



# Créer un deal
Source: https://developers.marko.fr/api-reference/deals/créer-un-deal

/openapi.json post /deals
Crée un deal dans le pipeline pre-closing.

**Scope requis :** `deals:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Créer une note de deal
Source: https://developers.marko.fr/api-reference/deals/créer-une-note-de-deal

/openapi.json post /deals/{deal_id}/notes
Ajoute une note sur un deal du pipeline.

**Scope requis :** `deals:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Lister les deals
Source: https://developers.marko.fr/api-reference/deals/lister-les-deals

/openapi.json get /deals
Expose le pipeline CRM pre-closing de l'entité.

**Scope requis :** `deals:read`. [Scopes et délégation](/scopes-and-delegation).



# Lister les notes d'un deal
Source: https://developers.marko.fr/api-reference/deals/lister-les-notes-dun-deal

/openapi.json get /deals/{deal_id}/notes
Expose les notes attachées à un deal.

**Scope requis :** `deals:read`. [Scopes et délégation](/scopes-and-delegation).



# Mettre à jour un deal
Source: https://developers.marko.fr/api-reference/deals/mettre-à-jour-un-deal

/openapi.json put /deals/{deal_id}
Met à jour un deal existant du pipeline.

**Scope requis :** `deals:write`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer un deal
Source: https://developers.marko.fr/api-reference/deals/récupérer-un-deal

/openapi.json get /deals/{deal_id}
Retourne un deal unitaire du pipeline.

**Scope requis :** `deals:read`. [Scopes et délégation](/scopes-and-delegation).



# Supprimer un deal
Source: https://developers.marko.fr/api-reference/deals/supprimer-un-deal

/openapi.json delete /deals/{deal_id}
Supprime logiquement un deal du pipeline.

**Scope requis :** `deals:write`. [Scopes et délégation](/scopes-and-delegation).



# Supprimer une note de deal
Source: https://developers.marko.fr/api-reference/deals/supprimer-une-note-de-deal

/openapi.json delete /deal-notes/{note_id}
Supprime une note rattachée au pipeline deals.

**Scope requis :** `deals:write`. [Scopes et délégation](/scopes-and-delegation).



# Creer le metadata d'un document
Source: https://developers.marko.fr/api-reference/documents/creer-le-metadata-dun-document

/openapi.json put /documents/external/{external_id}
Route idempotente pour declarer un document avant upload physique.

**Scope requis :** `documents:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).

[Documents et upload](/documents-guide).



# Lister les documents
Source: https://developers.marko.fr/api-reference/documents/lister-les-documents

/openapi.json get /documents
Peut filtrer sur une operation MARKO ou une `operation_external_id`.

**Scope requis :** `documents:read`. [Scopes et délégation](/scopes-and-delegation).

[Documents et upload](/documents-guide).



# Mettre à jour un document
Source: https://developers.marko.fr/api-reference/documents/mettre-à-jour-un-document

/openapi.json put /documents/{document_id}
Met à jour les métadonnées d'un document existant.

**Scope requis :** `documents:write`. [Scopes et délégation](/scopes-and-delegation).

[Documents et upload](/documents-guide).



# Rattacher un document à une opération
Source: https://developers.marko.fr/api-reference/documents/rattacher-un-document-à-une-opération

/openapi.json post /documents/{document_id}/attach-operation
Rattache atomiquement un document non affecté à une opération MARKO. Une relance avec la même clé d'idempotence rejoue la première réponse; une nouvelle intention échoue si le document est déjà rattaché.

**Scope requis :** `documents:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).

[Documents et upload](/documents-guide).



# Recuperer un document
Source: https://developers.marko.fr/api-reference/documents/recuperer-un-document

/openapi.json get /documents/{document_id}
Retourne le metadata d'un document et son URL de telechargement si disponible.

**Scope requis :** `documents:read`. [Scopes et délégation](/scopes-and-delegation).

[Documents et upload](/documents-guide).



# Supprimer un document
Source: https://developers.marko.fr/api-reference/documents/supprimer-un-document

/openapi.json delete /documents/{document_id}
Supprime logiquement un document existant.

**Scope requis :** `documents:write`. [Scopes et délégation](/scopes-and-delegation).

[Documents et upload](/documents-guide).



# Uploader un document
Source: https://developers.marko.fr/api-reference/documents/uploader-un-document

/openapi.json put /documents/external/{external_id}/upload
Upload multipart/form-data idempotent avec rattachement a une operation via `operation_id` ou `operation_external_id`.

**Scope requis :** `documents:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).

[Documents et upload](/documents-guide).



# Invalider le cache SIREN
Source: https://developers.marko.fr/api-reference/enrichment/invalider-le-cache-siren

/openapi.json delete /enrichment/siren/{siren}/cache
Supprime l'entrée de cache. Une nouvelle résolution provider exige ensuite POST /v1/enrichment/siren/{siren}/resolve.

**Scope requis :** `operateurs:write`. [Scopes et délégation](/scopes-and-delegation).



# Lire les données société locales par SIREN
Source: https://developers.marko.fr/api-reference/enrichment/lire-les-données-société-locales-par-siren

/openapi.json get /enrichment/siren/{siren}
Retourne uniquement les données déjà en cache ou présentes dans la base locale. Cet endpoint de lecture ne déclenche aucun appel facturable.

**Scope requis :** `operateurs:read`. [Scopes et délégation](/scopes-and-delegation).



# Résoudre une société par SIREN via Pappers
Source: https://developers.marko.fr/api-reference/enrichment/résoudre-une-société-par-siren-via-pappers

/openapi.json post /enrichment/siren/{siren}/resolve
Résout d'abord les données locales puis réserve de façon idempotente tout appel Pappers facturable. Requiert le header Idempotency-Key.

**Scope requis :** `operateurs:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Valider un SIREN
Source: https://developers.marko.fr/api-reference/enrichment/valider-un-siren

/openapi.json get /enrichment/siren/{siren}/validate
Vérifie le format et le checksum Luhn d'un SIREN sans appeler un provider externe.

**Scope requis :** `operateurs:read`. [Scopes et délégation](/scopes-and-delegation).



# Recuperer la fiche de l'entite
Source: https://developers.marko.fr/api-reference/entity/recuperer-la-fiche-de-lentite

/openapi.json get /entity
Expose l'entite rattachee a la cle API, sans changer de contexte.

**Scope requis :** `entity:read`. [Scopes et délégation](/scopes-and-delegation).



# Lister le dictionnaire de champs
Source: https://developers.marko.fr/api-reference/field-definitions/lister-le-dictionnaire-de-champs

/openapi.json get /field-definitions
Expose le référentiel métier des champs MARKO avec filtres et pagination.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer une définition de champ
Source: https://developers.marko.fr/api-reference/field-definitions/récupérer-une-définition-de-champ

/openapi.json get /field-definitions/{field_id}
Retourne la définition détaillée d'un champ métier par identifiant.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer une définition de champ par clé
Source: https://developers.marko.fr/api-reference/field-definitions/récupérer-une-définition-de-champ-par-clé

/openapi.json get /field-definitions/by-key/{field_key}
Retourne la définition détaillée d'un champ métier par field_key.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Créer un fonds
Source: https://developers.marko.fr/api-reference/fonds/créer-un-fonds

/openapi.json post /fonds
Crée un fonds d'investissement dans l'entité.

**Scope requis :** `fonds:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Lister les fonds
Source: https://developers.marko.fr/api-reference/fonds/lister-les-fonds

/openapi.json get /fonds
Retourne les fonds visibles pour l'entite de la cle, par page bornee. Les en-tetes X-Marko-Limit, X-Marko-Offset et X-Marko-Has-More decrivent la page.

**Scope requis :** `fonds:read`. [Scopes et délégation](/scopes-and-delegation).



# Mettre à jour un fonds
Source: https://developers.marko.fr/api-reference/fonds/mettre-à-jour-un-fonds

/openapi.json put /fonds/{fond_id}
Met à jour les métadonnées d'un fonds.

**Scope requis :** `fonds:write`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer un fonds
Source: https://developers.marko.fr/api-reference/fonds/récupérer-un-fonds

/openapi.json get /fonds/{fond_id}
Retourne le détail d'un fonds MARKO.

**Scope requis :** `fonds:read`. [Scopes et délégation](/scopes-and-delegation).



# Supprimer un fonds
Source: https://developers.marko.fr/api-reference/fonds/supprimer-un-fonds

/openapi.json delete /fonds/{fond_id}
Supprime logiquement un fonds.

**Scope requis :** `fonds:write`. [Scopes et délégation](/scopes-and-delegation).



# Demander l'arrêt d'un import
Source: https://developers.marko.fr/api-reference/import-jobs/demander-larrêt-dun-import

/openapi.json post /import-jobs/{job_id}/cancel
Demande un arrêt propre au prochain point de reprise durable.

**Scope requis :** `operations:write`. [Scopes et délégation](/scopes-and-delegation).

[Import par lot, suivi et reprise](/imports-and-notes).



# Lister les résultats d'un import
Source: https://developers.marko.fr/api-reference/import-jobs/lister-les-résultats-dun-import

/openapi.json get /import-jobs/{job_id}/items
Filtre les résultats par `status` ou `item_kind` pour diagnostiquer et reprendre un lot.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).

[Import par lot, suivi et reprise](/imports-and-notes).



# Relancer les éléments échoués
Source: https://developers.marko.fr/api-reference/import-jobs/relancer-les-éléments-échoués

/openapi.json post /import-jobs/{job_id}/retry
Réenfile un job failed ou partial; les éléments déjà terminés restent des no-op.

**Scope requis :** `operations:write`. [Scopes et délégation](/scopes-and-delegation).

[Import par lot, suivi et reprise](/imports-and-notes).



# Suivre un job d'import
Source: https://developers.marko.fr/api-reference/import-jobs/suivre-un-job-dimport

/openapi.json get /import-jobs/{job_id}
Retourne les compteurs completed, noop, failed et conflict du job durable. Pour un import d'une operation, `operation_id` est renseigne des que la cible MARKO existe; sinon `error_code` et `error_message` decrivent l'echec.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).

[Import par lot, suivi et reprise](/imports-and-notes).



# Compter les notifications non lues
Source: https://developers.marko.fr/api-reference/notifications/compter-les-notifications-non-lues

/openapi.json get /notifications/unread-count
Retourne le compteur unread et le flag critique.

**Scope requis :** `notifications:read`. [Scopes et délégation](/scopes-and-delegation).



# Créer une notification
Source: https://developers.marko.fr/api-reference/notifications/créer-une-notification

/openapi.json post /notifications
Crée une notification ciblée dans l'entité.

**Scope requis :** `notifications:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Lister les notifications
Source: https://developers.marko.fr/api-reference/notifications/lister-les-notifications

/openapi.json get /notifications
Expose les notifications de l'entité.

**Scope requis :** `notifications:read`. [Scopes et délégation](/scopes-and-delegation).



# Marquer tout comme lu
Source: https://developers.marko.fr/api-reference/notifications/marquer-tout-comme-lu

/openapi.json post /notifications/actions/read-all
Marque toutes les notifications comme lues.

**Scope requis :** `notifications:write`. [Scopes et délégation](/scopes-and-delegation).



# Marquer une notification comme lue
Source: https://developers.marko.fr/api-reference/notifications/marquer-une-notification-comme-lue

/openapi.json post /notifications/{notification_id}/actions/read
Passe le drapeau read à true.

**Scope requis :** `notifications:write`. [Scopes et délégation](/scopes-and-delegation).



# Qualifier un faux positif
Source: https://developers.marko.fr/api-reference/notifications/qualifier-un-faux-positif

/openapi.json post /notifications/{notification_id}/actions/false-positive
Marque une notification comme faux positif sans la supprimer.

**Scope requis :** `notifications:write`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer une notification
Source: https://developers.marko.fr/api-reference/notifications/récupérer-une-notification

/openapi.json get /notifications/{notification_id}
Retourne une notification unitaire.

**Scope requis :** `notifications:read`. [Scopes et délégation](/scopes-and-delegation).



# Supprimer une notification
Source: https://developers.marko.fr/api-reference/notifications/supprimer-une-notification

/openapi.json delete /notifications/{notification_id}
Supprime une notification de l'entité.

**Scope requis :** `notifications:write`. [Scopes et délégation](/scopes-and-delegation).



# Créer ou mettre à jour un opérateur externe
Source: https://developers.marko.fr/api-reference/operateurs/créer-ou-mettre-à-jour-un-opérateur-externe

/openapi.json put /operateurs/external/{external_id}
Upsert synchrone par identifiant partenaire, sans exiger de SIREN. Une ressource supprimée logiquement est restaurée avec le même UUID; existing_marko_id lie explicitement une cible existante lors du premier envoi.

**Scope requis :** `operateurs:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Créer un opérateur
Source: https://developers.marko.fr/api-reference/operateurs/créer-un-opérateur

/openapi.json post /operateurs
Crée un opérateur dans l'entité.

**Scope requis :** `operateurs:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Créer un événement de risque tiers
Source: https://developers.marko.fr/api-reference/operateurs/créer-un-événement-de-risque-tiers

/openapi.json post /operateurs/{operateur_id}/third-party-risks
Ajoute manuellement un événement de risque tiers pour un opérateur.

**Scope requis :** `third_party_risks:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Lister les opérateurs
Source: https://developers.marko.fr/api-reference/operateurs/lister-les-opérateurs

/openapi.json get /operateurs
Expose les opérateurs et leurs métadonnées principales. Utilisez `name` pour une correspondance exacte insensible à la casse ou `search` pour une recherche partielle; ces filtres sont mutuellement exclusifs.

**Scope requis :** `operateurs:read`. [Scopes et délégation](/scopes-and-delegation).



# Lister les risques tiers d'un opérateur
Source: https://developers.marko.fr/api-reference/operateurs/lister-les-risques-tiers-dun-opérateur

/openapi.json get /operateurs/{operateur_id}/third-party-risks
Expose les événements de surveillance tiers rattachés à un opérateur.

**Scope requis :** `third_party_risks:read`. [Scopes et délégation](/scopes-and-delegation).



# Mettre à jour un opérateur
Source: https://developers.marko.fr/api-reference/operateurs/mettre-à-jour-un-opérateur

/openapi.json put /operateurs/{operateur_id}
Met à jour l'identité ou les données d'un opérateur.

**Scope requis :** `operateurs:write`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer un opérateur
Source: https://developers.marko.fr/api-reference/operateurs/récupérer-un-opérateur

/openapi.json get /operateurs/{operateur_id}
Retourne le détail d'un opérateur.

**Scope requis :** `operateurs:read`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer un opérateur par identifiant externe
Source: https://developers.marko.fr/api-reference/operateurs/récupérer-un-opérateur-par-identifiant-externe

/openapi.json get /operateurs/external/{external_id}
Résout l'identifiant stable du partenaire vers l'opérateur MARKO.

**Scope requis :** `operateurs:read`. [Scopes et délégation](/scopes-and-delegation).



# Résoudre un risque tiers
Source: https://developers.marko.fr/api-reference/operateurs/résoudre-un-risque-tiers

/openapi.json post /operateurs/{operateur_id}/third-party-risks/{event_id}/resolve
Marque un événement tiers comme résolu.

**Scope requis :** `third_party_risks:write`. [Scopes et délégation](/scopes-and-delegation).



# Résumé des risques tiers
Source: https://developers.marko.fr/api-reference/operateurs/résumé-des-risques-tiers

/openapi.json get /operateurs/{operateur_id}/third-party-risks/summary
Retourne le score de risque tiers et les compteurs agrégés d'un opérateur.

**Scope requis :** `third_party_risks:read`. [Scopes et délégation](/scopes-and-delegation).



# Supprimer un opérateur
Source: https://developers.marko.fr/api-reference/operateurs/supprimer-un-opérateur

/openapi.json delete /operateurs/{operateur_id}
Supprime logiquement un opérateur.

**Scope requis :** `operateurs:write`. [Scopes et délégation](/scopes-and-delegation).



# Creer ou mettre a jour une operation externe
Source: https://developers.marko.fr/api-reference/operations/creer-ou-mettre-a-jour-une-operation-externe

/openapi.json put /operations/external/{external_id}
Crée ou met à jour immédiatement une opération à partir d'un identifiant partenaire stable. La réponse contient directement marko_id. Une valeur de taxonomie inconnue est créée pour l'entité, visible immédiatement et signalée dans taxonomy_additions. Le segment généré des codes `custom__...` n'est pas prévisible : le client doit conserver le code renvoyé et le réutiliser. Une création répond 201; une mise à jour, restauration ou répétition sans changement répond 200. Les notes utilisent leur endpoint dédié; seul POST /operations/batch reste asynchrone.

**Scope requis :** `operations:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Créer un remboursement
Source: https://developers.marko.fr/api-reference/operations/créer-un-remboursement

/openapi.json post /operations/{operation_id}/repayments
Enregistre un remboursement sur une opération.

**Scope requis :** `operations:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Créer une note de suivi MARKO
Source: https://developers.marko.fr/api-reference/operations/créer-une-note-de-suivi-marko

/openapi.json post /operations/{operation_id}/comments
Crée une note sans identifiant externe; pour un import idempotent, utilisez la route notes/external. `category` est une chaine libre de 1 a 80 caracteres; valeurs conseillees: call, comite, juridique ou libre.

**Scope requis :** `operations:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Importer un lot d'operations externes
Source: https://developers.marko.fr/api-reference/operations/importer-un-lot-doperations-externes

/openapi.json post /operations/batch
Accepte jusqu'à 500 opérations, 10 000 notes et 20 Mio par requête. Le job est durable et chaque élément possède son propre résultat. `category` dans les notes est une chaine libre de 1 a 80 caracteres.

**Scope requis :** `operations:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).

[Import par lot, suivi et reprise](/imports-and-notes).



# Importer une note de suivi externe
Source: https://developers.marko.fr/api-reference/operations/importer-une-note-de-suivi-externe

/openapi.json put /operations/external/{operation_external_id}/notes/external/{note_external_id}
Crée ou met à jour immédiatement une note historique datée sur une opération référencée par son identifiant externe. La réponse contient directement son marko_id. Une catégorie inconnue devient une option d'entité visible, avec la source partenaire. Une mise à jour versionnée doit porter un source_updated_at strictement plus récent lorsque la note en possède déjà un.

**Scope requis :** `operations:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Lire la chronologie narrative d'une opération
Source: https://developers.marko.fr/api-reference/operations/lire-la-chronologie-narrative-dune-opération

/openapi.json get /operations/{operation_id}/chronicle/narrative
Agrège notamment les notes de suivi. Pour une note importée, metadata expose note_date, note_text et note_category.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Lire l'historique technique d'une opération
Source: https://developers.marko.fr/api-reference/operations/lire-lhistorique-technique-dune-opération

/openapi.json get /operations/{operation_id}/chronicle
Historique paginé des transitions, changements de champs et événements d'audit.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Lister le socle canonique MARKO historique
Source: https://developers.marko.fr/api-reference/operations/lister-le-socle-canonique-marko-historique

/openapi.json get /operations/taxonomy
Endpoint legacy: retourne uniquement le socle canonique MARKO historique. Les écritures acceptent aussi les valeurs propres à l'entité. Utilisez `GET /v1/taxonomies?dimension=...` pour la liste visible et autoritative, y compris les options ClubFunding.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Lister les notes de suivi MARKO
Source: https://developers.marko.fr/api-reference/operations/lister-les-notes-de-suivi-marko

/openapi.json get /operations/{operation_id}/comments
Retourne les notes triées par date métier avec texte et catégorie libre.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Lister les operations
Source: https://developers.marko.fr/api-reference/operations/lister-les-operations

/openapi.json get /operations
Supporte la recherche par nom exact insensible a la casse, la pagination, le filtrage par statut et le filtrage par SPV. Le filtre par nom est un controle avant creation, pas une garantie d'unicite concurrente; conservez l'identifiant MARKO et utilisez external_id avec Idempotency-Key.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Lister l'historique de remboursements
Source: https://developers.marko.fr/api-reference/operations/lister-lhistorique-de-remboursements

/openapi.json get /operations/{operation_id}/repayments
Retourne les remboursements saisis sur une opération avec pagination.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Recuperer une operation
Source: https://developers.marko.fr/api-reference/operations/recuperer-une-operation

/openapi.json get /operations/{operation_id}
Retourne le detail d'une operation par son identifiant MARKO.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer un suivi par identifiants externes
Source: https://developers.marko.fr/api-reference/operations/récupérer-un-suivi-par-identifiants-externes

/openapi.json get /operations/external/{operation_external_id}/notes/external/{note_external_id}
Retourne la note uniquement si elle appartient à l'opération externe indiquée.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer une opération par identifiant externe
Source: https://developers.marko.fr/api-reference/operations/récupérer-une-opération-par-identifiant-externe

/openapi.json get /operations/external/{external_id}
Résout l'identifiant stable du système partenaire et retourne immédiatement l'identifiant MARKO et la ressource courante. Les codes `custom__...` sont générés par MARKO : conservez toujours le code renvoyé au lieu de le construire.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Supprimer une opération
Source: https://developers.marko.fr/api-reference/operations/supprimer-une-opération

/openapi.json delete /operations/{operation_id}
Supprime logiquement une opération existante.

**Scope requis :** `operations:write`. [Scopes et délégation](/scopes-and-delegation).



# Recuperer la synthese portefeuille
Source: https://developers.marko.fr/api-reference/portfolio/recuperer-la-synthese-portefeuille

/openapi.json get /portfolio/summary
Retourne un resume portefeuille agrege pour l'entite de la cle, sans parametre de filtre. Les totaux excluent les ressources supprimees et les repartitions utilisent les codes de taxonomie effectifs.

**Scope requis :** `portfolio:read`. [Scopes et délégation](/scopes-and-delegation).



# Synthèse RCCI
Source: https://developers.marko.fr/api-reference/rcci/synthèse-rcci

/openapi.json get /rcci/summary
Agrège les covenants en tension, les documents manquants et les opérations à risque de l'entité.

**Scope requis :** `portfolio:read`. [Scopes et délégation](/scopes-and-delegation).



# Créer un template de reporting
Source: https://developers.marko.fr/api-reference/reporting/créer-un-template-de-reporting

/openapi.json post /reporting/templates
Crée un template de reporting personnalisé.

**Scope requis :** `reporting:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Lister les templates de reporting
Source: https://developers.marko.fr/api-reference/reporting/lister-les-templates-de-reporting

/openapi.json get /reporting/templates
Expose les templates de reporting configurés pour l'entité.

**Scope requis :** `reporting:read`. [Scopes et délégation](/scopes-and-delegation).



# Mettre à jour un template de reporting
Source: https://developers.marko.fr/api-reference/reporting/mettre-à-jour-un-template-de-reporting

/openapi.json put /reporting/templates/{template_id}
Met à jour un template existant.

**Scope requis :** `reporting:write`. [Scopes et délégation](/scopes-and-delegation).



# Prévisualiser un template de reporting
Source: https://developers.marko.fr/api-reference/reporting/prévisualiser-un-template-de-reporting

/openapi.json get /reporting/templates/{template_id}/preview
Retourne un aperçu tabulaire d'un template.

**Scope requis :** `reporting:read`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer un template de reporting
Source: https://developers.marko.fr/api-reference/reporting/récupérer-un-template-de-reporting

/openapi.json get /reporting/templates/{template_id}
Retourne le détail d'un template de reporting.

**Scope requis :** `reporting:read`. [Scopes et délégation](/scopes-and-delegation).



# Supprimer un template de reporting
Source: https://developers.marko.fr/api-reference/reporting/supprimer-un-template-de-reporting

/openapi.json delete /reporting/templates/{template_id}
Supprime un template de reporting non système.

**Scope requis :** `reporting:write`. [Scopes et délégation](/scopes-and-delegation).



# Exporter le reporting INREV
Source: https://developers.marko.fr/api-reference/reports/exporter-le-reporting-inrev

/openapi.json get /reports/inrev
Génère le classeur INREV standard de l'entité au format XLSX.

**Scope requis :** `reporting:read`. [Scopes et délégation](/scopes-and-delegation).



# Recherche globale
Source: https://developers.marko.fr/api-reference/search/recherche-globale

/openapi.json get /search
Recherche transversale sur operations, operateurs, SPV, fonds et documents.

**Scope requis :** `search:read`. [Scopes et délégation](/scopes-and-delegation).



# Recherche plein texte documentaire
Source: https://developers.marko.fr/api-reference/search/recherche-plein-texte-documentaire

/openapi.json get /search/content
Recherche full-text dans le contenu documentaire indexé.

**Scope requis :** `search:read`. [Scopes et délégation](/scopes-and-delegation).



# Lire les paramètres de l'entité
Source: https://developers.marko.fr/api-reference/settings/lire-les-paramètres-de-lentité

/openapi.json get /settings
Expose les paramètres métier et branding de l'entité.

**Scope requis :** `settings:read`. [Scopes et délégation](/scopes-and-delegation).



# Mettre à jour les paramètres de l'entité
Source: https://developers.marko.fr/api-reference/settings/mettre-à-jour-les-paramètres-de-lentité

/openapi.json put /settings
Met à jour les paramètres de reporting et de branding de l'entité.

**Scope requis :** `settings:write`. [Scopes et délégation](/scopes-and-delegation).



# Créer ou mettre à jour une SPV externe
Source: https://developers.marko.fr/api-reference/spvs/créer-ou-mettre-à-jour-une-spv-externe

/openapi.json put /spvs/external/{external_id}
Upsert synchrone par identifiant partenaire. Une ressource MARKO supprimée logiquement est restaurée avec le même UUID. existing_marko_id permet de lier explicitement une SPV existante lors du premier envoi.

**Scope requis :** `spvs:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Créer une SPV
Source: https://developers.marko.fr/api-reference/spvs/créer-une-spv

/openapi.json post /spvs
Crée une SPV sur l'entité et le fonds ciblé. La forme juridique, le SIREN et l'adresse peuvent etre fournis des la creation. Le type d'investissement reste porte par l'operation, car une meme SPV peut en regrouper plusieurs.

**Scope requis :** `spvs:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Lister les SPV
Source: https://developers.marko.fr/api-reference/spvs/lister-les-spv

/openapi.json get /spvs
Permet de rechercher un SPV par nom exact insensible a la casse via `name`, et de filtrer par fonds via `fond_id`. Le filtre par nom est un controle avant creation, pas une garantie d'unicite concurrente; conservez l'identifiant MARKO et utilisez Idempotency-Key pour les ecritures. Les en-tetes X-Marko-Limit, X-Marko-Offset et X-Marko-Has-More decrivent la page.

**Scope requis :** `spvs:read`. [Scopes et délégation](/scopes-and-delegation).



# Mettre à jour une SPV
Source: https://developers.marko.fr/api-reference/spvs/mettre-à-jour-une-spv

/openapi.json put /spvs/{spv_id}
Met à jour les attributs d'une SPV.

**Scope requis :** `spvs:write`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer une SPV
Source: https://developers.marko.fr/api-reference/spvs/récupérer-une-spv

/openapi.json get /spvs/{spv_id}
Retourne le détail d'une SPV MARKO.

**Scope requis :** `spvs:read`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer une SPV par identifiant externe
Source: https://developers.marko.fr/api-reference/spvs/récupérer-une-spv-par-identifiant-externe

/openapi.json get /spvs/external/{external_id}
Résout l'identifiant stable du partenaire vers la SPV MARKO.

**Scope requis :** `spvs:read`. [Scopes et délégation](/scopes-and-delegation).



# Supprimer une SPV
Source: https://developers.marko.fr/api-reference/spvs/supprimer-une-spv

/openapi.json delete /spvs/{spv_id}
Supprime logiquement une SPV.

**Scope requis :** `spvs:write`. [Scopes et délégation](/scopes-and-delegation).



# Archiver une tâche
Source: https://developers.marko.fr/api-reference/tasks/archiver-une-tâche

/openapi.json delete /tasks/{task_id}
Archive une tâche Kanban.

**Scope requis :** `tasks:write`. [Scopes et délégation](/scopes-and-delegation).



# Créer un label de tâche
Source: https://developers.marko.fr/api-reference/tasks/créer-un-label-de-tâche

/openapi.json post /tasks/labels
Crée un label Kanban.

**Scope requis :** `tasks:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Créer une tâche
Source: https://developers.marko.fr/api-reference/tasks/créer-une-tâche

/openapi.json post /operations/{operation_id}/tasks
Crée une tâche Kanban pour une opération.

**Scope requis :** `tasks:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Lister les labels de tâches
Source: https://developers.marko.fr/api-reference/tasks/lister-les-labels-de-tâches

/openapi.json get /tasks/labels
Expose les labels Kanban disponibles.

**Scope requis :** `tasks:read`. [Scopes et délégation](/scopes-and-delegation).



# Lister les tâches agrégées
Source: https://developers.marko.fr/api-reference/tasks/lister-les-tâches-agrégées

/openapi.json get /tasks
Expose les tâches Kanban agrégées de l'entité.

**Scope requis :** `tasks:read`. [Scopes et délégation](/scopes-and-delegation).



# Lister les tâches d'une opération
Source: https://developers.marko.fr/api-reference/tasks/lister-les-tâches-dune-opération

/openapi.json get /operations/{operation_id}/tasks
Expose les tâches Kanban d'une opération donnée.

**Scope requis :** `tasks:read`. [Scopes et délégation](/scopes-and-delegation).



# Mettre à jour une tâche
Source: https://developers.marko.fr/api-reference/tasks/mettre-à-jour-une-tâche

/openapi.json put /tasks/{task_id}
Met à jour une tâche Kanban.

**Scope requis :** `tasks:write`. [Scopes et délégation](/scopes-and-delegation).



# Récupérer une tâche
Source: https://developers.marko.fr/api-reference/tasks/récupérer-une-tâche

/openapi.json get /tasks/{task_id}
Retourne une tâche Kanban unitaire.

**Scope requis :** `tasks:read`. [Scopes et délégation](/scopes-and-delegation).



# Réordonner une tâche
Source: https://developers.marko.fr/api-reference/tasks/réordonner-une-tâche

/openapi.json put /tasks/reorder
Déplace une tâche dans le board Kanban.

**Scope requis :** `tasks:write`. [Scopes et délégation](/scopes-and-delegation).



# Supprimer un label de tâche
Source: https://developers.marko.fr/api-reference/tasks/supprimer-un-label-de-tâche

/openapi.json delete /tasks/labels/{label_id}
Supprime un label Kanban.

**Scope requis :** `tasks:write`. [Scopes et délégation](/scopes-and-delegation).



# Lister une taxonomie d'entité
Source: https://developers.marko.fr/api-reference/taxonomies/lister-une-taxonomie-dentité

/openapi.json get /taxonomies
Retourne les options visibles décidées par l'administrateur de l'entité. Une option courante masquée peut être demandée avec current_code afin de rester affichable sans être proposée pour une nouvelle sélection.

**Scope requis :** `operations:read`. [Scopes et délégation](/scopes-and-delegation).



# Créer un dashboard personnalisé pour le sujet délégué
Source: https://developers.marko.fr/api-reference/users/créer-un-dashboard-personnalisé-pour-le-sujet-délégué

/openapi.json post /users/me/custom-dashboards
Exige une allowlist explicite sur la clé et la capacité `custom_dashboards`.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `custom_dashboards`. Le sujet doit être approuvé et appartenir à la même entité.

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Créer une vue sauvegardée pour le sujet délégué
Source: https://developers.marko.fr/api-reference/users/créer-une-vue-sauvegardée-pour-le-sujet-délégué

/openapi.json post /users/me/saved-views
Exige une allowlist explicite sur la clé et la capacité `saved_views`.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `saved_views`. Le sujet doit être approuvé et appartenir à la même entité.

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Déclencher un reset mot de passe
Source: https://developers.marko.fr/api-reference/users/déclencher-un-reset-mot-de-passe

/openapi.json post /users/{user_id}/actions/reset-password
Déclenche le flux Better Auth de reset ou réactivation.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Exercer le droit à l'effacement pour le sujet délégué
Source: https://developers.marko.fr/api-reference/users/exercer-le-droit-à-leffacement-pour-le-sujet-délégué

/openapi.json delete /users/me/rgpd/erasure
Exige une allowlist explicite sur la clé et la capacité `rgpd_erasure`, avec `{"confirm": true}`.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `rgpd_erasure`. Le sujet doit être approuvé et appartenir à la même entité.

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).

[Export, inventaire et effacement RGPD](/privacy-guide).



# Exporter les données personnelles du sujet délégué
Source: https://developers.marko.fr/api-reference/users/exporter-les-données-personnelles-du-sujet-délégué

/openapi.json get /users/me/rgpd/export
Exige une allowlist explicite sur la clé et la capacité `rgpd_export`.

**Scope requis :** `users:read`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `rgpd_export`. Le sujet doit être approuvé et appartenir à la même entité.

[Export, inventaire et effacement RGPD](/privacy-guide).



# Inviter un utilisateur
Source: https://developers.marko.fr/api-reference/users/inviter-un-utilisateur

/openapi.json post /users
Crée un utilisateur d'entité et déclenche le flux d'activation Better Auth.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Lire le profil d'un utilisateur délégué
Source: https://developers.marko.fr/api-reference/users/lire-le-profil-dun-utilisateur-délégué

/openapi.json get /users/me
Nécessite exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email` pour résoudre le sujet utilisateur dans la même entité.

**Scope requis :** `users:read`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `user_self_service`. Le sujet doit être approuvé et appartenir à la même entité.



# Lire les préférences d'alerte d'un utilisateur délégué
Source: https://developers.marko.fr/api-reference/users/lire-les-préférences-dalerte-dun-utilisateur-délégué

/openapi.json get /users/me/alert-preferences
Retourne les préférences d'alerte du sujet utilisateur délégué résolu via header.

**Scope requis :** `users:read`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `user_self_service`. Le sujet doit être approuvé et appartenir à la même entité.



# Lire les préférences d'un utilisateur délégué
Source: https://developers.marko.fr/api-reference/users/lire-les-préférences-dun-utilisateur-délégué

/openapi.json get /users/me/preferences
Retourne les préférences du sujet utilisateur délégué résolu via header.

**Scope requis :** `users:read`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `user_self_service`. Le sujet doit être approuvé et appartenir à la même entité.



# Lire un dashboard personnalisé du sujet délégué
Source: https://developers.marko.fr/api-reference/users/lire-un-dashboard-personnalisé-du-sujet-délégué

/openapi.json get /users/me/custom-dashboards/{dashboard_id}
Retourne un dashboard possédé par le sujet utilisateur délégué.

**Scope requis :** `users:read`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `custom_dashboards`. Le sujet doit être approuvé et appartenir à la même entité.



# Lire une vue sauvegardée du sujet délégué
Source: https://developers.marko.fr/api-reference/users/lire-une-vue-sauvegardée-du-sujet-délégué

/openapi.json get /users/me/saved-views/{view_id}
Retourne une vue sauvegardée possédée par le sujet utilisateur délégué.

**Scope requis :** `users:read`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `saved_views`. Le sujet doit être approuvé et appartenir à la même entité.



# Lister les dashboards personnalisés du sujet délégué
Source: https://developers.marko.fr/api-reference/users/lister-les-dashboards-personnalisés-du-sujet-délégué

/openapi.json get /users/me/custom-dashboards
Exige une allowlist explicite sur la clé et la capacité `custom_dashboards`.

**Scope requis :** `users:read`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `custom_dashboards`. Le sujet doit être approuvé et appartenir à la même entité.



# Lister les utilisateurs de l'entité
Source: https://developers.marko.fr/api-reference/users/lister-les-utilisateurs-de-lentité

/openapi.json get /users
Expose les utilisateurs Better Auth rattachés à l'entité de la clé.

**Scope requis :** `users:read`. [Scopes et délégation](/scopes-and-delegation).



# Lister les vues sauvegardées du sujet délégué
Source: https://developers.marko.fr/api-reference/users/lister-les-vues-sauvegardées-du-sujet-délégué

/openapi.json get /users/me/saved-views
Exige un sujet utilisateur délégué résolu via header, une allowlist explicite sur la clé, et la capacité `saved_views`.

**Scope requis :** `users:read`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `saved_views`. Le sujet doit être approuvé et appartenir à la même entité.



# Lister l'inventaire RGPD du sujet délégué
Source: https://developers.marko.fr/api-reference/users/lister-linventaire-rgpd-du-sujet-délégué

/openapi.json get /users/me/rgpd/inventory
Exige une allowlist explicite sur la clé et la capacité `rgpd_inventory`.

**Scope requis :** `users:read`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `rgpd_inventory`. Le sujet doit être approuvé et appartenir à la même entité.

[Export, inventaire et effacement RGPD](/privacy-guide).



# Mettre à jour le profil d'un utilisateur délégué
Source: https://developers.marko.fr/api-reference/users/mettre-à-jour-le-profil-dun-utilisateur-délégué

/openapi.json put /users/me
Met à jour le profil du sujet utilisateur délégué résolu via header.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `user_self_service`. Le sujet doit être approuvé et appartenir à la même entité.



# Mettre à jour les préférences d'alerte d'un utilisateur délégué
Source: https://developers.marko.fr/api-reference/users/mettre-à-jour-les-préférences-dalerte-dun-utilisateur-délégué

/openapi.json put /users/me/alert-preferences
Met à jour les préférences d'alerte du sujet utilisateur délégué résolu via header.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `user_self_service`. Le sujet doit être approuvé et appartenir à la même entité.



# Mettre à jour les préférences d'un utilisateur délégué
Source: https://developers.marko.fr/api-reference/users/mettre-à-jour-les-préférences-dun-utilisateur-délégué

/openapi.json put /users/me/preferences
Met à jour les préférences du sujet utilisateur délégué résolu via header.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `user_self_service`. Le sujet doit être approuvé et appartenir à la même entité.



# Mettre à jour un dashboard personnalisé du sujet délégué
Source: https://developers.marko.fr/api-reference/users/mettre-à-jour-un-dashboard-personnalisé-du-sujet-délégué

/openapi.json put /users/me/custom-dashboards/{dashboard_id}
Exige une allowlist explicite sur la clé et la capacité `custom_dashboards`.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `custom_dashboards`. Le sujet doit être approuvé et appartenir à la même entité.



# Mettre à jour un utilisateur
Source: https://developers.marko.fr/api-reference/users/mettre-à-jour-un-utilisateur

/openapi.json put /users/{user_id}
Met à jour le rôle d'un utilisateur de l'entité.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).



# Mettre à jour une vue sauvegardée du sujet délégué
Source: https://developers.marko.fr/api-reference/users/mettre-à-jour-une-vue-sauvegardée-du-sujet-délégué

/openapi.json put /users/me/saved-views/{view_id}
Exige une allowlist explicite sur la clé et la capacité `saved_views`.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `saved_views`. Le sujet doit être approuvé et appartenir à la même entité.



# Renvoyer une invitation
Source: https://developers.marko.fr/api-reference/users/renvoyer-une-invitation

/openapi.json post /users/{user_id}/actions/resend-invitation
Régénère le flux d'activation pour un utilisateur non activé.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Retirer un utilisateur
Source: https://developers.marko.fr/api-reference/users/retirer-un-utilisateur

/openapi.json delete /users/{user_id}
Annule immédiatement une invitation non activée ou retire les accès d'un compte actif et lance son workflow durable d'effacement RGPD.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



# Réactiver un utilisateur
Source: https://developers.marko.fr/api-reference/users/réactiver-un-utilisateur

/openapi.json post /users/{user_id}/actions/unsuspend
Réactive un utilisateur suspendu.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).



# Supprimer un dashboard personnalisé du sujet délégué
Source: https://developers.marko.fr/api-reference/users/supprimer-un-dashboard-personnalisé-du-sujet-délégué

/openapi.json delete /users/me/custom-dashboards/{dashboard_id}
Exige une allowlist explicite sur la clé et la capacité `custom_dashboards`.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `custom_dashboards`. Le sujet doit être approuvé et appartenir à la même entité.



# Supprimer une vue sauvegardée du sujet délégué
Source: https://developers.marko.fr/api-reference/users/supprimer-une-vue-sauvegardée-du-sujet-délégué

/openapi.json delete /users/me/saved-views/{view_id}
Exige une allowlist explicite sur la clé et la capacité `saved_views`.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).

**Délégation utilisateur :** exactement un header `X-Marko-Delegated-User-Id` ou `X-Marko-Delegated-User-Email`.

**Accès complémentaire :** allowlist utilisateur explicite sur la clé et capacité `saved_views`. Le sujet doit être approuvé et appartenir à la même entité.



# Suspendre un utilisateur
Source: https://developers.marko.fr/api-reference/users/suspendre-un-utilisateur

/openapi.json post /users/{user_id}/actions/suspend
Suspend un utilisateur activé de l'entité.

**Scope requis :** `users:write`. [Scopes et délégation](/scopes-and-delegation).



# Accepter une recommandation
Source: https://developers.marko.fr/api-reference/workflows/accepter-une-recommandation

/openapi.json post /workflows/recommendations/{recommendation_id}/accept
Acquitte une recommandation d'automatisation côté entité.

**Scope requis :** `workflows:write`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Activer ou désactiver un workflow
Source: https://developers.marko.fr/api-reference/workflows/activer-ou-désactiver-un-workflow

/openapi.json post /workflows/{workflow_id}/actions/toggle
Bascule l'état d'un workflow système ou personnalisé.

**Scope requis :** `workflows:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).

[Workflows et extraction IA](/workflows-guide).



# Créer un job AI extraction
Source: https://developers.marko.fr/api-reference/workflows/créer-un-job-ai-extraction

/openapi.json post /workflows/ai-extraction-jobs
Place un job d'extraction IA dans la file gouvernée pour un document.

**Scope requis :** `ai_extraction:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).

[Workflows et extraction IA](/workflows-guide).



# Créer un workflow depuis une recommandation
Source: https://developers.marko.fr/api-reference/workflows/créer-un-workflow-depuis-une-recommandation

/openapi.json post /workflows/recommendations/{recommendation_id}/create-workflow
Instancie un workflow personnalisé prérempli à partir d'une recommandation validée.

**Scope requis :** `workflows:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).

[Workflows et extraction IA](/workflows-guide).



# Créer un workflow personnalisé
Source: https://developers.marko.fr/api-reference/workflows/créer-un-workflow-personnalisé

/openapi.json post /workflows/workflow-definitions
Crée une définition de workflow personnalisée.

**Scope requis :** `workflows:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).

[Workflows et extraction IA](/workflows-guide).



# Lancer un workflow maintenant
Source: https://developers.marko.fr/api-reference/workflows/lancer-un-workflow-maintenant

/openapi.json post /workflows/workflow-definitions/{definition_id}/run
Déclenche une exécution manuelle d'un workflow personnalisé.

**Scope requis :** `workflows:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).

[Workflows et extraction IA](/workflows-guide).



# Lister les jobs AI extraction
Source: https://developers.marko.fr/api-reference/workflows/lister-les-jobs-ai-extraction

/openapi.json get /workflows/ai-extraction-jobs
Expose les jobs d'extraction IA de l'entité.

**Scope requis :** `ai_extraction:read`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Lister les presets de workflows
Source: https://developers.marko.fr/api-reference/workflows/lister-les-presets-de-workflows

/openapi.json get /workflows/presets
Expose les presets d'automatisation supportés.

**Scope requis :** `workflows:read`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Lister les recommandations d'automatisation
Source: https://developers.marko.fr/api-reference/workflows/lister-les-recommandations-dautomatisation

/openapi.json get /workflows/recommendations
Expose les recommandations d'automatisation calculées pour l'entité.

**Scope requis :** `workflows:read`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Lister les workflows
Source: https://developers.marko.fr/api-reference/workflows/lister-les-workflows

/openapi.json get /workflows
Expose les automatisations système et personnalisées de l'entité.

**Scope requis :** `workflows:read`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Lister l'historique workflows
Source: https://developers.marko.fr/api-reference/workflows/lister-lhistorique-workflows

/openapi.json get /workflows/history
Expose l'historique d'exécution des jobs et workflows.

**Scope requis :** `workflows:read`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Mettre à jour un workflow personnalisé
Source: https://developers.marko.fr/api-reference/workflows/mettre-à-jour-un-workflow-personnalisé

/openapi.json put /workflows/workflow-definitions/{definition_id}
Met à jour une définition de workflow personnalisée.

**Scope requis :** `workflows:write`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Préparer une recommandation pour décision
Source: https://developers.marko.fr/api-reference/workflows/préparer-une-recommandation-pour-décision

/openapi.json post /workflows/recommendations/materialize
Persiste une seule recommandation prévisualisée avant acceptation, report ou rejet.

**Scope requis :** `workflows:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).

[Workflows et extraction IA](/workflows-guide).



# Prévisualiser les recommandations d'automatisation
Source: https://developers.marko.fr/api-reference/workflows/prévisualiser-les-recommandations-dautomatisation

/openapi.json post /workflows/recommendations/preview
Calcule une vue de recommandations sans persister d'état serveur.

**Scope requis :** `workflows:read`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Rejeter une recommandation
Source: https://developers.marko.fr/api-reference/workflows/rejeter-une-recommandation

/openapi.json post /workflows/recommendations/{recommendation_id}/dismiss
Classe une recommandation comme non pertinente.

**Scope requis :** `workflows:write`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Reporter une recommandation
Source: https://developers.marko.fr/api-reference/workflows/reporter-une-recommandation

/openapi.json post /workflows/recommendations/{recommendation_id}/snooze
Snooze une recommandation pendant quelques jours ou jusqu'à une date donnée.

**Scope requis :** `workflows:write`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Récupérer un job AI extraction
Source: https://developers.marko.fr/api-reference/workflows/récupérer-un-job-ai-extraction

/openapi.json get /workflows/ai-extraction-jobs/{job_id}
Retourne le détail d'un job d'extraction IA.

**Scope requis :** `ai_extraction:read`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Statistiques workflows
Source: https://developers.marko.fr/api-reference/workflows/statistiques-workflows

/openapi.json get /workflows/stats
Expose un résumé des exécutions workflows.

**Scope requis :** `workflows:read`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Supprimer un workflow personnalisé
Source: https://developers.marko.fr/api-reference/workflows/supprimer-un-workflow-personnalisé

/openapi.json delete /workflows/workflow-definitions/{definition_id}
Supprime une définition de workflow personnalisée.

**Scope requis :** `workflows:write`. [Scopes et délégation](/scopes-and-delegation).

[Workflows et extraction IA](/workflows-guide).



# Authentification
Source: https://developers.marko.fr/authentication

Signez l'échange HMAC-SHA256 et utilisez le bearer renvoyé par MARKO.

L'API utilise deux éléments distincts : une **clé API** avec un identifiant public `key_id` et un secret, puis un **bearer de courte durée** pour les routes métier. Le secret sert uniquement à signer `POST /v1/auth/token` ; il ne doit pas être transmis aux routes métier ni utilisé dans un navigateur.

## Signature de l'échange

Construisez les quatre lignes suivantes avec des sauts de ligne `\n`, sans saut de ligne final :

```text theme={null}
MARKO-EXTERNAL-API-TOKEN-V1
{key_id}
{timestamp}
{nonce}
```

`timestamp` est l'heure Unix en secondes. Générez un `nonce` différent pour chaque échange. Calculez la signature HMAC-SHA256 de ce message avec le secret API et encodez-la en hexadécimal. Envoyez ensuite :

```http theme={null}
POST /v1/auth/token HTTP/1.1
Content-Type: application/json

{"key_id":"YOUR_PUBLIC_KEY_ID","timestamp":1760000000,"nonce":"UNIQUE_NONCE","signature":"HEX_HMAC_SHA256"}
```

La réponse inclut `access_token`, `expires_in`, `expires_at` et `environment`. Renouvelez le bearer après son expiration en créant un nouvel échange signé. Pour les autres routes, utilisez :

```http theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

Une clé peut être limitée par scopes, routes et adresses IP. Le scope nécessaire figure dans le texte de chaque page API et dans `x-marko-required-scope` de l'[OpenAPI enrichi](https://raw.githubusercontent.com/mathieuworoniecki/marko-developer-docs/main/openapi.json). L'administrateur de l'entité peut exporter une version du contrat filtrée selon une clé donnée. Les routes déléguées exigent aussi les [capacités et headers correspondants](/scopes-and-delegation).

## Contraintes de l'échange

`key_id` contient 4 à 24 lettres minuscules ou chiffres. Utilisez l'identifiant réel de la clé; les marqueurs `YOUR_PUBLIC_KEY_ID` des exemples doivent être remplacés. `nonce` contient 16 à 128 lettres ASCII, chiffres, `_` ou `-`. La signature contient exactement 64 caractères hexadécimaux et `timestamp` est un entier positif ou nul.

Synchronisez l'horloge de votre serveur. La fenêtre d'horloge et la durée du bearer sont configurables; utilisez `expires_in` et `expires_at` retournés plutôt qu'une durée codée en dur. Évitez de refaire un échange pour chaque appel : réutilisez le bearer jusqu'à son renouvellement, en coordonnant ce renouvellement si plusieurs workers partagent la clé.

Après un `401`, vérifiez d'abord que le bearer vient du même hôte et contexte, puis refaites au besoin un échange avec un **nouveau nonce**. Ne renvoyez pas aveuglément le payload signé d'un échange déjà consommé. Pour une écriture métier, le renouvellement du bearer ne change ni son intention ni sa clé d'idempotence.


# Documents et upload
Source: https://developers.marko.fr/documents-guide

Transmettre un fichier, comprendre la déclaration metadata et vérifier le document obtenu.

## Uploader directement le fichier

Pour envoyer le binaire et le rattacher à une opération, appelez directement `PUT /documents/external/{external_id}/upload` avec un **nouvel identifiant externe**. Il faut `documents:write`, une clé d'idempotence, le fichier, son `type` et `operation_id` ou `operation_external_id`.

```bash theme={null}
curl --fail-with-body -X PUT \
  "$MARKO_API_BASE_URL/documents/external/document-example-001/upload" \
  -H "Authorization: Bearer $MARKO_ACCESS_TOKEN" \
  -H "Idempotency-Key: document-example-001-upload-01" \
  -F "file=@./exemple.pdf;type=application/pdf" \
  -F "type=autre" \
  -F "operation_external_id=crm-example-001" \
  -F 'partner_metadata={"source":"crm","reference":"document-example-001"}'
```

L'opération d'exemple doit exister dans votre contexte. Laissez cURL créer le header `Content-Type` et sa boundary multipart. N'envoyez pas le fichier en Base64. Dans un formulaire multipart, `partner_metadata` est une **chaîne contenant un objet JSON**, contrairement à la déclaration JSON où c'est un objet.

Lorsque les deux identifiants d'opération sont fournis, `operation_id` est utilisé. La lecture applicative est bornée à 500 Mio dans la version documentée; un proxy ou l'infrastructure peut imposer une limite inférieure. Le message d'erreur actuel de dépassement mentionne encore « 50 MB » : ce texte ne décrit pas la constante applicative effective.

## Réponses et reprises

La réponse contient `external_id`, `document_id`, `created` et `document`. Une création répond `201`, une référence existante `200`. Conservez le `document_id` et relisez `GET /documents/{document_id}` avec `documents:read` pour vérifier ses métadonnées et l'URL de téléchargement disponible.

La reprise compare notamment le contenu du fichier, son nom, son type et les métadonnées de l'appel initial. Réutilisez la même clé et le même contenu; un identifiant externe déjà associé à un autre contenu peut produire `409`. N'utilisez pas cette route pour remplacer arbitrairement un fichier existant.

## Déclaration metadata

`PUT /documents/external/{external_id}` déclare une fiche documentaire JSON sans envoyer de binaire. Elle exige aussi une opération et `documents:write`. Cette route ne constitue pas une étape obligatoire avant `/upload`.

Dans la version documentée, `/upload` peut renvoyer une fiche déjà déclarée sous le même identifiant externe **sans lui ajouter le fichier**. Pour importer réellement un fichier, commencez donc par l'upload direct avec un identifiant externe neuf. Une réponse `200` ou `created=false` ne prouve pas qu'un fichier vient d'être stocké.

## Modifier ou rattacher un document

`PUT /documents/{document_id}` modifie les métadonnées; il ne remplace pas le contenu binaire. `POST /documents/{document_id}/attach-operation` rattache atomiquement un document non affecté. Une nouvelle intention échoue si le document est déjà rattaché; une reprise avec la même clé conserve la première réponse lorsque la déduplication applicable est active.

Les droits dataroom et le contexte de la clé restent applicables. Une URL absente peut correspondre à une fiche sans fichier ou à une disponibilité limitée; vérifiez les propriétés renvoyées. La suppression documentaire est logique et ne doit pas être assimilée à une promesse d'effacement immédiat de toutes les copies.


# Environnements
Source: https://developers.marko.fr/environments

Distinguez les hôtes de préproduction et production des clés sandbox et live.

| Usage | Base URL |
| - | - |
| Préproduction de l'infrastructure MARKO | `https://partner-api-preprod.marko.fr/v1` |
| Production | `https://partner-api.marko.fr/v1` |

Les clés d'API portent également un environnement `sandbox` ou `live`, choisi lors de leur création dans MARKO. **Le choix de l'hôte et celui de la clé sont deux décisions distinctes.** Utilisez les identifiants fournis pour l'environnement et l'entité visés ; la réponse de `POST /v1/auth/token` indique l'environnement associé à la clé.

Le contrat public de production est disponible sur [OpenAPI](https://partner-api.marko.fr/v1/openapi.json). Il présente les opérations stables. L'administrateur de l'entité peut télécharger depuis la section **API** un contrat OpenAPI ou une collection Postman adaptés aux scopes et aux routes autorisés pour sa clé.


# Erreurs et reprises
Source: https://developers.marko.fr/errors-and-retries

Interprétez les erreurs HTTP et utilisez les clés d'idempotence sur les écritures concernées.

Les erreurs documentées dans le contrat public utilisent `application/problem+json`. Fournissez un en-tête `X-Request-ID` pour corréler vos appels avec les journaux MARKO ; le corps d'erreur peut également contenir `request_id`.

| Statut | Sens | Action |
| - | - | - |
| `400` | Header, combinaison de paramètres ou demande invalide | Corriger la requête, notamment l'idempotence ou les headers de délégation. |
| `401` | Échange ou bearer invalide ou expiré | Vérifier la signature, l'horloge et le bearer ; refaire un échange avec un nouveau nonce si nécessaire. |
| `403` | Scope, route ou IP non autorisé | Vérifier les droits de la clé avec l'administrateur de l'entité. |
| `404` | Ressource absente ou non accessible dans ce contexte | Vérifier l'identifiant et l'entité; ne pas changer de clé pour contourner les droits. |
| `409` | Conflit d'idempotence, d'association, de cible ou de version source | Diagnostiquer le conflit; ne pas le masquer en générant une autre clé. |
| `412` | Précondition/version non satisfaite sur une route qui l'exige | Relire la ressource et réévaluer l'intention avant une nouvelle mutation. |
| `413` | Limite de taille du serveur ou proxy | Réduire ou découper l'envoi selon les limites de la route. |
| `422` | Paramètre ou corps invalide | Corriger la requête selon l'endpoint. |
| `428` | `Idempotency-Key` requis mais absent | Ajouter une clé d'idempotence à cette écriture. |
| `429` | Limite de débit atteinte | Respecter `Retry-After` quand il est présent. |
| `500` | Erreur serveur | Réessayer prudemment ; conserver la même clé d'idempotence pour une écriture déjà soumise. |
| `503` | Service ou stockage temporairement indisponible | Reprendre avec attente, en conservant l'identité de la mutation; diagnostiquer si cela persiste. |

Tous ces statuts ne s'appliquent pas à toutes les routes. La page de référence décrit les réponses du contrat; certains refus métier ou de l'infrastructure peuvent ajouter un statut. Un dépassement de fichier peut également être exposé en `422` par l'application.

## Lire le problème retourné

```json theme={null}
{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "The API key does not allow this operation.",
  "request_id": "example-request-001"
}
```

Cet exemple est synthétique. `detail` décrit le problème et peut contenir des informations métier structurées selon la route. Conservez le statut, le `request_id` et les codes structurés lorsqu'ils sont disponibles. Évitez de dépendre de la traduction ou du texte exact d'un message.

## Politique de reprise

Corrigez les erreurs de validation et d'accès avant de réessayer. Pour `429`, respectez `Retry-After` lorsqu'il est fourni. Pour une panne transitoire ou une coupure, utilisez une attente croissante, un léger aléa et un nombre de tentatives borné; le timeout HTTP ne prouve pas qu'une mutation a échoué.

Si votre SDK attend toujours du JSON, traitez séparément les réponses `204` sans corps, les exports binaires et les erreurs renvoyées par un proxy. Pour les jobs, continuez le suivi de l'identifiant connu plutôt que de soumettre un nouveau lot.

Les opérations d'écriture qui exigent `Idempotency-Key` l'indiquent dans leur page de référence. Générez une clé unique pour chaque mutation logique et réutilisez **la même clé et le même contenu** lors d'une reprise après une réponse incertaine. N'envoyez pas une mutation une seconde fois avec une nouvelle clé tant que vous n'avez pas vérifié son résultat.

Consultez [Écritures et idempotence](/writes-and-idempotency) pour les reprises et [Pagination et données](/pagination-and-data) pour les listes.


# Imports et notes
Source: https://developers.marko.fr/imports-and-notes

Importer un lot durable, suivre chaque élément et préserver les dates historiques des notes.

## Choisir le mode d'import

Pour une ressource à la fois, les upserts externes opérations, SPV, opérateurs et notes renvoient immédiatement la cible MARKO. Pour un lot d'opérations avec leurs notes, utilisez `POST /operations/batch` avec `operations:write` et `Idempotency-Key`.

Le lot accepte **1 à 500 opérations**, **10 000 notes au total** et une enveloppe normalisée d'au plus **20 Mio**. Une opération importée est également soumise à la limite de 20 Mio. Découpez les gros imports avant l'envoi et conservez les identifiants externes entre les lots.

```json theme={null}
{
  "operations": [
    {
      "external_id": "crm-example-001",
      "name": "Exemple MARKO",
      "notes": [
        {
          "external_id": "note-example-001",
          "date": "2026-10-01T10:00:00Z",
          "text": "Note historique synthétique.",
          "category": "libre",
          "source_updated_at": "2026-10-01T10:00:00Z"
        }
      ]
    }
  ]
}
```

Ce JSON est un exemple synthétique, pas une donnée présente dans votre entité.

## Suivre le job jusqu'au résultat métier

Une réponse `202` contient `job_id`, `status_url`, `results_url` et les compteurs reçus. Elle signifie que le lot est accepté, pas que chaque élément a réussi.

1. Conservez `job_id` durablement dans votre intégration.
2. Consultez `GET /import-jobs/{job_id}` avec `operations:read` et un délai entre lectures.
3. Lisez `GET /import-jobs/{job_id}/items` en paginant ses résultats. Utilisez `status` et `item_kind` pour isoler les échecs ou conflits.
4. Exploitez les compteurs `completed_items`, `noop_items`, `failed_items` et `conflict_items`, puis relisez les ressources dont vous avez besoin.

Chaque élément contient son identifiant externe, son statut, ses tentatives et, lorsqu'ils existent, `target_id`, `result`, `error_code`, `error_message` et `conflict_payload`. Une erreur locale ne signifie pas que tout le lot a été annulé.

`POST /import-jobs/{job_id}/retry` réenfile un job `failed` ou `partial`; les éléments déjà terminés restent des no-op. `POST /import-jobs/{job_id}/cancel` demande un arrêt au prochain point de reprise durable. Une annulation n'est pas un rollback des éléments déjà persistés. Ces actions exigent `operations:write` et une clé d'idempotence.

## Notes historiques

La route `PUT /operations/external/{operation_external_id}/notes/external/{note_external_id}` importe une note dans une opération déjà résolue. Le GET équivalent vérifie aussi que la note appartient à l'opération externe indiquée.

`date` est la date métier. Une date `YYYY-MM-DD` est normalisée à minuit UTC; une date-heure doit inclure un fuseau. `source_created_at` et `source_updated_at`, lorsqu'ils sont fournis, doivent inclure un fuseau; la mise à jour source ne peut pas précéder la création source.

Pour une note déjà versionnée, un contenu modifié doit fournir un `source_updated_at` strictement plus récent. Ne réécrivez pas l'histoire en utilisant l'heure d'import à la place de la date source. Un conflit doit être résolu dans votre synchronisation avant reprise.

`category` est une chaîne de 1 à 80 caractères, `libre` par défaut. Les valeurs usuelles incluent `call`, `comite` et `juridique`. L'import externe peut créer une option d'entité inconnue; conservez les codes et les `taxonomy_additions` retournés. Les routes `/comments` restent utiles pour les notes ordinaires sans identifiant externe.

## Notes traduites

Fournissez `text` ou un `description_i18n` non vide. Chaque texte contient au plus 10 000 caractères. `description_i18n` accepte au plus 20 locales, 100 000 caractères agrégés et des codes de locale d'au plus 35 caractères. Les locales sont normalisées en minuscules avec des tirets; une collision après normalisation est refusée.

Sans `text`, MARKO choisit une traduction française, puis anglaise, puis la première locale triée pour le texte principal. Les notes importées sont aussi visibles dans la chronologie; le récit peut exposer `note_date`, `note_text` et `note_category` dans ses métadonnées.


# Développer avec MARKO
Source: https://developers.marko.fr/index

Les guides et la référence pour intégrer l'API partenaire MARKO.

Connectez votre application aux données de votre entité et automatisez les opérations autorisées par votre clé API.

<Columns>
  <Card title="Premier appel" icon="terminal" href="/quickstart">
    Obtenez une clé et envoyez votre première requête avec un exemple Python.
  </Card>

  <Card title="Authentification" icon="key" href="/authentication">
    Signez l'échange HMAC et utilisez le bearer pour vos appels API.
  </Card>

  <Card title="Référence API" icon="code" href="/api-reference/auth/obtenir-un-bearer-court">
    Explorez les endpoints, leurs paramètres et les réponses.
  </Card>

  <Card title="Erreurs et reprises" icon="arrows-rotate" href="/errors-and-retries">
    Gérez les erreurs, la pagination et les requêtes idempotentes.
  </Card>
</Columns>

## Votre intégration

L'API utilise un bearer obtenu par un échange signé côté serveur. Les routes accessibles dépendent des scopes et des éventuelles restrictions de votre clé.

**URL de production**

```text theme={null}
https://partner-api.marko.fr/v1
```

Pour préparer vos tests, consultez le guide des [environnements](/environments). Un administrateur de l'entité peut exporter depuis MARKO un contrat OpenAPI ou une collection Postman filtrés pour votre clé.

## Développer avec une IA

<CopyDocumentation />

Le menu de chaque page permet aussi de copier son contenu en Markdown ou de l'ouvrir dans Claude ou ChatGPT. Donnez à votre agent l'[index de la documentation](https://developers.marko.fr/llms.txt) et le [contrat OpenAPI enrichi](https://raw.githubusercontent.com/mathieuworoniecki/marko-developer-docs/main/openapi.json). Le guide [IA et outils de développement](/ai-and-tools) présente les formats disponibles.


# Pagination et données
Source: https://developers.marko.fr/pagination-and-data

Lire toutes les pages, utiliser les filtres exacts et interpréter les types métier.

## Deux formes de pagination

La référence de chaque route indique ses valeurs par défaut, bornes et filtres. Les limites ne sont pas uniformes : n'appliquez pas une valeur globale à toutes les ressources.

| Forme | Lecture |
| - | - |
| Objet avec `items`, `total`, `limit`, `offset` | Parcourir `items`, puis augmenter `offset` du nombre d'éléments reçus jusqu'à atteindre `total` ou une page vide. |
| Tableau JSON | Lire le tableau et avancer avec `offset` jusqu'à une page plus courte que `limit` ou vide. Les listes fonds et SPV exposent aussi `X-Marko-Limit`, `X-Marko-Offset` et `X-Marko-Has-More`; la liste opérations n'expose pas ces headers. |
| Paramètre `page` | Respecter le numéro de première page et la limite de la route; ne pas mélanger `page` et `offset`. |

Un parcours paginé n'est pas un instantané transactionnel : des modifications peuvent intervenir entre deux lectures. Conservez les identifiants, dédupliquez vos résultats et effectuez une nouvelle lecture si votre traitement dépend d'un état courant.

```bash theme={null}
curl --fail-with-body --get "$MARKO_API_BASE_URL/operations" \
  -H "Authorization: Bearer $MARKO_ACCESS_TOKEN" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"
```

`MARKO_API_BASE_URL` contient le préfixe `/v1`, par exemple `https://partner-api.marko.fr/v1`.

## Recherche et filtres

`GET /operations` et `GET /spvs` proposent `name` pour une correspondance exacte insensible à la casse et aux espaces périphériques. `GET /operateurs` distingue `name` exact et `search` partiel; ces deux filtres sont mutuellement exclusifs. Une recherche par nom avant création ne garantit pas l'unicité concurrente. Pour une synchronisation, préférez les [identifiants externes](/writes-and-idempotency).

Les filtres de statut utilisent les codes retournés par les [taxonomies](/taxonomies-guide). Le filtre `status=active` de la liste opérations est un raccourci documenté vers les cinq statuts canoniques actifs. Ne traduisez pas un libellé d'interface pour fabriquer un code.

Encodez les valeurs des paramètres et segments d'URL avec la bibliothèque HTTP utilisée. Pour les paramètres booléens, utilisez `true` ou `false`; la référence enrichie indique leur type réel.

## Identifiants, dates et valeurs

Les UUID MARKO et les identifiants externes sont deux valeurs différentes. Les identifiants utilisateur peuvent être des chaînes non UUID. Le schéma de la route fait autorité.

Les dates sont en ISO 8601. Une date métier `YYYY-MM-DD` ne porte pas de fuseau; une date-heure telle que `2026-10-01T10:00:00Z` en porte un. Les notes externes ont des règles de normalisation spécifiques décrites dans [Imports et notes](/imports-and-notes).

Un champ absent et un champ `null` ne sont pas interchangeables dans une mutation. N'envoyez que les propriétés que vous souhaitez traiter et respectez le modèle d'update de la route. Certains montants décimaux sont sérialisés en chaîne pour préserver leur précision; respectez le type de réponse, sans convertir systématiquement en flottant.

## Champs métier extensibles

`data`, certains résumés, configurations de workflow et métadonnées sont des objets JSON ouverts par conception. Pour les champs métier des opérations, interrogez `GET /field-definitions` ou `GET /field-definitions/by-key/{field_key}` : le référentiel décrit les clés et leurs métadonnées métier. Vérifiez l'unité, le type et la disponibilité d'un champ avant de l'écrire; ne déduisez pas une unité monétaire ou un pourcentage de son nom.


# Données personnelles et RGPD
Source: https://developers.marko.fr/privacy-guide

Comprendre les exports délégués, leur couverture et les résultats d'effacement durables.

Ces routes s'appliquent au sujet utilisateur explicitement délégué dans l'entité de la clé. Elles exigent le scope `users:read` ou `users:write`, une allowlist explicite et la capacité correspondante. Consultez [Scopes et délégation](/scopes-and-delegation) avant de les appeler.

## Inventaire

`GET /users/me/rgpd/inventory` décrit les sources connues, champs, champs personnels et présence de données. `auth_database` couvre les sources du compte; `entity_databases` décrit le périmètre des bases d'entité, les compteurs et les avertissements.

Un compteur `null` avec un avertissement signale une source non inspectée; il ne signifie pas zéro donnée. L'inventaire ne contient pas nécessairement les enregistrements eux-mêmes et ne vaut pas confirmation d'effacement.

## Export JSON

`GET /users/me/rgpd/export` renvoie un téléchargement JSON `marko_privacy_export/v2`, avec le header `X-Marko-Privacy-Case-Id`. Stockez le fichier dans un emplacement adapté aux données personnelles et conservez l'identifiant du dossier.

Le fichier contient notamment le profil, les préférences, les sources centrales autorisées, les projections de l'entité courante et un **manifest**. La référence détaille aussi les projections exportées par source. Certaines sources sont volontairement limitées aux métadonnées : les binaires des pièces jointes, les prompts IA chiffrés, les résultats chiffrés de fournisseurs et certaines données métier de tiers ne sont pas intégrés.

Les notifications et audits centraux dont le périmètre d'entité ne peut pas être prouvé sont retenus : leurs tableaux centraux peuvent être vides alors que le manifest signale des enregistrements détectés et un export incomplet.

Vérifiez `manifest.complete`, `failed_required_sources`, le statut de chaque source et ses limitations. `case_finalization_pending=true` indique que la finalisation du dossier a lieu après la livraison du fichier. Ne transformez pas la présence d'un JSON ou `HTTP 200` en preuve que toutes les sources ont été exportées. Aucun certificat ni URL de téléchargement temporaire n'est promis par cet export.

## Effacement délégué

`DELETE /users/me/rgpd/erasure` exige `users:write`, la capacité `rgpd_erasure`, l'utilisateur délégué, `Idempotency-Key` et ce corps :

```json theme={null}
{"confirm": true}
```

La réponse est limitée aux métadonnées : `privacy_case_id`, `status`, `result_mode=metadata_only`, besoins de réconciliation ou de revue manuelle, éventuelle référence de certificat, date de fin, actions et drapeau `replayed`.

`202` indique un dossier accepté dont le traitement n'est pas terminé; `200` correspond à un dossier terminé. Une réponse rejouée ne déclenche pas automatiquement un nouvel effacement. Un dossier bloqué ou en réconciliation demande un suivi avec l'administrateur ou le support; n'envoyez pas de nouvelles clés pour forcer son passage.

La suppression d'un utilisateur par `/users/{user_id}` et l'exercice du droit à l'effacement délégué sont des contrats distincts. Une invitation non activée peut être annulée immédiatement; un compte actif suit un workflow durable de retrait d'accès et d'effacement. Les données métier conservées et les obligations de conservation doivent être interprétées selon le dossier effectif.


# Premier appel
Source: https://developers.marko.fr/quickstart

Créez un bearer puis listez les opérations accessibles à votre clé MARKO.

## Prérequis

Un administrateur technique de votre entité crée une clé dans la section **API** de MARKO et vous transmet son `key_id` et son secret par un canal sécurisé. La clé doit inclure le scope `operations:read` pour l'exemple ci-dessous. Conservez le secret uniquement côté serveur.

Définissez `MARKO_KEY_ID` et `MARKO_API_SECRET` dans l'environnement de votre processus. Pour une clé de préproduction, définissez également `MARKO_API_BASE_URL=https://partner-api-preprod.marko.fr/v1`.

## Échanger la clé et appeler l'API

L'exemple utilise seulement la bibliothèque standard Python. Il crée un nonce unique, signe le message canonique, récupère un bearer court, puis lit une page d'opérations.

```python theme={null}
import hashlib
import hmac
import json
import os
import secrets
import time
import urllib.request

base_url = os.getenv("MARKO_API_BASE_URL", "https://partner-api.marko.fr/v1").rstrip("/")
key_id = os.environ["MARKO_KEY_ID"]
secret = os.environ["MARKO_API_SECRET"]
timestamp = int(time.time())
nonce = secrets.token_urlsafe(24)
message = f"MARKO-EXTERNAL-API-TOKEN-V1\n{key_id}\n{timestamp}\n{nonce}"
signature = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()

payload = json.dumps({
    "key_id": key_id,
    "timestamp": timestamp,
    "nonce": nonce,
    "signature": signature,
}).encode()
token_request = urllib.request.Request(
    f"{base_url}/auth/token",
    data=payload,
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(token_request, timeout=30) as response:
    access_token = json.load(response)["access_token"]

operations_request = urllib.request.Request(
    f"{base_url}/operations?limit=1",
    headers={"Authorization": f"Bearer {access_token}"},
)
with urllib.request.urlopen(operations_request, timeout=30) as response:
    print(json.dumps(json.load(response), indent=2, ensure_ascii=False))
```

Une réponse `403` sur le second appel indique notamment que le scope ou la route n'est pas autorisé pour cette clé. Consultez [les erreurs et les reprises](/errors-and-retries) et la référence de l'endpoint concerné.


# Ressources de l'API
Source: https://developers.marko.fr/resources

Trouver les familles métier et choisir les routes utiles à votre intégration.

La référence du menu contient toutes les **158 opérations stables** du contrat public documenté. Les routes bêta et l'administration interne n'en font pas partie. Dépliez une famille pour lire ses endpoints, champs, réponses, scopes et contraintes.

| Famille | Utilisation |
| - | - |
| Authentification | Échanger une signature HMAC contre un bearer court. |
| Entité et portefeuille | Lire le contexte de l'intégration, les agrégats portefeuille et le résumé RCCI. |
| Deals | Pipeline CRM avant closing, détail et notes attachées. |
| Fonds et SPV | Structures d'investissement, rattachements et synchronisation externe des SPV. |
| Opérateurs | Identités et métadonnées, synchronisation externe et risques tiers. |
| Opérations | Liste, détail, synchronisation externe, imports et notes. |
| Taxonomies et champs métier | Codes visibles de l'entité et définitions des propriétés métier. |
| Chronologie | Événements paginés et récit d'une opération. |
| Documents | Fiches, téléchargement disponible, upload et rattachement. |
| Utilisateurs | Gestion des utilisateurs de l'entité, activation, suspension et actions de compte. |
| Utilisateur délégué | Profil, préférences, vues sauvegardées, dashboards et traitement RGPD. |
| Paramètres | Paramètres métier, reporting et branding de l'entité. |
| Recherche | Recherche transversale des ressources ou du contenu documentaire indexé. |
| Alertes et notifications | Lecture, acquittement, résolution, report et faux positifs selon la ressource. |
| Calendrier | Événements persistés, modifications et décisions d'acceptation ou de rejet. |
| Enrichissement SIREN | Lecture locale, validation et résolution fournisseur explicite. |
| Remboursements | Échéances/remboursements enregistrés sur une opération. |
| Reporting | Export INREV XLSX, templates et aperçus tabulaires. |
| Workflows | Presets, définitions, exécutions, historique et recommandations. |
| Extraction IA | Jobs documentaires, suivi et résultats publics. |
| Tâches | Board Kanban, tâches d'opération, réordonnancement et labels. |

## Enrichissement SIREN

`GET /enrichment/siren/{siren}` lit le cache ou les données locales sans déclencher d'appel facturable. `/validate` vérifie le format et le checksum sans fournisseur externe. Pour une résolution pouvant appeler Pappers, utilisez explicitement `POST /enrichment/siren/{siren}/resolve`, avec `operateurs:write` et une clé d'idempotence.

Supprimer le cache ne déclenche pas une nouvelle résolution. Après une réponse incertaine d'une résolution fournisseur, conservez la même clé pour la même intention afin de préserver sa réconciliation; ne créez pas une nouvelle clé pour forcer un appel.

## Reporting binaire

`GET /reports/inrev` renvoie un fichier XLSX et non du JSON. Votre client doit lire des octets et enregistrer le fichier, en vérifiant le statut et le type de contenu avant de le considérer comme un classeur. Les autres routes de templates et d'aperçu renvoient leurs modèles JSON décrits dans la référence.

## Quel endpoint choisir ?

Pour une synchronisation depuis un CRM, commencez par les [écritures externes](/writes-and-idempotency), puis les [imports et notes](/imports-and-notes). Pour un document, suivez [l'upload direct](/documents-guide). Pour une interface d'un utilisateur, vérifiez d'abord [la délégation et ses capacités](/scopes-and-delegation).


# Scopes et délégation
Source: https://developers.marko.fr/scopes-and-delegation

Choisir les droits de l'intégration et appeler les routes d'un utilisateur délégué.

Chaque clé est rattachée à une entité et à un environnement de données. Le bearer conserve ce contexte : un paramètre, un identifiant ou un header ne permet pas de changer d'entité. Les droits peuvent combiner **scopes**, **routes autorisées**, **restrictions IP** et, pour certains documents, droits d'accès à la dataroom. Une route présente dans cette documentation n'est donc pas automatiquement accessible à votre clé.

Le scope requis apparaît sur chaque page de la référence. Demandez à l'administrateur les droits nécessaires à votre intégration et son export OpenAPI filtré par clé. `POST /auth/token` est l'exception : l'échange signé ne nécessite pas de bearer préalable.

## Lecture et écriture

Les scopes `*:read` permettent les lectures de la famille concernée et les scopes `*:write` ses mutations. Certaines routes utilisent un scope d'une autre famille : les remboursements demandent `operations:*`, l'enrichissement SIREN `operateurs:*`, le résumé RCCI `portfolio:read` et les jobs d'extraction `ai_extraction:*`.

La référence est autoritative pour le scope d'une opération : ne le déduisez pas du verbe HTTP. Par exemple, `POST /workflows/recommendations/preview` demande `workflows:read`.

## Routes /users/me

Ces routes concernent le **sujet utilisateur délégué**, pas un compte implicitement choisi à partir de la clé. Fournissez exactement un des deux headers :

```http theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Marko-Delegated-User-Email: integration@example.com
```

Vous pouvez remplacer le header email par `X-Marko-Delegated-User-Id`. N'envoyez pas les deux. L'utilisateur doit appartenir à l'entité de la clé, avoir le statut approuvé et être autorisé par l'allowlist utilisateur de la clé.

Les routes ci-dessous exigent aussi une allowlist utilisateur **explicitement renseignée**, une capacité et le scope de lecture ou d'écriture correspondant :

| Routes | Capacité |
| - | - |
| Profil, préférences et préférences d'alerte `/users/me` | `user_self_service` |
| `/users/me/saved-views` | `saved_views` |
| `/users/me/custom-dashboards` | `custom_dashboards` |
| `/users/me/rgpd/export` | `rgpd_export` |
| `/users/me/rgpd/inventory` | `rgpd_inventory` |
| `/users/me/rgpd/erasure` | `rgpd_erasure` |

La délégation ne contourne pas les droits du sujet : certaines écritures sont refusées pour un utilisateur en lecture seule. Les vues et dashboards délégués sont soumis à leurs règles de propriété.

## Diagnostiquer un refus

Un header manquant ou les deux headers ensemble produisent `400`. Un sujet introuvable dans l'entité produit `404`. Un utilisateur non approuvé, non autorisé ou une capacité absente produit `403`. Ajoutez `X-Request-ID` pour permettre au support de retrouver la requête sans transmettre votre secret ni votre bearer.

Pour les routes RGPD, consultez [le traitement des données personnelles](/privacy-guide).

## Vues sauvegardées

Le nom de vue est normalisé et doit rester non vide. L'état `filters`, `columns` et `sort` est limité à 16 384 octets JSON; les bornes sont de 24 clés de filtre, 64 colonnes et 4 clés de tri. Les tokens d'icône et de couleur acceptés figurent dans le schéma de création et de mise à jour.

Pour une vue `operations`, les clés de filtre sont `preset`, `search`, `statut`, `statut_interne`, `statut_operationnel`, `cycle_interne`, `classe_actif`, `type_investissement` et `operateur_id`. `status` n'est pas une clé de filtre acceptée pour cet objet, même si d'autres endpoints utilisent ce paramètre. Le tri utilise `sort_by` et `sort_order` (`asc` ou `desc`); colonnes et champs de tri sont contrôlés par les allowlists du schéma. Les mises à jour restent soumises au type de la vue déjà enregistrée.


# Taxonomies
Source: https://developers.marko.fr/taxonomies-guide

Utiliser les codes visibles de l'entité et gérer les options créées par les imports externes.

## Catalogue visible

`GET /taxonomies?dimension=...` avec `operations:read` fournit les options visibles de l'entité. Les dimensions couvrent notamment le statut, le type d'investissement, le type d'opération, la classe et sous-classe d'actif, les statuts internes ou opérationnels et les catégories de notes. Utilisez les valeurs exactes de `dimension` indiquées dans la référence.

Conservez le **code**, distinct du libellé affiché. Les options peuvent dépendre de l'entité et des décisions de son administrateur. Pour afficher une valeur courante masquée sans la proposer à une nouvelle sélection, fournissez `current_code` à la route du catalogue.

`GET /operations/taxonomy` est un endpoint legacy limité au socle canonique historique. Il ne décrit pas toutes les valeurs propres à l'entité. Pour construire un formulaire ou vérifier les options visibles, utilisez `/taxonomies`.

## Upserts externes

Les upserts externes d'opérations et de notes peuvent transformer une valeur inconnue en option visible propre à l'entité. La réponse expose `taxonomy_additions` pour signaler ces créations. Le segment généré d'un code `custom__...` est imprévisible : conservez **le code renvoyé**, puis réutilisez-le.

Cette règle ne signifie pas que toutes les routes de mise à jour créent des catégories. Respectez le contrat de chaque endpoint. Si votre intégration doit utiliser uniquement les choix validés par l'administrateur, chargez le catalogue visible avant l'envoi et empêchez les valeurs inconnues côté client.

## Valeurs absentes et relations

Respectez les champs facultatifs et leurs types; n'inventez pas un statut ou une classe d'actif pour compléter un exemple. Les champs `statut_operationnel` peuvent être une liste. La sous-classe doit rester cohérente avec la classe d'actif selon les règles métier de l'entité.

Après un upsert, relisez la ressource ou exploitez la ressource retournée pour connaître les valeurs effectivement retenues. La référence des [champs métier](/pagination-and-data) complète les taxonomies pour les propriétés de `data`.


# Workflows et extraction IA
Source: https://developers.marko.fr/workflows-guide

Distinguer définitions, exécutions, recommandations et jobs d'analyse documentaire.

## Définitions et presets

`GET /workflows/presets` décrit les presets, leurs champs, choix et configurations par défaut. `GET /workflows` retourne les automatisations système et personnalisées avec leurs drapeaux `editable`, `deletable` et `toggleable`. L'identifiant d'une définition peut être une clé textuelle, pas un UUID.

Créez ou modifiez une définition personnalisée avec `/workflows/workflow-definitions`. Le preset détermine la structure de `config`. Les modes de planification pris en charge sont `manual`, `daily`, `weekly` et `monthly`; consultez le preset pour sa configuration. Remplacez les destinataires de démonstration par ceux que votre organisation a validés avant d'activer un workflow.

Les presets actuels couvrent l'escalade sponsor de reporting, le digest comité, les tâches de kickoff closing, les relances documentaires, la veille contentieuse et le suivi des covenants. Le catalogue GET reste la source à consulter avant de construire une configuration.

Les automatisations système ne sont pas toutes modifiables. `kanban-auto-promote` reste verrouillée et son activation produit `409`; ne contournez pas une étape de confirmation humaine en tentant de l'activer.

## Exécution et historique

`POST /workflows/workflow-definitions/{definition_id}/run` exige `workflows:write` et une clé d'idempotence. Sa réponse `202` contient `workflow` et `run`. Consultez `/workflows/history` pour l'historique et `/workflows/stats` pour les compteurs. Un run peut être `pending`, `running`, `completed`, `failed` ou `cancelled`.

L'historique rassemble deux formes : les jobs système avec `workflow_source=system` et les runs personnalisés avec `workflow_source=custom`. Les propriétés spécifiques à une forme ne sont pas garanties dans l'autre. Les objets `result` dépendent du preset ou du type de job.

Une réponse d'acceptation ne prouve pas l'achèvement de ses effets. Vérifiez le statut, le résultat puis les ressources concernées; une exécution en échec ne doit pas être qualifiée de réussite à partir du seul HTTP initial.

## Recommandations

`POST /workflows/recommendations/preview` calcule une prévisualisation sans persister de recommandation et demande `workflows:read`. Les identifiants `preview-*` sont temporaires : ils ne sont pas les UUID utilisés par les routes de décision.

Pour agir sur une prévisualisation, matérialisez la recommandation avec `/workflows/recommendations/materialize`, puis utilisez l'UUID retourné pour accepter, rejeter, reporter ou créer un workflow. Ces mutations demandent `workflows:write` et l'idempotence indiquée dans leur référence.

Le périmètre est `entity`, `fund`, `spv` ou `operation`; fournissez l'identifiant de périmètre lorsque la route l'exige. Les priorités sont `critical`, `recommended` et `optional`. Les preuves, le préremplissage et les indicateurs d'impact varient selon la recommandation.

Accepter une recommandation et créer un workflow sont des actions distinctes. L'endpoint `create-workflow` instancie la définition personnalisée : ne supposez pas qu'un simple `accept` la crée.

## Extraction documentaire IA

`POST /workflows/ai-extraction-jobs` place un document dans la file d'extraction gouvernée. Cette route demande **`ai_extraction:write`**, tandis que la liste et le détail des jobs demandent **`ai_extraction:read`**.

Conservez l'identifiant du job retourné et consultez `GET /workflows/ai-extraction-jobs/{job_id}`. Les états possibles du job système sont `pending`, `running`, `completed`, `failed`, `dead_letter` et `cancelled`. Le détail peut contenir des compteurs de suggestions, un récit, une résolution d'opération, un résultat public ou une erreur.

Un job `completed` signifie que le traitement a terminé; il ne garantit pas que toute suggestion a été appliquée ni que toute donnée extraite est correcte. Les confirmations, droits et règles de validation restent applicables aux résultats.


# Écritures et idempotence
Source: https://developers.marko.fr/writes-and-idempotency

Synchroniser des ressources sans doublons et reprendre une écriture après une réponse incertaine.

## Une clé par intention

Les routes qui le précisent exigent `Idempotency-Key`. La valeur contient au maximum 255 caractères ASCII visibles, sans espaces. Générez une clé unique pour une mutation logique; conservez **la même clé, la même cible et le même contenu** pendant les reprises. Une mutation différente reçoit une nouvelle clé.

```http theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
Idempotency-Key: crm-operation-001-revision-01
X-Request-ID: crm-sync-operation-001
```

`X-Request-ID` sert au diagnostic et ne remplace pas la clé d'idempotence. Un header d'idempotence absent produit `428`, invalide `400`, et une réutilisation incompatible peut produire `409`.

Le header reste obligatoire sur les écritures concernées, même lorsque la déduplication des reprises est désactivée pour une famille ou un environnement. Sa présence ne promet donc pas à elle seule une déduplication universelle ou une rétention illimitée. La politique active de l'entité et de la famille doit être confirmée lors de l'intégration.

## Identifiants externes

Les routes `/external/{external_id}` associent l'identifiant stable de votre système à un identifiant MARKO. Les références sont isolées par entité, intégration cliente, environnement et type de ressource. Conservez l'identifiant externe et l'identifiant MARKO renvoyé; ne reconstruisez pas une association à partir du nom.

Les identifiants des opérations, opérateurs, SPV et notes externes acceptent les lettres ASCII, chiffres et caractères `._:~-`, avec une première position limitée à une lettre, un chiffre ou `_~-`, et une longueur maximale de 255. La référence indique les contraintes de chaque route, notamment celles des documents.

Pour une première association explicite, certaines routes acceptent `existing_marko_id`. La cible doit être compatible et accessible; ce champ n'autorise pas une réaffectation arbitraire. Les upserts opérateur et SPV peuvent restaurer une ressource supprimée logiquement en conservant son UUID.

## Upsert synchrone d'une opération

Cet exemple est synthétique. Il crée ou met à jour une opération sans choisir une valeur de taxonomie propre à votre entité :

```bash theme={null}
curl --fail-with-body -X PUT \
  "$MARKO_API_BASE_URL/operations/external/crm-example-001" \
  -H "Authorization: Bearer $MARKO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-example-001-revision-01" \
  --data '{"name":"Exemple MARKO"}'
```

Une création renvoie `201`; une mise à jour, restauration ou répétition sans changement renvoie `200`. La réponse contient directement `marko_id` et la ressource. Aucune attente de job n'est nécessaire pour cet endpoint. Les notes passent par leur route dédiée; l'import `/operations/batch` est, lui, asynchrone.

## Reprendre une réponse incertaine

Après un timeout ou une coupure réseau, vérifiez la ressource par son identifiant externe ou le job accepté. Si une reprise est nécessaire, renvoyez la même intention avec sa clé conservée. N'envoyez pas immédiatement une nouvelle clé pour la même écriture : le premier appel a pu être validé malgré l'absence de réponse.

Une réponse `409` demande un diagnostic de la clé, du contenu, de l'association externe, de la cible ou de la version source. Elle ne se résout pas en changeant automatiquement la clé. Pour les notes importées, les dates source imposent aussi une règle de [mise à jour versionnée](/imports-and-notes).