> ## 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 une note de suivi externe

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



## OpenAPI

````yaml /openapi.json put /operations/external/{operation_external_id}/notes/external/{note_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 <access_token>`.

    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/external/{operation_external_id}/notes/external/{note_external_id}:
    put:
      tags:
        - operations
      summary: Importer une note de suivi externe
      description: >-
        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).
      operationId: operations_notes_upsert
      parameters:
        - in: path
          name: operation_external_id
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
            pattern: ^[A-Za-z0-9_~-][A-Za-z0-9._:~-]{0,254}$
            title: Operation External Id
          example: CF-OP-001
          description: >-
            Identifiant externe de l'opération, appartenant à la même
            intégration.
        - in: path
          name: note_external_id
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
            pattern: ^[A-Za-z0-9_~-][A-Za-z0-9._:~-]{0,254}$
            title: Note External Id
          example: CF-NOTE-002
          description: >-
            Paramètre note_external_id pour cette route; type, format et
            contraintes ci-dessous.
        - 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-notes-upsert
        - 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/ExternalNoteUpsertRequest'
            example:
              date: '2026-07-16T14:00:00Z'
              text: 'Comité: prorogation à documenter.'
              category: comite
              description_i18n:
                fr: 'Comité : prorogation à documenter.'
                en: 'Committee: extension to document.'
              source_created_at: '2026-07-16T14:00:00Z'
              source_updated_at: '2026-07-16T14:00:00Z'
      responses:
        '200':
          description: Additional successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalNoteSyncUpsertResponse'
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalNoteSyncUpsertResponse'
              example:
                external_id: CF-NOTE-002
                marko_id: 55555555-5555-5555-5555-555555555555
                outcome: created
                resource:
                  id: 55555555-5555-5555-5555-555555555555
                  operation_id: 44444444-4444-4444-4444-444444444444
                  date: '2026-07-16T14:00:00Z'
                  category: custom__a3e08c7bde__comite
                  text: 'Comité: prorogation à documenter.'
                  description_i18n:
                    fr: 'Comité : prorogation à documenter.'
                    en: 'Committee: extension to document.'
                  source_created_at: '2026-07-16T14:00:00Z'
                  source_updated_at: '2026-07-16T14:00:00Z'
                  created_at: '2026-08-22T08:00:00Z'
                  updated_at: '2026-08-22T08:00:00Z'
                taxonomy_additions:
                  - code: custom__a3e08c7bde__comite
                    dimension: follow_up_category
                    display_label: comite
                    source_kind: partner
                    source_display_name: ClubFunding
                    is_visible: true
                    is_active: true
                    position: 10000
                    usage_count: 0
                    label_editable: true
                    canonical_code: null
                request_id: req_cf_note_upsert
        '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:
    ExternalNoteUpsertRequest:
      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.
      additionalProperties: false
      type: object
      required:
        - date
      title: ExternalNoteUpsertRequest
      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.
    ExternalNoteSyncUpsertResponse:
      properties:
        external_id:
          type: string
          title: External Id
          description: >-
            Identifiant stable de votre système, dans le contexte de votre
            intégration.
        marko_id:
          type: string
          format: uuid
          title: Marko Id
          description: >-
            Identifiant MARKO résolu ou créé; conservez-le pour les appels
            ultérieurs.
        outcome:
          type: string
          enum:
            - created
            - updated
            - noop
            - restored
            - bound
          title: Outcome
          description: >-
            Résultat de la synchronisation: created, updated, noop, restored ou
            bound. Conserver marko_id quel que soit ce résultat.
        resource:
          $ref: '#/components/schemas/ExternalNoteResourceResponse'
          description: État de la ressource MARKO après la synchronisation externe.
        taxonomy_additions:
          items:
            $ref: '#/components/schemas/EntityTaxonomyOptionResponse'
          type: array
          title: Taxonomy Additions
          description: >-
            Options de taxonomie créées par cet upsert. Conservez les codes
            retournés; le suffixe custom__ n'est pas prévisible.
        request_id:
          type: string
          title: Request Id
          description: Identifiant de corrélation pour le diagnostic de la requête.
      type: object
      required:
        - external_id
        - marko_id
        - outcome
        - resource
        - request_id
      title: ExternalNoteSyncUpsertResponse
    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.
    ExternalNoteResourceResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Identifiant MARKO de la ressource.
        operation_id:
          type: string
          format: uuid
          title: Operation Id
          description: UUID MARKO de l'opération.
        date:
          type: string
          format: date-time
          title: Date
          description: >-
            Date métier; le type et le format ci-dessous font autorité pour
            cette route.
        text:
          type: string
          title: Text
          description: Texte de la note ou du commentaire.
        category:
          type: string
          title: Category
          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:
          additionalProperties:
            type: string
          type: object
          title: Description I18N
          description: >-
            Textes par locale normalisée (fr, en, fr-fr…); contraintes
            complémentaires dans le guide Imports et notes.
        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.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Date de création au format ISO 8601.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Date de dernière modification au format ISO 8601.
      type: object
      required:
        - id
        - operation_id
        - date
        - text
        - category
        - created_at
        - updated_at
      title: ExternalNoteResourceResponse
    EntityTaxonomyOptionResponse:
      properties:
        parent_code:
          anyOf:
            - type: string
              enum:
                - due_diligence
                - en_cours
                - en_recouvrement
                - termine
            - type: 'null'
          title: Parent Code
          description: Code de l'option parente dans la taxonomie, lorsqu'elle existe.
        code:
          type: string
          title: Code
          description: >-
            Code stable de la ressource ou de l'option. Conserver la valeur
            retournée par MARKO.
        dimension:
          type: string
          enum:
            - operation_status
            - investment_type
            - operation_type
            - asset_class
            - internal_status
            - operational_status
            - follow_up_category
          title: Dimension
          description: Dimension de taxonomie à laquelle cette option appartient.
        display_label:
          type: string
          title: Display Label
          description: >-
            Libellé de l'option à afficher; utiliser code comme identifiant
            stable.
        source_kind:
          type: string
          enum:
            - marko
            - partner
            - entity
          title: Source Kind
          description: >-
            Nature de l'origine de l'option: catalogue MARKO ou source propre à
            l'entité.
        source_display_name:
          type: string
          title: Source Display Name
          description: Nom lisible de l'origine de l'option de taxonomie.
        is_visible:
          type: boolean
          title: Is Visible
          description: Indique si l'option est visible dans le catalogue de l'entité.
        is_active:
          type: boolean
          title: Is Active
          description: Indique si l'élément est actif.
        position:
          type: integer
          title: Position
          description: Position de l'élément dans sa liste.
        usage_count:
          type: integer
          title: Usage Count
          default: 0
          description: Nombre d'utilisations de cette option de taxonomie.
        label_editable:
          type: boolean
          title: Label Editable
          description: Indique si le libellé de l'option peut être modifié dans MARKO.
        canonical_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Canonical Code
          description: Code MARKO canonique associé à cette option, lorsqu'il existe.
        icon_key:
          anyOf:
            - type: string
              enum:
                - tag
                - briefcase
                - building
                - landmark
                - home
                - map
                - layers
                - shield
                - trending-up
                - calendar
                - circle-check
                - triangle-alert
            - type: 'null'
          title: Icon Key
          description: Clé de l'icône associée à l'option de taxonomie.
      type: object
      required:
        - code
        - dimension
        - display_label
        - source_kind
        - source_display_name
        - is_visible
        - is_active
        - position
        - label_editable
      title: EntityTaxonomyOptionResponse
  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.