> ## Documentation Index
> Fetch the complete documentation index at: https://developers.marko.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Documents et upload

> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.