Une clé par intention
Les routes qui le précisent exigentIdempotency-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é.
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é :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éponse409 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.