ABDM V3 — Integration & Testing Log

Owner: Simmi · Branch: feature/abdm_integration_port · API version: ABDM V3 Started: 2026-07-07

This is the living integration document for Kulcare's ABDM backend (/integration/abdm/*). It holds (a) the API reference for every Kulcare ABDM endpoint, (b) the DB tables each touches, (c) config, and (d) a chronological log of what we've registered/tested and the results.

Companions (static references):

• Architecture/where-code-lives: docs/audits/abdm-parts-to-domains-audit-2026-07-06.md
• Step-by-step test cases: docs/testing/abdm-v3-manual-test-plan.md
• Importable requests: docs/testing/kulcare-abdm.postman_collection.json

1. Test environmentCopy Anchor Link

ABDM secrets (client_id, client_secret, gateway_url, cm_id, abdm.* hosts) stay server-side in Rails credentials. Postman/API testing only needs a CMS bearer token + facility_id.

2. ABDM DB tables reference (schema integration.* unless noted)Copy Anchor Link

Useful scopes (model): AbdmFacilityRegistration.hip_for_facility(facility_id), .hiu_for_facility(...).

3. API reference — Kulcare ABDM endpointsCopy Anchor Link

All under /integration/abdm/*. Authenticated endpoints: Authorization: Bearer <cms jwt> + tenant context; facility_id passed where shown. Webhooks use ABDM JWT (no bearer).

M1 — Facility registration & ABHACopy Anchor Link

M2 — HIP linking ← current focusCopy Anchor Link

Prereq for M2: the facility must have an active HIP registration (hip_for_facility), and the patient must have a verified abdm_patient_profile. ✅ HIP reg now in place for City Hospital Branch.

M3 — Consent & dataCopy Anchor Link

InfraCopy Anchor Link

4. Configuration (Rails credentials) — correct keysCopy Anchor Link

⚠️ The ABDM client code had wrong credential key names (fixed in port). Always use the abdm_-prefixed keys below.

ABDM session endpoint (corrected)Copy Anchor Link

• URL: POST https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions
• Path used by code: /api/hiecm/gateway/v3/sessions (was /v3/gateway/sessions — wrong)
• Body: {"clientId":"...","clientSecret":"...","grantType":"client_credentials"} (was missing grantType)
• Required headers: Content-Type: application/json, X-CM-ID, REQUEST-ID (UUID), TIMESTAMP (must include milliseconds, format: 2026-07-07T00:00:00.000Z; Time.current.iso8601(3) — plain iso8601 without precision gives ABDM-1016 Invalid Timestamp)

ABDM bridge-services endpointCopy Anchor Link

• URL: GET https://dev.abdm.gov.in/api/hiecm/gateway/v3/bridge-services
• Response shape: {"services":[{"id","name","types":["HIP","HIU","PHR"],"active":true}]}
• IN1810000370 → {"id":"IN1810000370","name":"National_program_AS_LAKHIMPUR_Kadam_village","types":["HIP","HIU","PHR"],"active":true}

5. Testing log (chronological)Copy Anchor Link

5a. Bugs found & fixed during M1 setupCopy Anchor Link

Bug 1: Wrong credential keys (ApiClient + GatewayTokenService)Copy Anchor Link

ApiClient and GatewayTokenService referenced credential keys that don't exist: client_id, client_secret, cm_id, gateway_url all returned nil. The correct keys are abdm_gateway_client_id, abdm_gateway_client_secret, abdm_cm_id, abdm_gateway_host_hiecm.

Fixed in:

• domains/integration/services/abdm/api_client.rb — gateway_base_url → :abdm_gateway_host_hiecm, cm_id → :abdm_cm_id
• domains/integration/services/abdm/gateway_token_service.rb — client_id/client_secret → :abdm_gateway_client_id/secret, session path → /api/hiecm/gateway/v3/sessions, added grantType: 'client_credentials' + X-CM-ID/REQUEST-ID/TIMESTAMP headers

Bug 2: TIMESTAMP missing milliseconds (ABDM-1016)Copy Anchor Link

ApiClient used Time.current.iso8601 (no ms) for the TIMESTAMP header. ABDM rejects timestamps without milliseconds.

Fixed: Time.current.iso8601(3) (adds .fff precision).

Bug 3: Schema didn't support same-id HIP+HIUCopy Anchor Link

abdm_facility_registrations had UNIQUE(service_id) — blocked registering the same service_id as both HIP and HIU. abdm_hip_registry had PRIMARY KEY (service_id) — the sync trigger would overwrite (upsert ON CONFLICT service_id, losing the first type).

Fixed: Migration db/migrate/20260706120000_support_multi_type_abdm_registrations.rb:

• abdm_facility_registrations: UNIQUE(service_id, registration_type)
• abdm_hip_registry: PRIMARY KEY (service_id, registration_type)
• sync_hip_registry() trigger: upsert/delete on (service_id, registration_type)
• Added missing abdm_api_logs partitions for Jul–Oct 2026

Bug 4: Model uniqueness not scoped to typeCopy Anchor Link

Model had validates :service_id, uniqueness: true — conflicts with composite unique index.

Fixed: validates :service_id, uniqueness: { scope: :registration_type }

Bug 5: BridgeService only validated HIP (not HIU)Copy Anchor Link

find_hip filtered only for services with types.include?('HIP') — ignored HIU-only or multi-type services.

Fixed: Added find_service(service_id) returning the full service object with all types. find_hip now delegates to find_service and validates the HIP type.

Bug 6: Controller created only one typeCopy Anchor Link

Original create required registration_type from body and only created one row.

Fixed: create calls find_service, intersects ABDM's types[] with REGISTRATION_TYPES (HIP/HIU), and creates one row per applicable type in a single call.

2026-07-07 — HIP+HIU registration (M1.1) via pure API ✅Copy Anchor Link

• Action: POST /integration/abdm/facility_registrations — City Hospital Branch (01900002-...002) + IN1810000370
• Auth: Lisa Anderson (lisa.admin@cityhospital.com) — use the token field from login response (has tenant_id + facility_id embedded; NOT the access_token field which has no tenant)
• Result: HTTP 201, 2 rows created:
  • HIP: id=019f3fcb-4e17-71a7-bf8c-acb2ee2d7998
  • HIU: id=019f3fcb-4e36-7e7f-a2ff-29d39d014eb8
• ABDM bridge-services response for IN1810000370: types:["HIP","HIU","PHR"] → registered HIP+HIU, skipped PHR
• abdm_hip_registry: 2 rows synced via trigger (HIP + HIU) ✅
• Scope verified: hip_for_facility and hiu_for_facility both resolve for City Hospital Branch ✅

Curl used:

curl -X POST http://localhost:6000/integration/abdm/facility_registrations \
  -H "Authorization: Bearer <Lisa's token (the 'token' field, not 'access_token')" \
  -H "Content-Type: application/json" \
  -d '{"facility_registration":{"facility_id":"01900002-0000-7000-8000-000000000002","service_id":"IN1810000370","service_name":"City Hospital Branch"}}'

Next: M2 HIP linkage — need a Kulcare patient at City Hospital Branch with an ABHA number to link.

• Action: Registered City Hospital Branch (01900002-0000-7000-8000-000000000002, tenant 01900000-...001) as HIP with service_id = IN1810000370.
• Method: Direct DB insert into integration.abdm_facility_registrations (table was empty; bypassed API since IN1810000370 is a production-format id not present in sandbox bridge-services).
• Result: Row created id = 019f38d8-4d9a-717b-80ef-45a33b43272b, registration_type=HIP, active=true, service_name='City Hospital Branch'.
• Trigger verified: integration.abdm_hip_registry auto-synced (IN1810000370, HIP, active).
• Scope verified: hip_for_facility(City Hospital Branch) resolves → current_hip_registration will work for M2.
• Next: M2 HIP linking — need a patient with a verified ABHA profile at this facility, then run fetch_modes → auth_init → auth_confirm → add_contexts.