> ## 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. # Importer un lot d'operations externes > 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). ## OpenAPI ````yaml /openapi.json post /operations/batch 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: /operations/batch: post: tags: - operations summary: Importer un lot d'operations externes description: >- 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). operationId: operations_batch parameters: - in: header name: X-Request-ID required: false description: >- Partner-generated correlation identifier echoed in logs and error payloads. schema: type: string example: marko-operations-batch - 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/ExternalOperationBatchRequest' example: operations: - external_id: CF-OP-001 name: Clubfunding Demo Deal status: instruction data: adresse: 12 rue de la Paix, Paris kpi_snapshot: date_reference: '2026-07-15' crd_total: 2500000 notes: - external_id: CF-NOTE-001 date: '2026-07-15T09:30:00Z' text: Pièces complémentaires attendues. category: call responses: '202': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ExternalImportAcceptedResponse' example: job_id: 88888888-8888-8888-8888-888888888888 status: accepted status_url: /v1/import-jobs/88888888-8888-8888-8888-888888888888 results_url: /v1/import-jobs/88888888-8888-8888-8888-888888888888/items received_counts: operations: 1 notes: 1 idempotency_key: client-nightly-2026-07-15-001 replayed: false '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 '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: ExternalOperationBatchRequest: properties: operations: items: $ref: '#/components/schemas/ExternalOperationBatchItem' type: array maxItems: 500 minItems: 1 title: Operations description: >- Opérations à importer; entre 1 et 500 par lot, enveloppe normalisée limitée à 20 Mio. additionalProperties: false type: object required: - operations title: ExternalOperationBatchRequest ExternalImportAcceptedResponse: properties: job_id: type: string format: uuid title: Job Id description: UUID du job durable à suivre. status: type: string title: Status description: >- État du job d'import: accepted, queued, running, partial, completed, failed ou cancelled. Lire les compteurs et les résultats individuels avant de considérer l'ensemble du lot comme réussi. status_url: type: string title: Status Url description: >- Chemin permettant de lire l'état du job; peut être relatif à l'hôte de l'API. results_url: type: string title: Results Url description: >- Chemin permettant de lire les résultats individuels du job; peut être relatif à l'hôte de l'API. received_counts: additionalProperties: type: integer type: object title: Received Counts description: >- Objet JSON extensible. Les types des valeurs sont indiqués par additionalProperties lorsque la route les contraint. idempotency_key: type: string title: Idempotency Key description: >- Clé utilisée pour cette intention; la conserver avec le job ou la ressource. replayed: type: boolean title: Replayed default: false description: >- Indique qu'une réponse liée à la même intention a été retrouvée et rejouée. type: object required: - job_id - status - status_url - results_url - received_counts - idempotency_key title: ExternalImportAcceptedResponse 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. ExternalOperationBatchItem: properties: spv_id: anyOf: - type: string format: uuid - type: 'null' title: Spv Id description: UUID MARKO de la SPV. lead_operateur_id: anyOf: - type: string format: uuid - type: 'null' title: Lead Operateur Id description: UUID MARKO de l'opérateur principal de l'opération. existing_marko_id: anyOf: - type: string format: uuid - type: 'null' title: Existing Marko Id description: >- UUID d'une ressource MARKO existante à associer lors du premier upsert externe; la cible doit être accessible et compatible. name: type: string maxLength: 255 minLength: 1 title: Name description: >- Nom de la ressource. Les recherches exactes et partielles sont décrites au niveau de la route. status: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Status description: >- Statut métier de l'opération. Pour une écriture externe, consulter la dimension operation_status de GET /taxonomies. type_investissement: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Type Investissement description: >- Code de type d'investissement; consulter la dimension investment_type de GET /taxonomies. type_operation: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Type Operation description: >- Code de type d'opération; consulter la dimension operation_type de GET /taxonomies. classe_actif: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Classe Actif description: >- Classe d'actif de l'opération. Pour une écriture externe, consulter la dimension asset_class de GET /taxonomies. statut_interne: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Statut Interne description: >- Code de statut interne de l'opération; consulter la dimension internal_status de GET /taxonomies. statut_operationnel: anyOf: - items: type: string maxLength: 255 minLength: 1 type: array maxItems: 100 - type: 'null' title: Statut Operationnel description: >- Codes de statuts opérationnels de l'opération; consulter la dimension operational_status de GET /taxonomies. sous_classe_actif: anyOf: - type: string - type: 'null' title: Sous Classe Actif description: Sous-classe d'actif de l'opération. data: additionalProperties: true type: object title: Data description: >- Données métier de l'opération. Consultez GET /field-definitions pour les clés, types et unités disponibles; ne déduisez pas les unités des noms. kpi_snapshot: anyOf: - $ref: '#/components/schemas/ExternalKpiSnapshotInput' - type: 'null' description: >- Indicateurs financiers à la date de référence; utiliser les unités définies dans le guide Pagination et données. external_id: type: string maxLength: 255 minLength: 1 pattern: ^[A-Za-z0-9_~-][A-Za-z0-9._:~-]{0,254}$ title: External Id description: >- Identifiant stable de votre système, dans le contexte de votre intégration. notes: items: $ref: '#/components/schemas/ExternalNoteImport' type: array maxItems: 10000 title: Notes description: >- Notes historiques de l'opération. Le lot complet accepte au maximum 10 000 notes. additionalProperties: false type: object required: - name - external_id title: ExternalOperationBatchItem ExternalKpiSnapshotInput: properties: date_reference: anyOf: - type: string format: date - type: 'null' title: Date Reference description: Date à laquelle les valeurs du snapshot KPI se rapportent. crd_total: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Crd Total description: Capital restant dû total à la date de référence. crd_total_source: anyOf: - type: string maxLength: 32 - type: 'null' title: Crd Total Source description: 'Origine du capital restant dû: financing_tranches ou operation_data.' crd_senior: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Crd Senior description: Capital restant dû sur les tranches senior. crd_mezzanine: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Crd Mezzanine description: Capital restant dû sur les tranches mezzanine. valeur_venale: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Valeur Venale description: Valeur de marché de l'actif utilisée pour calculer la LTV. noi: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Noi description: >- Net Operating Income: revenu opérationnel net utilisé pour les ratios financiers. service_dette: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Service Dette description: >- Service de la dette utilisé pour le calcul du DSCR; aligner sa période avec celle du NOI. ltv: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Ltv description: >- Loan-to-Value en fraction: 0.65 signifie 65 %. La valeur persistée est comprise entre 0 et 2. dscr: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Dscr description: >- Ratio de couverture du service de la dette, exprimé comme un multiple: 1.25 signifie une couverture de 1,25 fois. icr: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Icr description: Ratio de couverture des intérêts, exprimé comme un multiple. ltc: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Ltc description: >- Loan-to-Cost en fraction: 0.65 signifie 65 %. La valeur persistée est comprise entre 0 et 2. debt_yield: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Debt Yield description: 'Rendement de la dette, exprimé en fraction: 0.08 signifie 8 %.' risk_score_simple: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Risk Score Simple description: Score de risque de l'opération, en points de 0 à 100. pct_perte_estimee: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Pct Perte Estimee description: 'Perte estimée en fraction comprise entre 0 et 1: 0.03 signifie 3 %.' type: object title: ExternalKpiSnapshotInput ExternalNoteImport: properties: date: anyOf: - type: string format: date-time - type: string format: date description: >- Date métier avec fuseau horaire, ou date YYYY-MM-DD normalisée à minuit UTC. text: anyOf: - type: string maxLength: 10000 minLength: 1 - type: 'null' title: Text description: Texte de la note ou du commentaire. category: type: string maxLength: 80 minLength: 1 title: Category default: libre description: >- Catégorie de la note; les règles exactes dépendent de la route. Pour l'import externe: chaîne de 1 à 80 caractères, libre par défaut. description_i18n: anyOf: - type: object maxProperties: 20 additionalProperties: type: string maxLength: 10000 minLength: 1 description: >- Objet JSON extensible. Les types des valeurs sont indiqués par additionalProperties lorsque la route les contraint. - type: 'null' description: >- Au plus 20 locales et 100 000 caractères au total. Locales normalisées en minuscules avec tirets, max 35 caractères; aucune collision après normalisation. Les textes vides sont refusés. source_created_at: anyOf: - type: string format: date-time - type: 'null' title: Source Created At description: Date de création dans le système source, avec fuseau horaire. source_updated_at: anyOf: - type: string format: date-time - type: 'null' title: Source Updated At description: >- Date de dernière mise à jour dans le système source, avec fuseau horaire. Pour une note déjà versionnée, un changement exige une date strictement plus récente. existing_marko_id: anyOf: - type: string format: uuid - type: 'null' title: Existing Marko Id description: >- UUID d'une ressource MARKO existante à associer lors du premier upsert externe; la cible doit être accessible et compatible. external_id: type: string maxLength: 255 minLength: 1 pattern: ^[A-Za-z0-9_~-][A-Za-z0-9._:~-]{0,254}$ title: External Id description: >- Identifiant stable de votre système, dans le contexte de votre intégration. additionalProperties: false type: object required: - date - external_id title: ExternalNoteImport description: >- Note historique. text ou description_i18n non vide est requis. Dates source avec fuseau horaire; source_updated_at ne peut pas précéder source_created_at. Voir Imports et notes pour les règles de traduction et de version. anyOf: - required: - text properties: text: type: string minLength: 1 description: Texte de la note ou du commentaire. - required: - description_i18n properties: description_i18n: type: object minProperties: 1 description: >- Textes par locale normalisée (fr, en, fr-fr…); contraintes complémentaires dans le guide Imports et notes. 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.