docs: add co-medicaid reference note

2026-06-19 19:49:34 -06:00
parent 8c12e3c81a
commit 307a8d3b69
1 changed files with 71 additions and 0 deletions
@@ -0,0 +1,71 @@
+# Colorado Medicaid — payer specifics
+
+Cyclone's CO Medicaid (`PayerConfig.co_medicaid()` and
+`PayerConfig835.co_medicaid_835()`) factories encode the trading-partner
+and code-set rules that the Colorado Department of Health Care Policy &
+Financing (HCPF) requires.
+
+## Trading Partner IDs (TPID)
+
+| Role | 837P | 835 |
+|---|---|---|
+| Sender | `SKCO0` | (varies; usually the clearinghouse) |
+| Receiver | `COHCPF` | (varies) |
+
+These appear in the `NM1*PR` (payer) and `NM1*40` (receiver) segments of
+the 837P file.
+
+## Payer IDs
+
+### 837P (claims)
+
+- `NM1*PR N104 = "SKCO0"` (COHCPF)
+
+### 835 (remittance)
+
+- `BPR10 = "81-1725341"` — TXIX (Medicaid) account
+- `BPR10 = "84-0644739"` — BHA (behavioral health) account
+- `N1*PR N104 = "7912900843"` — payer ID
+- `N1*PR N102` is one of `"CO_TXIX"` or `"CO_BHA"`
+
+## Allowed codes
+
+### 837P `CLM05-3` (frequency code)
+
+| Code | Meaning |
+|---|---|
+| 1 | Original claim |
+| 7 | Replacement claim |
+| 8 | Void / cancel |
+
+Cyclone raises `R030_frequency_allowed` if any other value appears.
+
+### 835 `CLP02` (claim status code)
+
+Allowed: `{1, 2, 3, 4, 19, 20, 21, 22, 23, 25}`. See the 835 reference
+note for the meaning of each.
+
+### Place of service (POS)
+
+All CMS POS codes `01`–`99` are accepted. The canonical list lives in
+`cyclone/parsers/payer.py` as `CMS_PLACE_OF_SERVICE_CODES` and is the
+source of truth for validation and any UI dropdowns.
+
+## Validation rules Cyclone enforces
+
+See [837p.md](./837p.md#validation-rules-cyclone-enforces) and the
+`cyclone.parsers.validator` / `cyclone.parsers.validator_835` modules.
+
+## Adding a new payer
+
+The pattern is:
+
+1. Add a `PayerConfig` (837P) and `PayerConfig835` (835) factory in
+   `cyclone/parsers/payer.py` — usually thin wrappers that override only
+   the differing fields (allowed codes, payer IDs).
+2. Register the factory in the `PAYER_FACTORIES` / `PAYER_FACTORIES_835`
+   dicts in `cyclone/api.py` and `cyclone/cli.py`.
+3. Add a smoke fixture under `backend/tests/fixtures/` (a real or
+   synthetic file matching the new payer's rules) and a parser test that
+   loads it.
+4. Update this note + the 837p/835 notes with the new payer's specifics.