DOC
Accueil/ Projets/ KOBIKE Tracking Notifier/ ADR 0001 : Écoute en direct des mises à jour de Tencent Docs dans n8n

ADR 0001 : Écoute en direct des mises à jour de Tencent Docs dans n8n

  • Statut : Accepté (révisé le 2026-07-13 - pivot vers polling OpenAPI, voir « Révision » ci-dessous)
  • Date : 2026-07-13
  • Auteur : Antigravity

⚠️ Révision (2026-07-13) - HiFlow abandonné, Voie A (OpenAPI polling) retenue

La décision initiale (HiFlow événementiel, ci-dessous) est abandonnée pour deux raisons constatées à l'usage :

  1. HiFlow bloqué : erreurs « get appid error » et liste de connecteurs vide sur ipaas.cloud.tencent.com (probablement VPN + traduction navigateur, mais expérience jugée trop fragile/complexe par l'utilisateur).
  2. Le document est un tableur classique docs.qq.com/**sheet**/… (en ligne 表格, colonnes A/B/C, onglets par période), PAS un Smart Sheet (智能表格). → l'API WeCom Smart Sheet de l'Option 2 (guide 02) est techniquement inutilisable (elle ne lit que les Smart Sheets).

Nouvelle décision : Voie A = polling via l'API Tencent Docs OpenAPI officielle.

  • n8n (node Schedule) rafraîchit un access_token (OAuth, refresh_token valable 1 an) puis lit les plages de cellules du tableur : GET /openapi/spreadsheet/v3/files/{fileId}/{sheetId}/{range}.
  • Comparaison delta vs PostgreSQL ; l'anti-doublon UNIQUE (numero_commande, tracking_number) (ADR 0004) garantit l'idempotence malgré le polling.
  • Contrepartie assumée : nécessite de créer une application développeur Tencent Docs approuvée (docs.qq.com/open/developers/, authentification entreprise probable) - plus lourd que HiFlow à l'onboarding, mais indépendant de HiFlow, du VPN et des contacts chinois.

Guide d'implémentation : docs/guide/07-tencent-docs-openapi-polling.md. Guides 02 (WeCom) et 03 (HiFlow) conservés pour historique mais caducs.

Mise à jour (2026-07-13, suite) - chemin ACTIF = import par upload

HiFlow définitivement écarté (GetAppIdError, compte Tencent non provisionné pour 轻联). La Voie A OpenAPI reste valable mais différée (nécessite une app développeur approuvée : délai). Constaté aussi : le document est Enterprise / lecture seule → le lien de partage n'est pas téléchargeable par n8n sans session authentifiée (pas d'auto-download).

Chemin ACTIF retenu pour livrer tout de suite = import manuel par upload (guide 08) :

  • l'utilisateur exporte le tableur (导出为 → Excel) et le dépose sur une page de formulaire n8n ;
  • n8n lit le fichier, applique le pipeline commun (upsert → email → anti-doublon).
  • Zéro dépendance Tencent API / OAuth / HiFlow. Semi-manuel assumé ; la Voie A (guide 07) reste le plan d'automatisation ultérieur (même pipeline aval).

La section ci-dessous documente l'analyse initiale (conservée pour traçabilité).

Contexte

Le fichier de suivi logistique est un document Tencent Docs (腾讯文档), accessible à l'URL https://docs.qq.com/sheet/DQ1lxSE5hQ1V3WlJh, mis à jour par des collaborateurs en Chine. L'accès en lecture doit nous être accordé prochainement. Nous cherchons un moyen automatisé et direct pour déclencher n8n dès qu'un numéro de tracking est ajouté dans le document.

Deux contraintes fortes orientent la décision :

  1. Pas de Google Drive / Google Sheets. L'export manuel .xlsx vers Google Drive (approche initiale du rapport_0001) est abandonné : il ajoute une étape manuelle, un retard, et une dépendance à un outil que nous ne voulons pas utiliser ici.
  2. Pas de polling / cron pour le moment. Le délai de réponse depuis la Chine est parfois long et irrégulier ; interroger l'API à intervalle fixe reviendrait souvent à « appeler pour rien ». Nous privilégions donc une approche événementielle (le document nous notifie quand il change) plutôt qu'un balayage périodique.

