Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Clearinghouse Integration — Integration

​

Quick Reference

​

Decision Tree

• Need to submit a claim electronically? → Use PM-15 ClearinghouseAdapter.submitClaim() via PM-08 claim workflow. → Credentials resolved from vault refs at runtime; never stored in code.
• Need to process an ERA/835? → Use ClearinghouseAdapter.fetchRemittance() → parse → feed PM-09 payment posting. → 835 SVC segments map to pm_claim_lines.
• Need to check eligibility in real-time? → Use ClearinghouseAdapter.checkEligibility() for 270/271 (PM-02 integration).

​

Common Mistakes

​

Pre-Flight Checklist

• PM-08 and PM-09 schemas exist (claims, claim_lines, payments)
• Vault refs configured for clearinghouse credentials
• RLS enabled with FORCE on all four tables
• UPDATE policies include WITH CHECK
• No secrets in code, migrations, or docs

​

Overview

​

Integration Points

​

API / Adapter Contract

​

Phase 1 methods (adapter interface)

​

Phase 2a additions (transport layer)

​

Phase 2b additions (X12 utilities — shared, pure TypeScript)

​

835 parser → PM-09 interface

1. Creates pm_era_files record: file_name, received_date, payer_id (from GS/TRN), check_eft_number, total_paid, claim_count, status = 'received'
2. Emits clearinghouse_era_received event (payload below) for PM-09 to pick up
3. PM-09 payment posting pipeline consumes the event and creates pm_payments + pm_payment_applications

// clearinghouse_era_received event payload
interface ClearinghouseEraReceivedPayload {
  era_file_id: string;        // pm_era_files.id just created
  organization_id: string;
  batch_id: string;           // pm_transaction_batches.id
  claim_count: number;
  total_paid: number;
}

​

Pattern Library

• Adapter abstraction pattern: PM workflows call ClearinghouseAdapter methods, not vendor SDKs directly.
• Vault reference pattern: runtime credential resolution from pm_clearinghouse_config, never plaintext secrets in code.
• Append-only ledger pattern: pm_transaction_log is immutable and used for traceability.

// Example: PM workflow invocation using tenant-scoped config + adapter
const { data: config } = await supabase
  .from('pm_clearinghouse_config')
  .select('*')
  .eq('organization_id', orgId)
  .single();

const credentials = await resolveVaultCredentials(config); // resolves vault refs at runtime

await clearinghouseAdapter.submitClaim(claimId, payload, { credentials });
await clearinghouseAdapter.fetchRemittance({ organizationId: orgId, credentials });
await clearinghouseAdapter.checkEligibility({ organizationId: orgId, credentials }, eligibilityRequest);

​

Event Contracts

Note: clearinghouse_batch_submitted and clearinghouse_batch_error were defined in Phase 1 (PM-15 Errata F-5). clearinghouse_era_received and clearinghouse_health_changed are new in Phase 2.

​

Phase 2c: Connection Health Monitoring

• On status change → updates pm_clearinghouse_config.health_status and last_health_check_at
• On down or degraded → emits clearinghouse_health_changed immediately; PF-10 alert fired
• On recovery to healthy → requires 2 consecutive healthy checks before emitting recovery event (anti-flap throttle)
• Health badge in UI is gated by pm.clearinghouse.view

​

Security & Tenant Isolation

• All clearinghouse tables are scoped by organization_id; RLS and SECURITY DEFINER helpers enforce isolation.
• Credentials stored in vault only; config holds vault refs; resolution at runtime in edge function or backend.
• PHI in 837/835: encrypt in transit (TLS); audit access to batch and transaction log.

​

References

• PM-15: Clearinghouse Integration — Phase 1 (tables, RLS, adapter interface, UI stubs)
• PM-15-P2: Production Clearinghouse Transport — Phase 2 (transport, X12, health monitoring)
• PM-15: Clearinghouse Vendor Selection & Waystar-First Integration
• PM-09: Payment Posting & ERA Processing — pm_era_files, pm_payments, pm_payment_applications schema
• X12 EDI Technical Design
• REGULATORY_COMPLIANCE_TRACKER.md — PM-15-P2 HIPAA EDI Transport row