Aller au contenu

Doctolib integration

Status: Placeholder — to be developed. Last reviewed: — Reference structural sibling: guidelines/i18n/translation-rules.md (rule + workflow style — connector-specific operational rules).

Scope (when this guideline lands)

Doctolib API access: auth model, which entities sync (appointments primarily), incremental vs full sync, schedule (currently daily at 3:00 AM via Celery beat), failure modes specific to Doctolib (rate limits, schema drift, multi-account scoping), how appointments reconcile with apps/appointments/.

Out of scope (cross-refs)

  • Shared connector contract (credentials, retry, error surfacing patterns common to all connectors) → guidelines/integrations/overview.md (placeholder).
  • Celery task shape (naming, idempotency) → guidelines/celery/task-conventions.md (placeholder).
  • Appointment domain model → apps/appointments/ reference; not a guideline.
  • Logging and PII in sync output → guidelines/security/pii-and-logging.md (placeholder). Doctolib syncs return patient names — log discipline is critical here.

Sources to mine when writing this

  • apps/sync/ — Doctolib client (services/, clients/?), sync tasks (tasks.py), management commands.
  • Beat schedule — confirm the 3:00 AM daily run and document why (probably to avoid Doctolib rate limits during business hours).
  • sync_output*.log files at repo root — sample of what a sync run looks like (and what failures look like). Verify these don't leak PII (see security/pii-and-logging.md placeholder).
  • apps/sync/models.py — SyncLog and related models that record run state.
  • apps/sync/views.py — manual-sync endpoints with the percent-format messages from commit 8a023fd (post-i18n-fix reference).
  • Past Doctolib incidents in roadmap/done/ or commit history (grep for "doctolib" in git log).

Starter hard rules to investigate

  1. Daily 3 AM beat run for full incremental sync — verify and document the rationale (off-hours rate-limit avoidance).
  2. Incremental by default, full re-sync only on demand via management command.
  3. Per-practice scoping — Doctolib sync is per-practice; the task arg is always a practice_id, never global.
  4. Schema-drift detection: when Doctolib changes a response shape, the sync should fail loudly, not silently skip rows.
  5. Sync output never logs raw patient data (per security/pii-and-logging.md placeholder).

Decision points to settle

  1. Schema drift handling: fail-loud with Sentry alert vs auto-quarantine the bad rows + continue.
  2. Multi-account scoping: a practice with multiple Doctolib accounts — how is that modeled? Currently there's is_doctolib_practice_profile and is_doctolib_dentist_profile flags.
  3. Manual-sync rate limit: a user clicks "Sync now" in the UI — should that bypass the daily beat or queue alongside?
  4. Historical sync window: how far back does an incremental sync look? Days? Last-sync-timestamp?

Known deviations to look for during writing

  • Doctolib API calls in views (not in a Celery task) — latency risk.
  • Sync log entries with raw patient strings.
  • Missing 3 AM run with no "skipped" record.
  • Schema-drift cases handled with try: parse() except: continue — silent quarantine.

If found, file as roadmap/backlog/integrations-doctolib-drift-2026-MM.md.