Nous disposons d'un compte développeur WeCom (Enterprise WeChat) et allons explorer la piste du déclenchement cloud (Tencent HiFlow / 腾讯轻联).

Options étudiées

Option 1 : Déclenchement par connecteur tiers (Tencent Cloud HiFlow)

HiFlow est la plateforme d'intégration officielle de Tencent (équivalent de Zapier/Make). Elle propose des intégrations natives avec Tencent Docs et WeCom.

  • Avantages :
    • Détecte les modifications du fichier en quasi-temps réel.
    • Pas de code complexe à écrire pour la détection des changements.
    • Facile à lier à un webhook n8n (HiFlow appelle n8n en cas de modification).
  • Inconvénients :
    • Dépendance envers un service cloud tiers (HiFlow).
    • Limitations liées au plan tarifaire de HiFlow en cas de volume extrême.

Option 2 : Appel direct à l'API WeCom Smart Sheet par轮询 (Polling) dans n8n

Configuration d'un nœud Cron dans n8n qui appelle périodiquement l'API Smart Sheet de WeCom pour extraire les enregistrements.

  • Avantages :
    • Contrôle total de la logique dans n8n et notre base PostgreSQL.
    • Aucune dépendance envers un tiers (HiFlow).
    • Sécurité et confidentialité des données renforcées (les requêtes restent internes entre WeCom, n8n et PostgreSQL).
  • Inconvénients :
    • La détection n'est pas immédiate (latence de quelques minutes selon la fréquence du Cron).
    • Consommation d'appels API régulière même si aucune modification n'a eu lieu.

Option 3 : Webhooks natifs de la plateforme développeur Tencent Docs

Utilisation directe des webhooks de l'API Tencent Docs Open Platform (hors WeCom).

  • Avantages :
    • Temps réel strict.
    • Solution native au niveau du document.
  • Inconvénients :
    • Nécessite la configuration d'un compte développeur entreprise sur Tencent Docs Open Platform (distinct de WeCom).
    • Processus de validation et de sécurité plus lourd (signature de requêtes, certificats).

Décision

L'Option 1 (déclenchement cloud événementiel via Tencent HiFlow) est retenue comme solution principale, en cohérence avec les deux contraintes du contexte (pas de Google, pas de cron).

Concrètement :

  • HiFlow surveille le document Tencent Docs via son déclencheur natif « une ligne est ajoutée ou modifiée dans une feuille ».
  • En action, HiFlow envoie une requête HTTP POST (webhook) vers un nœud Webhook de n8n, en transmettant les données de la ligne modifiée.
  • n8n ne travaille donc que lorsqu'il y a un changement réel : aucune requête n'est émise « pour rien », ce qui neutralise le problème de latence chinoise irrégulière.

L'Option 2 (Polling WeCom Smart Sheet) est reléguée en solution de secours (fallback) uniquement, à n'activer que si HiFlow s'avère inutilisable (ex. document non éligible au connecteur, quota dépassé). Elle n'est pas implémentée pour l'instant.

L'Option 3 (webhooks natifs Tencent Docs Open Platform) reste une évolution possible si l'on veut se passer de HiFlow, au prix d'un onboarding développeur plus lourd.

Voir le guide d'implémentation : docs/guide/03-hiflow-declenchement-cloud.md.

Conséquences

  • Positives :
    • Traitement strictement événementiel : n8n ne s'exécute que sur changement réel, pas d'appels inutiles vers/depuis la Chine.
    • Pas de script de comparaison (delta) à maintenir dans n8n pour le chemin principal.
    • Latence faible (quasi temps réel) sans surcoût d'infrastructure côté VPS.
  • Négatives :
    • Dépendance à un service tiers Tencent (HiFlow) pour le déclenchement - atténuée par le fallback polling documenté.
    • Le webhook HiFlow doit être exposé publiquement (URL n8n accessible depuis Internet) et sécurisé (jeton secret dans l'URL ou en-tête, validation côté n8n).
    • Nécessite un compte Tencent / HiFlow correctement configuré (voir guides).