Location Clearing House Connections

1. What does this feature do? (High-Level Overview)

This feature lets authorized users configure clearing house accounts per location, so each location can send claim batches with the correct billing credentials. Today, the supported provider is ClaimMD.

2. Who is this for? (Roles & Permissions)

• Users with manage_clearing_houses and access to the location (for example, Manager/Owner): Can add, edit, activate/deactivate, and delete clearing house connections for that location.
• Billing users sending batches (typically roles that include manage_claims): Use these configured connections from Claims; if multiple active connections exist, they must pick one.

3. Business Rules & Enforcements

• Rule 1: All clearing house endpoints are protected by manage_clearing_houses and location authorization checks.
• Rule 2: On create, provider, label, and api_key are required; provider is currently restricted to claimmd.
• Rule 3: On update, api_key is optional; leaving it empty in the UI keeps the current key.
• Rule 4: API keys are stored encrypted and are never returned in full; the UI/API only exposes a masked value.
• Rule 5: Connections can be active or inactive. Claim sending only considers active connections for the batch location.
• Rule 6: If no active connection exists for the location, sending is blocked. If multiple active connections exist, the sender must select one.
• Rule 7: Deleting a location removes its clearing house connections automatically.

4. UI Placement

1. Sidebar > Loc. Settings (location context mode): Open the location edit form.
2. Location Edit (/location/list/edit/:id) > Clearing House Connections: Main area to manage provider, API key, label, status, and actions.
3. Claims > Batches (/claims) > Send action: Uses the active location connections and prompts for selection when more than one is active.

5. How-To Guide (Step-by-Step)

Scenario A: Add a ClaimMD connection for a location

1. Open Loc. Settings and enter the target location edit page.
2. Go to Clearing House Connections.
3. Select ClaimMD as provider.
4. Enter the API key and a clear label (for example, ClaimMD Main Account).
5. Leave Status as Active if it should be usable immediately.
6. Click Add Connection and confirm the success message.

Scenario B: Manage existing connections and control sending behavior

1. In Clearing House Connections, review existing rows (provider, label, masked key, status).
2. Click Edit to update label, status, or API key.
3. Use Activate/Deactivate to control whether the connection can be used for claim sending.
4. Use Delete only when the connection should no longer exist for the location.
5. In Claims > Batches, click Send on a pending batch.
6. If one active connection exists, send continues with that connection.
7. If several active connections exist, choose one in the selection dialog before sending.

6. What happens if…? (Edge Cases / FAQ)

• Q: What happens if a location has no active clearing house connection?
  A: Sending a claim batch is blocked until at least one connection is active.
• Q: What happens if there are multiple active connections for the same location?
  A: The sender must choose which connection to use at send time.
• Q: Can this feature be used in Admin View mode?
  A: The clearing house section is shown only in location edit context (not Admin View mode), even when the user has the permission.