--- name: nhcx-full description: >- Build India's NHCX (National Health Claims Exchange) provider-side claims integration into an existing HMIS codebase, end to end: beneficiary policy search, coverage eligibility, the payer's insurance plan, pre-authorisation, payer queries, claim, reprocess and release, and payment notices, with the NHCX gateway (JWE, x-hcx headers, ABDM session tokens, registry, callbacks) embedded in the application. Use when adding NHCX or PMJAY cashless claims to a hospital system as a whole, or when unsure which part of NHCX is needed. --- Copied from github.com/nha-in/nhcx-skills on 21 September 2026, over commit `7f59d09`. The NHCX documentation is the place to look when this folder does not carry enough. This folder is a snapshot. Re-download the whole folder from the portal's /skills/nhcx-full/ path when it is older than the work you are doing: this router and every file under `apis/`, `callbacks/`, `database/`, `fhir/`, `gateway/`, `references/`, `screens/` and `steps/`. Fetching this file alone leaves its pointers aimed at files you do not have. If the nhcx-docs MCP server is connected, trust its answers over this folder. It serves the Catalogue live, which holds 536 NHCX atoms, and this folder cites none of them. What the claims here rest on. The protocol comes from the knowledge source the skill records at its first step: the nhcx-docs MCP server, or a release of the NHCX package checked against its `MANIFEST`. What was seen only on the NHCX sandbox is marked [SANDBOX], and what depends on the payer is marked [PAYER]. None of it is re-verified in this repository: `catalogue/verification/` holds 65 sandbox records and not one of them is NHCX. # READ FIRST: CORE Before anything else, read [references/CORE.md](references/CORE.md) and keep it in mind for the whole task. Its **Instructions** are binding: follow them strictly in every step and every file, and re-read them at the start of each step (L1 to L8). Its **Confusions** settle what easily mixed-up terms mean; when a word is ambiguous, CORE.md decides. It also holds the base URLs and, for every exchange, the route, bundle, workflow id and callback. # GOAL Add NHCX provider-side claims to the target HMIS, from policy search to payment, with the NHCX gateway running inside the application. This skill holds only the specs this goal needs; the SCOPE section lists them. Specs it names but does not hold are marked with the skill that has them. # REQUIREMENTS - **The target HMIS source**, with its build, test and migration commands working. - **NHCX participant credentials** for the facility: participant code, ABDM client id and client secret, and the private key of the encryption certificate registered for that code. - **A public URL** NHCX can reach, registered as the participant's `endpoint_url`, routed to the application's inbound path (`/in/` or `/v1/`). - **A knowledge source**: the nhcx-docs MCP server, or network access to download the NHCX package (see KNOWLEDGE SOURCE). - For end-to-end tests: sandbox credentials, a sandbox payer that answers, and test beneficiaries. # KNOWLEDGE SOURCE NHCX facts (API paths and headers, FHIR profiles and example bundles, codes, workflow ids, error codes, go-live rules) come from one knowledge source, chosen at the start of L1 and recorded in `nhcx-plan/knowledge.json`. Details: [references/KNOWLEDGE.md](references/KNOWLEDGE.md). 1. **nhcx-docs MCP.** If the `nhcx-docs` MCP server is connected (`catalogue_info` answers), use it: `search_docs`, `get_operation`, `get_fhir_profile`, `get_fhir_example`, `validate_fhir`, `validate_request`, `decode_error`. 2. **GitHub package.** Otherwise download the latest release zip from [github.com/nha-in/nhcx-package/releases](https://github.com/nha-in/nhcx-package/releases) (`nhcx-package-v.zip`), keep it as `nhcx-plan/knowledge/nhcx-package-v.zip`, extract it to `nhcx-plan/knowledge/nhcx-package/`, and check it against its `MANIFEST`. On the protocol the knowledge source wins over these specs; on what the application does, the specs win. Statements that are not the protocol are marked [REF](references/PAYERS.md#markers) (a reference-implementation choice), [PAYER](references/PAYERS.md#markers) (depends on the payer adapter) or [SANDBOX](references/PAYERS.md#markers) (seen only in the sandbox); every payer-specific value is in [references/PAYERS.md](references/PAYERS.md). Its ids (NHA use cases such as `C5`) are not this skill's ids: write them as `nha:C5`. # STEPS Follow [steps/INDEX.md](steps/INDEX.md) in order. Each step writes one file under `nhcx-plan/` in the target repository, and every sub-step and file change is logged in `nhcx-plan/progress.json` and `nhcx-plan/progress.md` ([steps/LOG.md](steps/LOG.md)). 1. [L1 Discovery](steps/L1-discovery.md): the knowledge source, the target's technology, and every spec item in SCOPE found, partial or missing, with file and lines. 2. [L2 Mapping](steps/L2-mapping.md): target fields to database columns and FHIR elements. 3. [L3 Integration Planning](steps/L3-integration-planning.md): phases, steps and sub-steps for this target, in the build order of the [SCAFFOLDING](references/SCAFFOLDING.md), including the "Claims" entry on the HMIS home screen, sidebar or navbar. 4. [L4 Code Planning](steps/L4-code-planning.md): files, functions and order, laid out by mapping the [SCAFFOLDING](references/SCAFFOLDING.md) onto the target's conventions. 5. [L5 Write Code](steps/L5-write-code.md): file by file, recorded in `nhcx-plan/code.json`, keeping the scaffolding's dependency rules. 6. [L6 Validate Code](steps/L6-validate-code.md): each file against its specs. 7. [L7 Dry-run Tests](steps/L7-dry-run-tests.md): no network; fakes for NHCX and the registry. 8. [L8 End-to-end Tests](steps/L8-e2e-tests.md): against the NHCX sandbox. # SCAFFOLDING [references/SCAFFOLDING.md](references/SCAFFOLDING.md) is the shape the code takes in the target HMIS. Read it before L3 and keep it open through L5. - **One NHCX module** (`nhcx/`) holding `gateway/` (G, in-process), `fhir/` (F, pure builders and parsers), `services/` (A), `callbacks/` (C), `models/` and `migrations/` (D), `screens/` and `routes` (S), and the message `archive`. - **Existing HMIS modules** change only for the fields NHCX needs: patient ABHA (D3), practitioner HPR id and qualification (D2), facility HFR id and participant code (D1), and the "Claims" navigation entry. - **Dependency rules:** screens call services and read models; only services and callbacks write claim tables; FHIR builders never touch the database or the gateway; the gateway knows nothing about claims; a reply found by polling is applied by the same callback handler. - **Outside the repository:** the gateway config, client secret, private key, ledger and archive directories. - **Tests** under `tests/nhcx/` (dry-run and end-to-end), and **plan files** under `nhcx-plan/`. - **Build order** in phases, from the gateway foundation to the navigation entry; L3 plans in that order and leaves out phases whose specs are not in SCOPE. L4 maps these placeholder names onto the target's own conventions (a Django app, a Spring module, a Node package); the split between parts and the dependency direction do not change. # SCOPE The specs this skill holds: - **Screens** (16): [S1](screens/S1-search-policy.md), [S2](screens/S2-select-policy.md), [S3](screens/S3-policy-discovery.md), [S4](screens/S4-claim-creation-form.md), [S5](screens/S5-claim-master.md), [S6](screens/S6-claim-detail.md), [S7](screens/S7-insurance-plan.md), [S8](screens/S8-line-items.md), [S9](screens/S9-preauthorisation.md), [S10](screens/S10-communication.md), [S11](screens/S11-claim-submission.md), [S12](screens/S12-payments.md), [S13](screens/S13-patient-list.md), [S14](screens/S14-patient-registration-form.md), [S15](screens/S15-patient-detail.md), [S16](screens/S16-practitioner-master.md) - **APIs** (16): [A1](apis/A1-policy-search.md), [A2](apis/A2-coverage-eligibility-check.md), [A3](apis/A3-insurance-plan-request.md), [A4](apis/A4-preauth-submit.md), [A5](apis/A5-claim-submit.md), [A6](apis/A6-task-submit.md), [A7](apis/A7-communication-on-request.md), [A8](apis/A8-paymentnotice-on-request.md), [A10](apis/A10-txn-related.md), [A11](apis/A11-txn-dispatch.md), [A12](apis/A12-txn-fhir.md), [A13](apis/A13-txn-list.md), [A14](apis/A14-adjudicator-user-role.md), [A15](apis/A15-adjudicator-process-case.md), [A16](apis/A16-gateway-token.md), [A17](apis/A17-claim-state.md) - **Callbacks** (10): [C1](callbacks/C1-callback-door.md), [C2](callbacks/C2-coverage-eligibility-on-check.md), [C3](callbacks/C3-auth-requirements-on-check.md), [C4](callbacks/C4-insuranceplan-on-request.md), [C5](callbacks/C5-preauth-on-submit.md), [C6](callbacks/C6-claim-on-submit.md), [C7](callbacks/C7-cancel-on-submit.md), [C8](callbacks/C8-enquiry-on-submit.md), [C9](callbacks/C9-communication-request.md), [C10](callbacks/C10-paymentnotice-request.md) - **FHIR** (19): [F1](fhir/F1-bundle.md), [F2](fhir/F2-coverage-eligibility-request.md), [F3](fhir/F3-coverage-eligibility-response.md), [F4](fhir/F4-task-insuranceplan.md), [F5](fhir/F5-insuranceplan.md), [F6](fhir/F6-questionnaire.md), [F7](fhir/F7-questionnaireresponse.md), [F8](fhir/F8-claim.md), [F9](fhir/F9-claimresponse.md), [F10](fhir/F10-task-claim-actions.md), [F11](fhir/F11-communicationrequest.md), [F12](fhir/F12-communication.md), [F13](fhir/F13-paymentnotice.md), [F14](fhir/F14-payment-acknowledgement.md), [F15](fhir/F15-patient.md), [F16](fhir/F16-practitioner.md), [F17](fhir/F17-organization.md), [F18](fhir/F18-coverage.md), [F19](fhir/F19-other-resources.md) - **Database** (30): [D1](database/D1-organization.md), [D2](database/D2-practitioner.md), [D3](database/D3-patient.md), [D4](database/D4-encounter.md), [D5](database/D5-condition.md), [D6](database/D6-observation.md), [D7](database/D7-allergy.md), [D8](database/D8-terminology.md), [D9](database/D9-claim.md), [D10](database/D10-claim-plan.md), [D11](database/D11-claim-plan-benefit.md), [D12](database/D12-claim-plan-form.md), [D13](database/D13-claim-auth.md), [D14](database/D14-claim-auth-item.md), [D15](database/D15-claim-auth-requirement.md), [D16](database/D16-claim-line.md), [D17](database/D17-claim-form-answer.md), [D18](database/D18-claim-preauth.md), [D19](database/D19-claim-predetermination.md), [D20](database/D20-claim-submission.md), [D21](database/D21-claim-payment.md), [D22](database/D22-claim-payment-detail.md), [D23](database/D23-claim-query.md), [D24](database/D24-claim-adjudication.md), [D25](database/D25-claim-diagnosis.md), [D26](database/D26-claim-care-team.md), [D27](database/D27-claim-item.md), [D28](database/D28-claim-document.md), [D29](database/D29-claim-enquiry.md), [D30](database/D30-counter.md) - **Gateway** (11): [G1](gateway/G1-embedding.md), [G2](gateway/G2-configuration.md), [G3](gateway/G3-session-token.md), [G4](gateway/G4-registry.md), [G5](gateway/G5-protocol-headers.md), [G6](gateway/G6-encryption.md), [G7](gateway/G7-send.md), [G8](gateway/G8-receive.md), [G9](gateway/G9-ledger.md), [G10](gateway/G10-beneficiary-registry.md), [G11](gateway/G11-startup-checks.md) Other skills built from the same source: - **nhcx-coverage**: beneficiary policy search and coverage eligibility. - **nhcx-preauth**: pre-authorisation: the payer's plan, line items, authorisation requirements, pre-auth, enhancement, cancel and status. - **nhcx-claim**: claim submission after discharge, its verdict and status. - **nhcx-communication**: payer queries, notifications and notes, and the replies to them. - **nhcx-payment**: payment notices and their acknowledgement. - **nhcx-reprocess**: reprocess and balance release on a decided or partly paid claim. # REFERENCES - [references/CORE.md](references/CORE.md): base URLs, and every exchange with its route, bundles, workflow id and callback, on one page. - [references/KNOWLEDGE.md](references/KNOWLEDGE.md): the NHCX knowledge source, MCP or GitHub package, and which lookup answers which question. - [references/SCREENS.md](references/SCREENS.md): every screen in scope, its route and what it does. - [references/API.md](references/API.md): every API call in scope and what it does. - [references/CALLBACK.md](references/CALLBACK.md): every NHCX callback in scope and what it does. - [references/GATEWAY.md](references/GATEWAY.md): every part of the in-process NHCX gateway and what it does. - [references/FHIR.md](references/FHIR.md): every FHIR resource in scope, sent or read, and what it is. - [references/DATABASE.md](references/DATABASE.md): every table in scope, what one row is, and which screens, APIs, callbacks and FHIR resources use it. - [references/PAYERS.md](references/PAYERS.md): the payer adapters, their workflow ids and rules, and what the [REF](references/PAYERS.md#markers), [PAYER](references/PAYERS.md#markers) and [SANDBOX](references/PAYERS.md#markers) markers mean. - [references/OPERATIONS.md](references/OPERATIONS.md): production cutover, and running the application as more than one instance. - [references/READSETS.md](references/READSETS.md): for each screen, API, callback and gateway part, the other specs to read before implementing it. - [references/SCAFFOLDING.md](references/SCAFFOLDING.md): the module layout in the target, what each part holds and where each spec lands. # OUTPUT In the target repository: - **Code** in the NHCX module and the changed HMIS modules, as laid out in SCAFFOLDING. - **Tests** under `tests/nhcx/`: dry-run (L7) and end-to-end (L8). - **Plan files** under `nhcx-plan/`: `knowledge.json`, `discovery.json`, `mapping.json`, `plan.json`, `code-plan.json`, `code.json`, `validation.json`, `dry-run.json`, `e2e.json`, and the log `progress.json` with `progress.md`.