> ## 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. # Creer le metadata d'un document > 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). ## OpenAPI ````yaml /openapi.json put /documents/external/{external_id} openapi: 3.1.0 info: title: MARKO External Partner API version: v1 description: >- Stable external API contract for the live environment. Authentication flow for partner integrations: 1. Generate an API key from the MARKO entity admin API section. 2. Keep the raw API secret server-side and use it only to sign `POST /v1/auth/token`. 3. Build the canonical message `MARKO-EXTERNAL-API-TOKEN-V1\n{key_id}\n{timestamp}\n{nonce}`. 4. Sign that message with HMAC-SHA256 and send the hex signature with `key_id`, `timestamp` and `nonce`. 5. Use the returned short-lived bearer on business endpoints as `Authorization: Bearer `. The raw API secret must never be sent on business endpoints. This public contract intentionally excludes beta endpoints. Référence enrichie pour les développeurs et les assistants IA. Exemples synthétiques; les champs sont extraits des modèles et sérialiseurs de la version indiquée dans x-documentation-provenance. servers: - url: https://partner-api.marko.fr/v1 security: - BearerAuth: [] tags: - name: auth x-group: Authentification - name: entity x-group: Entité - name: portfolio x-group: Portefeuille - name: deals x-group: Deals - name: fonds x-group: Fonds - name: spvs x-group: SPV - name: operations x-group: Opérations - name: taxonomies x-group: Taxonomies - name: import-jobs x-group: Imports par lot - name: comments x-group: Commentaires - name: documents x-group: Documents - name: users x-group: Utilisateurs - name: settings x-group: Paramètres - name: rcci x-group: Conformité RCCI - name: field-definitions x-group: Champs métier - name: search x-group: Recherche - name: operateurs x-group: Opérateurs - name: alerts x-group: Alertes - name: notifications x-group: Notifications - name: calendar x-group: Calendrier - name: enrichment x-group: Enrichissement SIREN - name: reports x-group: Exports - name: reporting x-group: Templates de reporting - name: workflows x-group: Workflows et extraction IA - name: tasks x-group: Tâches externalDocs: description: Download the matching Postman collection. url: /v1/postman.json paths: /documents/external/{external_id}: put: tags: - documents summary: Creer le metadata d'un document description: >- 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). operationId: documents_create parameters: - in: path name: external_id required: true schema: type: string minLength: 1 maxLength: 255 pattern: ^[A-Za-z0-9_~-][A-Za-z0-9._:~-]{0,254}$ title: External Id example: CF-DOC-001 description: >- Identifiant stable de votre système, dans le contexte de votre intégration. - in: header name: X-Request-ID required: false description: >- Partner-generated correlation identifier echoed in logs and error payloads. schema: type: string example: marko-documents-create - in: header name: Idempotency-Key required: true description: >- Required for every write, including environments where replay deduplication is disabled. Reuse the same value when retrying the same logical write and use a new value for a different write. schema: type: string maxLength: 255 pattern: ^[!-~]+$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExternalDocumentCreateRequest' example: operation_external_id: CF-OP-001 type: term_sheet filename: term-sheet.pdf partner_metadata: langue: fr responses: '200': description: Référence documentaire existante ou réponse rejouée. content: application/json: schema: $ref: '#/components/schemas/ExternalDocumentResponse' example: external_id: CF-DOC-001 document_id: 55555555-5555-5555-5555-555555555555 created: true document: id: 55555555-5555-5555-5555-555555555555 operation_id: 44444444-4444-4444-4444-444444444444 spv_id: 33333333-3333-3333-3333-333333333333 fond_id: null type: term_sheet filename: term-sheet.pdf state: active version: 1 storage_path: null partner_metadata: langue: fr created_at: '2026-03-26T09:10:00Z' '201': description: Document créé; conserve son identifiant externe et son document_id. content: application/json: schema: $ref: '#/components/schemas/ExternalDocumentResponse' example: external_id: CF-DOC-001 document_id: 55555555-5555-5555-5555-555555555555 created: true document: id: 55555555-5555-5555-5555-555555555555 operation_id: 44444444-4444-4444-4444-444444444444 spv_id: 33333333-3333-3333-3333-333333333333 fond_id: null type: term_sheet filename: term-sheet.pdf state: active version: 1 storage_path: null partner_metadata: langue: fr created_at: '2026-03-26T09:10:00Z' '400': description: Invalid Idempotency-Key header content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Bad Request status: 400 detail: >- Idempotency-Key must contain at most 255 visible ASCII characters without spaces. request_id: req_example_partner_call '401': description: Authentication required content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Unauthorized status: 401 detail: A valid bearer token is required. request_id: req_example_partner_call '403': description: Scope, route or IP restriction content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Forbidden status: 403 detail: The API key does not allow this operation. request_id: req_example_partner_call '404': description: >- Not Found — refus déclaré dans le handler ou un helper de cette route. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '409': description: Idempotency or write target conflict content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Conflict status: 409 detail: >- The idempotency key payload, external reference, target, or source conflicts with an existing write. request_id: req_example_partner_call '422': description: Validation failed content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Unprocessable Content status: 422 detail: The request payload or parameters are invalid. request_id: req_example_partner_call '428': description: Required Idempotency-Key header is missing content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Precondition Required status: 428 detail: The Idempotency-Key header is required. request_id: req_example_partner_call '429': description: Rate limit or progressive ban headers: Retry-After: description: Cooldown in seconds before retrying the request. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Too Many Requests status: 429 detail: The request rate limit was exceeded. request_id: req_example_partner_call '500': description: Unexpected server error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Internal Server Error status: 500 detail: An unexpected server error occurred. request_id: req_example_partner_call deprecated: false security: - BearerAuth: [] components: schemas: ExternalDocumentCreateRequest: properties: operation_external_id: anyOf: - type: string - type: 'null' title: Operation External Id description: >- Identifiant externe de l'opération, appartenant à la même intégration. operation_id: anyOf: - type: string format: uuid - type: 'null' title: Operation Id description: UUID MARKO de l'opération. type: type: string maxLength: 100 minLength: 1 title: Type description: >- Catégorie métier du document, distincte de son type MIME; par exemple autre pour un document non spécialisé. filename: anyOf: - type: string maxLength: 255 - type: 'null' title: Filename description: Nom du fichier. partner_metadata: additionalProperties: true type: object title: Partner Metadata description: >- Objet JSON extensible. Les types des valeurs sont indiqués par additionalProperties lorsque la route les contraint. type: object required: - type title: ExternalDocumentCreateRequest anyOf: - required: - operation_id properties: operation_id: type: string format: uuid description: UUID MARKO de l'opération. - required: - operation_external_id properties: operation_external_id: type: string minLength: 1 description: >- Identifiant externe de l'opération, appartenant à la même intégration. description: >- Une opération est requise: fournir operation_id ou operation_external_id. Lorsque les deux sont fournis, operation_id est utilisé. Pour un upload de fichier, appeler directement /upload avec un nouvel external_id; une déclaration metadata préalable peut être renvoyée sans ajout de fichier. ExternalDocumentResponse: properties: external_id: type: string title: External Id description: >- Identifiant stable de votre système, dans le contexte de votre intégration. document_id: type: string format: uuid title: Document Id description: UUID MARKO du document. created: type: boolean title: Created description: >- Indique si une nouvelle fiche documentaire a été créée par cet appel. document: $ref: '#/components/schemas/PublicDocumentItem' description: Fiche du document associée à l'identifiant externe. type: object required: - external_id - document_id - created - document title: ExternalDocumentResponse ProblemDetails: type: object required: - title - status - detail properties: type: type: string default: about:blank description: >- URI identifiant le type de problème; about:blank lorsque seul le statut HTTP le caractérise. title: type: string description: Titre affiché pour l'événement ou le problème. status: type: integer description: Statut HTTP de la réponse d'erreur. detail: type: string description: Informations détaillées sur le problème ou le dossier. request_id: type: string description: Identifiant de corrélation pour le diagnostic de la requête. scope: type: string description: Scope concerné par le refus d'accès, lorsqu'il est renseigné. route_id: type: string description: Identifiant de la route concernée par le problème. reason_code: type: string description: >- Code structuré du motif de refus; préférable au texte du message pour le diagnostic. PublicDocumentItem: properties: id: type: string format: uuid title: Id description: Identifiant MARKO de la ressource. operation_id: anyOf: - type: string format: uuid - type: 'null' title: Operation Id description: UUID MARKO de l'opération. spv_id: anyOf: - type: string format: uuid - type: 'null' title: Spv Id description: UUID MARKO de la SPV. fond_id: anyOf: - type: string format: uuid - type: 'null' title: Fond Id description: UUID MARKO du fonds. type: type: string title: Type description: >- Catégorie métier du document, distincte de son type MIME; par exemple autre pour un document non spécialisé. filename: anyOf: - type: string - type: 'null' title: Filename description: Nom du fichier. state: type: string title: State description: État de traitement ou de validation du document. version: type: integer title: Version description: Version de la ressource MARKO. storage_path: anyOf: - type: string - type: 'null' title: Storage Path description: >- Référence du fichier dans le stockage; utiliser download_url pour le télécharger. download_url: anyOf: - type: string - type: 'null' title: Download Url description: >- URL de téléchargement disponible pour ce document. Elle peut être absente; ne pas la traiter comme un identifiant permanent. partner_metadata: anyOf: - additionalProperties: true type: object description: >- Objet JSON extensible. Les types des valeurs sont indiqués par additionalProperties lorsque la route les contraint. - type: 'null' title: Partner Metadata description: Métadonnées fournies par l'intégration partenaire pour ce document. created_at: type: string format: date-time title: Created At description: Date de création au format ISO 8601. type: object required: - id - type - state - version - created_at title: PublicDocumentItem securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: MARKO short-lived bearer description: >- Use the `access_token` returned by `POST /v1/auth/token`. Do not send the raw API secret on business endpoints. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.