provider-endpointsProvider Overview

Provider Overview

This page explains how Aivida integrates external lab providers using a single, provider-agnostic architecture.

Why This Exists

  • Keep endpoint contracts stable even when providers change.
  • Add new providers with adapter registration only.
  • Enforce Aivida-first payment control before external booking.
  • Persist all critical linkage in Aivida tables for traceability.

High-Level Architecture

Pay-Then-Book Flow

Report Fetch Flow

Data Ownership and Mapping

ConcernSource of Truth
Payment completionpayments
External booking referencelab_orders.order_id
Internal provider-order lifecycleprovider_orders
Report file metadatalab_result_files
External provider raw responseproviderRaw in endpoint response

Current Provider (v1)

  • Supported providerCode: thyrocare
  • Namespace: labProvider
  • Endpoints:
    • catalog
    • getPincodes
    • priceBreakup
    • searchSlots
    • createOrder
    • getOrder
    • listOrders
    • cancelOrder
    • rescheduleOrder
    • getReport

Operational Notes

  • v1 uses one platform Thyrocare account.
  • Provider operations like cancel/reschedule can be eventually consistent on provider side.
  • Status refresh is pull-based in v1 (getOrder, listOrders), not webhook-driven.
  • Adding a new provider requires implementing LabProviderClient and registering it in LabProviderRegistry.

Testing and Smoke Validation

cd backend
./scripts/thyrocare_smoke.sh
  • Full booking smoke (pay-then-book path):
cd backend
ORG_ID=org_test_thyro \
PAYMENT_ID=<payment_with_status_success> \
PATIENT_ID=<aivida_patient_id> \
./scripts/thyrocare_smoke.sh
OverviewLab Provider