e212f20a34
- cms855_pdf_filler.py: fills official CMS-855I/B/O/A AcroForms from intake (name, NPI, DOB, cert-page printed name) and records the signature anchor at the form's official /Sig box so the e-sign stamper lands on the cert line. - npi_provider handlers (revalidation/reactivation/enrollment) now generate the paper CMS-855, upload it to MinIO, request_esign with anchors, and email the signing link. Human completes/verifies + USPS Priority Mails to the MAC. - scripts/Dockerfile: copy the official CMS-855I/B/O/A forms into the image.
340 lines
14 KiB
Python
340 lines
14 KiB
Python
"""Healthcare / NPI provider compliance handlers.
|
|
|
|
Review-staged: each NPI service generates an admin todo with the provider's
|
|
NPI + intake details for a human to file in CMS PECOS / NPPES. This mirrors the
|
|
FCC auto-filing-off safety default — no automated submission to government
|
|
portals until the Playwright flows are proven.
|
|
|
|
Covers slugs:
|
|
npi-revalidation Medicare PECOS revalidation (5-yr cycle)
|
|
npi-reactivation reactivate a deactivated NPI
|
|
nppes-update NPPES data update / attestation
|
|
medicare-enrollment new Medicare enrollment via PECOS
|
|
oig-sam-screening OIG LEIE + SAM exclusion screening (annual)
|
|
provider-compliance-bundle revalidation watch + screening + NPPES upkeep
|
|
|
|
Intake data needed (collected by the npi-intake wizard step):
|
|
- npi provider's 10-digit NPI
|
|
- provider_name legal/provider name
|
|
- email contact email
|
|
- pecos_enrollment_id (optional) PECOS enrollment ID
|
|
- specialty (optional) taxonomy/specialty
|
|
- practice_state (optional) practice location state
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import logging
|
|
import os
|
|
|
|
LOG = logging.getLogger("workers.services.npi_provider")
|
|
|
|
# Per-slug admin todo metadata: human-readable action + the portal a human uses.
|
|
_SLUG_META = {
|
|
"npi-revalidation": {
|
|
"name": "Medicare PECOS Revalidation Filing",
|
|
"portal": "https://pecos.cms.hhs.gov/",
|
|
"action": (
|
|
"File the Medicare revalidation in PECOS for this provider. Confirm "
|
|
"the revalidation due date on the CMS revalidation list, update the "
|
|
"enrollment record, and submit. Capture the PECOS tracking ID."
|
|
),
|
|
"access": (
|
|
"PECOS via CMS I&A surrogacy (preferred). Fallback: paper CMS-855I/B/R, provider wet-signs cert page, mail to provider's MAC."
|
|
),
|
|
"priority": "high",
|
|
},
|
|
"npi-reactivation": {
|
|
"name": "NPI Reactivation",
|
|
"portal": "https://nppes.cms.hhs.gov/",
|
|
"action": (
|
|
"Reactivate the deactivated NPI in NPPES. Verify the deactivation "
|
|
"reason, correct any stale data, and re-certify the record."
|
|
),
|
|
"access": (
|
|
"NPPES via CMS I&A surrogacy. No paper option (NPPES is web-only)."
|
|
),
|
|
"priority": "high",
|
|
},
|
|
"nppes-update": {
|
|
"name": "NPPES Data Update / Attestation",
|
|
"portal": "https://nppes.cms.hhs.gov/",
|
|
"action": (
|
|
"Update + re-attest the provider's NPPES record (CMS requires "
|
|
"updates within 30 days of any change). Apply the requested field "
|
|
"changes and certify."
|
|
),
|
|
"access": (
|
|
"NPPES via CMS I&A surrogacy. No paper option (NPPES is web-only)."
|
|
),
|
|
"priority": "normal",
|
|
},
|
|
"medicare-enrollment": {
|
|
"name": "Medicare Enrollment (PECOS)",
|
|
"portal": "https://pecos.cms.hhs.gov/",
|
|
"action": (
|
|
"Complete the provider's Medicare enrollment in PECOS (CMS-855). "
|
|
"Confirm taxonomy, practice location, and authorized official."
|
|
),
|
|
"access": (
|
|
"PECOS via CMS I&A surrogacy (preferred). Fallback: paper CMS-855, provider wet-signs, mail to MAC."
|
|
),
|
|
"priority": "high",
|
|
},
|
|
"oig-sam-screening": {
|
|
"name": "OIG/SAM Exclusion Screening (Annual)",
|
|
"portal": "https://oig.hhs.gov/exclusions/ + https://sam.gov/",
|
|
"action": (
|
|
"Run the provider (and any listed staff) against the OIG LEIE and "
|
|
"SAM exclusion lists. Produce the screening certificate and flag any "
|
|
"matches for escalation."
|
|
),
|
|
"access": (
|
|
"No client access needed - OIG LEIE + SAM.gov are public. Screen by NPI/name, issue certificate."
|
|
),
|
|
"priority": "normal",
|
|
},
|
|
"provider-compliance-bundle": {
|
|
"name": "Provider Compliance Bundle (Annual)",
|
|
"portal": "https://pecos.cms.hhs.gov/ + https://nppes.cms.hhs.gov/",
|
|
"action": (
|
|
"Onboard the provider into the annual compliance bundle: enroll in "
|
|
"revalidation watch, run OIG/SAM screening, and refresh the NPPES "
|
|
"record. Set the next revalidation reminder."
|
|
),
|
|
"access": (
|
|
"PECOS/NPPES via CMS I&A surrogacy; screening is public. Paper CMS-855 fallback for the enrollment/revalidation piece."
|
|
),
|
|
"priority": "high",
|
|
},
|
|
}
|
|
|
|
# Slugs whose fulfilment includes a paper CMS-855 (auto-filled official form,
|
|
# e-signed, then printed + USPS Priority-mailed to the provider's MAC). The
|
|
# bundle's revalidation piece is handled by the dedicated revalidation order it
|
|
# spawns, so it is not listed here.
|
|
_PAPER_855_SLUGS = {
|
|
"npi-revalidation",
|
|
"npi-reactivation",
|
|
"medicare-enrollment",
|
|
}
|
|
|
|
|
|
class _BaseNPIHandler:
|
|
"""Shared review-staged behaviour for all NPI services."""
|
|
|
|
SERVICE_SLUG = ""
|
|
|
|
async def process(self, order_data: dict) -> list[str]:
|
|
order_number = order_data.get("order_number", order_data.get("name", ""))
|
|
return await self.handle(order_data, order_number)
|
|
|
|
async def handle(self, order_data: dict, order_number: str) -> list[str]:
|
|
meta = _SLUG_META[self.SERVICE_SLUG]
|
|
LOG.info("[%s] Processing %s", order_number, self.SERVICE_SLUG)
|
|
|
|
intake = order_data.get("intake_data") or {}
|
|
if isinstance(intake, str):
|
|
intake = json.loads(intake)
|
|
|
|
npi = intake.get("npi", "N/A")
|
|
provider = intake.get("provider_name", order_data.get("customer_name", "Unknown"))
|
|
specialty = intake.get("specialty", "")
|
|
practice_state = intake.get("practice_state", "")
|
|
pecos_id = intake.get("pecos_enrollment_id", "")
|
|
customer_email = (
|
|
intake.get("email")
|
|
or order_data.get("customer_email")
|
|
or order_data.get("email")
|
|
or ""
|
|
)
|
|
|
|
# For PECOS enrollment/revalidation we generate the official CMS-855,
|
|
# send it for e-signature, then a human prints + USPS-mails it to the MAC.
|
|
paper_note = ""
|
|
if self.SERVICE_SLUG in _PAPER_855_SLUGS:
|
|
try:
|
|
paper_note = self._generate_855_for_signing(
|
|
order_number, intake, provider, customer_email
|
|
)
|
|
except Exception as exc: # never block the admin todo on PDF issues
|
|
LOG.error("[%s] CMS-855 generation failed: %s", order_number, exc)
|
|
paper_note = f"CMS-855 auto-generation FAILED ({exc}); prepare the form manually."
|
|
|
|
description = (
|
|
f"{meta['action']}\n\n"
|
|
f"Provider: {provider}\n"
|
|
f"NPI: {npi}\n"
|
|
f"PECOS Enrollment ID: {pecos_id or 'not provided'}\n"
|
|
f"Specialty: {specialty or 'not provided'}\n"
|
|
f"Practice state: {practice_state or 'not provided'}\n"
|
|
f"Portal: {meta['portal']}\n"
|
|
f"Access model: {meta['access']}\n"
|
|
+ (f"\n{paper_note}\n" if paper_note else "")
|
|
+ "\nReview-staged: complete/verify the form, get it signed, then "
|
|
"print and USPS Priority Mail it to the provider's MAC (or file in "
|
|
"PECOS if surrogate access was granted). Mark this order complete."
|
|
)
|
|
|
|
self._create_todo(
|
|
order_number,
|
|
intake,
|
|
title=f"{meta['name']} — {provider} (NPI {npi})",
|
|
description=description,
|
|
priority=meta["priority"],
|
|
)
|
|
return []
|
|
|
|
def _generate_855_for_signing(self, order_number, intake, provider, customer_email) -> str:
|
|
"""Generate the official CMS-855, upload it, and request an e-signature.
|
|
|
|
Returns a human-readable note for the admin todo describing what was
|
|
generated and what still needs manual completion. The signed PDF is
|
|
printed and USPS Priority-mailed to the MAC by the fulfilment team.
|
|
"""
|
|
try:
|
|
from scripts.document_gen.templates.cms855_pdf_filler import (
|
|
determine_form_type, fill_cms855,
|
|
)
|
|
except ImportError:
|
|
from document_gen.templates.cms855_pdf_filler import ( # type: ignore
|
|
determine_form_type, fill_cms855,
|
|
)
|
|
|
|
form_type = determine_form_type(self.SERVICE_SLUG, intake)
|
|
pdf_bytes, anchors, missing = fill_cms855(form_type, intake, order_number)
|
|
|
|
# Upload the unsigned, partially-filled official form to MinIO.
|
|
document_key = f"compliance/{order_number}/cms{form_type}_unsigned.pdf"
|
|
try:
|
|
import tempfile
|
|
try:
|
|
from scripts.document_gen.minio_client import MinioStorage
|
|
except ImportError:
|
|
from document_gen.minio_client import MinioStorage # type: ignore
|
|
storage = MinioStorage()
|
|
with tempfile.NamedTemporaryFile(suffix=".pdf", delete=True) as tf:
|
|
tf.write(pdf_bytes)
|
|
tf.flush()
|
|
storage.upload(tf.name, document_key, content_type="application/pdf")
|
|
except Exception as exc:
|
|
LOG.error("[%s] CMS-855 upload failed: %s", order_number, exc)
|
|
return f"CMS-{form_type.upper()} generated but upload FAILED ({exc})."
|
|
|
|
# Create the esign record (via the shared helper, which also emails the
|
|
# signing link) and attach the official signature anchor so the stamper
|
|
# lands the signature on the certification line.
|
|
signed = self._create_855_esign_record(
|
|
order_number, intake, provider, customer_email,
|
|
form_type, document_key, anchors,
|
|
)
|
|
|
|
note_lines = [
|
|
f"PAPER CMS-{form_type.upper()} generated (official form, auto-filled where possible).",
|
|
f"Unsigned PDF: {document_key}",
|
|
]
|
|
if signed and customer_email:
|
|
note_lines.append(f"E-sign link emailed to {customer_email}. After signing, print + USPS Priority Mail to the MAC.")
|
|
else:
|
|
note_lines.append("No customer email or esign infra — send the form for wet signature manually.")
|
|
if missing:
|
|
note_lines.append("MANUAL COMPLETION NEEDED:")
|
|
note_lines.extend(f" - {m}" for m in missing)
|
|
return "\n".join(note_lines)
|
|
|
|
def _create_855_esign_record(self, order_number, intake, provider, customer_email,
|
|
form_type, document_key, anchors) -> bool:
|
|
"""Create the esign record + email the signing link via the shared helper,
|
|
then attach the official signature anchors. Returns True on success.
|
|
"""
|
|
if not customer_email:
|
|
return False
|
|
|
|
document_type = f"cms{form_type}"
|
|
document_title = f"Medicare Enrollment Form (CMS-{form_type.upper()})"
|
|
|
|
try:
|
|
try:
|
|
from scripts.workers.services.telecom.esign_helper import request_esign
|
|
except ImportError:
|
|
from .telecom.esign_helper import request_esign # type: ignore
|
|
import psycopg2
|
|
|
|
conn = psycopg2.connect(os.environ.get("DATABASE_URL", ""))
|
|
try:
|
|
esign_id = request_esign(
|
|
conn=conn,
|
|
order_number=order_number,
|
|
document_type=document_type,
|
|
document_title=document_title,
|
|
entity_name=provider,
|
|
customer_email=customer_email,
|
|
customer_name=provider,
|
|
document_minio_key=document_key,
|
|
requires_perjury=True,
|
|
metadata={"service_slug": self.SERVICE_SLUG, "npi": intake.get("npi", ""), "form_type": form_type},
|
|
expires_hours=21 * 24,
|
|
)
|
|
# request_esign does not persist signature anchors; attach them so
|
|
# the stamper places the signature on the certification line.
|
|
if esign_id and anchors:
|
|
with conn.cursor() as cur:
|
|
cur.execute(
|
|
"UPDATE esign_records SET signature_anchors = %s, updated_at = NOW() WHERE id = %s",
|
|
(json.dumps(anchors), esign_id),
|
|
)
|
|
conn.commit()
|
|
return esign_id is not None
|
|
finally:
|
|
conn.close()
|
|
except Exception as exc:
|
|
LOG.error("[%s] CMS-855 esign request failed: %s", order_number, exc)
|
|
return False
|
|
|
|
def _create_todo(self, order_number, intake, title, description, priority="normal"):
|
|
try:
|
|
import psycopg2
|
|
|
|
conn = psycopg2.connect(os.environ.get("DATABASE_URL", ""))
|
|
with conn.cursor() as cur:
|
|
cur.execute(
|
|
"""
|
|
INSERT INTO admin_todos (
|
|
title, category, priority, order_number, service_slug,
|
|
description, data, status
|
|
) VALUES (%s, %s, %s, %s, %s, %s, %s, 'pending')
|
|
""",
|
|
(
|
|
title, "filing", priority, order_number,
|
|
self.SERVICE_SLUG, description, json.dumps(intake),
|
|
),
|
|
)
|
|
conn.commit()
|
|
conn.close()
|
|
except Exception as exc:
|
|
LOG.error("[%s] Failed to create NPI todo: %s", order_number, exc)
|
|
|
|
|
|
class NPIRevalidationHandler(_BaseNPIHandler):
|
|
SERVICE_SLUG = "npi-revalidation"
|
|
|
|
|
|
class NPIReactivationHandler(_BaseNPIHandler):
|
|
SERVICE_SLUG = "npi-reactivation"
|
|
|
|
|
|
class NPPESUpdateHandler(_BaseNPIHandler):
|
|
SERVICE_SLUG = "nppes-update"
|
|
|
|
|
|
class MedicareEnrollmentHandler(_BaseNPIHandler):
|
|
SERVICE_SLUG = "medicare-enrollment"
|
|
|
|
|
|
class OIGSAMScreeningHandler(_BaseNPIHandler):
|
|
SERVICE_SLUG = "oig-sam-screening"
|
|
|
|
|
|
class ProviderComplianceBundleHandler(_BaseNPIHandler):
|
|
SERVICE_SLUG = "provider-compliance-bundle"
|