Synchronisation et identifiants externes

Maintenir une copie utile sans doublonner les objets ni perdre les suppressions.

Vérifié le 2026-10-12 · Version Markdown

Une synchronisation incrémentale#

1. Faites une première lecture paginée du périmètre autorisé.
2. Stockez les identifiants Cercla et les dates de modification.
3. Reprenez avec updatedSince sur les routes compatibles, puis parcourez toutes les pages.
4. Appliquez des upserts idempotents chez vous et gardez une fenêtre de recouvrement.
5. Réconciliez régulièrement l'ensemble des identifiants.

Les listes ordinaires excluent les objets à la corbeille sans tombstone. Un delta updatedSince ne suffit donc pas à détecter toutes les disparitions. Utilisez les événements de mise à la corbeille disponibles et une réconciliation périodique. Les webhooks peuvent arriver hors ordre.

Faire correspondre les identifiants#

externalRefs rattache un objet à un identifiant de votre système. Chaque entrée porte une source, un identifiant externe et éventuellement une date source. Les routes de références externes couvrent les sociétés, contacts, devis, factures et contrats.

Le PUT vers /{objet}/{id}/external-refs/{source} pose la référence ; le DELETE la retire. Un identifiant déjà porté par un autre objet de la même source provoque un 409, sans déplacement silencieux. La source réservée salesforce n'est pas writable par ce parcours générique.

Les listes compatibles acceptent externalId et externalSource. Vérifiez chaque opération dans la référence. Une liste vide signifie qu'aucun objet visible ne correspond, pas nécessairement qu'aucun objet n'existe dans l'organisation.

Brancher un référentiel maître#

L'administrateur configure la source, l'URL et le mapping. Cercla peut lire un enregistrement par identifiant et recevoir un delta signé. Les champs tenus par la source se corrigent chez elle. Une valeur vide reçue n'efface pas automatiquement les champs du CRM.

Le webhook entrant /api/v1/webhooks/in/{source} utilise une signature et X-Cercla-Organization, selon ce contrat particulier. Ce header ne remplace pas le contexte de jeton des routes REST ordinaires.

Récupérer une archive d'organisation#

Avec exports:read, lisez /exports, /exports/latest puis /exports/{id}/download. Une archive peut être en attente, en échec, expirée ou purgée. Vérifiez sa disponibilité, sa taille et son SHA-256.

Le fichier contient un manifeste, des tables JSONL et les fichiers de l'organisation selon le format d'export. Le schéma des tables suit les migrations et n'est pas une API métier stable. Utilisez les routes REST pour les intégrations durables.