Si gestiona usted un plan Medicare Advantage, CMS le exige ahora publicar un directorio de proveedores que liste qué proveedores e instalaciones forman parte de la red de cada plan, para que Medicare Plan Finder (MPF) pueda responder a la pregunta que los usuarios realmente formulan: ¿está cubierto mi proveedor? Esa pregunta es específica de MA: un plan MA cubre una red contratada y, dado que MA es Medicare de financiación federal gestionado por aseguradoras privadas, CMS tiene potestad para dictar cómo se publica el directorio. El directorio debe ser legible por máquina, actualizarse en un plazo de 30 días tras cualquier cambio y atestiguarse una vez al año. Forma parte de la apuesta más amplia de CMS por la interoperabilidad basada en FHIR.
CMS acepta dos formatos: un archivo JSON plano o FHIR; aquí se construye el formato FHIR. Este sigue PDex Plan-Net, el IG de Da Vinci que estandariza la red de un plan mediante perfiles FHIR sobre InsurancePlan, Organization (tanto como red como instalación), Practitioner, PractitionerRole, Location y OrganizationAffiliation, así como las referencias entre ellos. CMS no consulta su servidor por cada usuario: su rastreador ingiere los archivos publicados una vez al día y los valida, siguiendo su guía técnica de implementación. Si falla la validación, incumple la atestación anual o supera el umbral de calidad de datos de CMS, este suprimirá su directorio de MPF y, por lo general, lo restaurará al día siguiente de resolverse el problema. Mientras esté suprimido, los usuarios que comparan planes no podrán ver su red, por lo que mantener el directorio válido en cada ejecución es fundamental.
El resto de este artículo describe esa canalización, fase por fase.
Cómo funciona
Sus datos ya residen en Payerbox. La canalización los convierte en los archivos que CMS rastrea, según una programación. Cuatro fases:
La ejecución diaria, de principio a fin: extracción desde Payerbox, filtrado al subconjunto de la red, empaquetado como FHIR y publicación de los archivos que CMS rastrea.
Un trabajo programado ejecuta todo el proceso cada mañana, antes del rastreo diario de CMS.
Todo lo que sigue a la extracción es código ordinario sobre NDJSON, por lo que se ejecuta y prueba sobre una exportación de muestra, sin necesidad de un servidor FHIR activo.
Cómo extraer los datos
Existen dos formas de obtener los recursos de Payerbox. La canalización lee a través de una interfaz
de origen común, por lo que cualquiera de las dos podría alimentarla; aquí se utiliza $export masivo.
- La API REST de FHIR. Paginación mediante consultas de búsqueda ordinarias. Es una opción adecuada para un subconjunto pequeño y preciso, pero extraer tipos de recursos completos a escala implica muchas llamadas de ida y vuelta, y los datos pueden cambiar entre páginas.
- La operación
$exportmasivo de FHIR. Esta operación se ejecuta de forma asíncrona y transmite todo como NDJSON en un solo paso, sin la deriva entre páginas que ocasiona la paginación sobre la API en tiempo real. Está diseñada para esto, y es la que se utiliza aquí.
$export es la operación estándar FHIR Bulk Data Access,
con _typeFilter para aplicar filtros selectivos en la exportación y +gzip en _outputFormat para
mantener el volcado en un tamaño reducido. Con _typeFilter, el servidor envía únicamente los recursos
que importan:
GET /fhir/$export
?_outputFormat=application/fhir+ndjson+gzip
&_type=InsurancePlan,Organization,Practitioner,PractitionerRole,Location,OrganizationAffiliation
&_typeFilter=InsurancePlan?status=active&_profile=.../plannet-InsurancePlan&_id=...
&_typeFilter=PractitionerRole?active=true&_profile=.../plannet-PractitionerRole&network=...
&_typeFilter=OrganizationAffiliation?active=true&_profile=.../plannet-OrganizationAffiliation&network=...
Iniciado con el encabezado de solicitud Prefer: respond-async, $export devuelve 202 Accepted
con un encabezado de respuesta Content-Location: la URL de estado que se sondea hasta que los archivos
NDJSON estén listos. Los planes, los roles de profesional y las afiliaciones se devuelven ya filtrados
a los recursos activos, de la red y de Plan-Net. Los elementos hijo que estos referencian llegan
completos, de modo que un registro conservado nunca apunta a algo eliminado.
Filtrado al subconjunto de la red
Ese $export fue el primer filtro: _typeFilter reduce los elementos padre en el servidor FHIR.
Un paso a nivel de código resuelve entonces los elementos hijo: recorre el grafo (plan → red →
organizaciones y profesionales afiliados → sus ubicaciones), conserva un elemento hijo únicamente
cuando un elemento padre conservado lo referencia, y descarta el resto. Ese grafo son las referencias
que PDex Plan-Net define entre los seis recursos:
Las referencias entre los recursos de Plan-Net. _typeFilter reduce los elementos padre (InsurancePlan,
PractitionerRole, OrganizationAffiliation) en el servidor FHIR; el paso de código conserva entonces
los elementos hijo que estos referencian.
Empaquetado y publicación
Los recursos conservados se incluyen en Bundles de FHIR
(type: collection), divididos por tipo de recurso en archivos numerados (PractitionerRole-001.json,
-002.json, etc.); cada recurso conserva su meta.lastUpdated de origen, que la guía asocia a la fecha
de última actualización de cada registro. CMS espera esa división: requiere un archivo índice por contrato,
un manifiesto con la URL de cada archivo que el rastreador lee en primer lugar:
{
"provider_urls": [
"https://.../H9999/2026/InsurancePlan-001.json",
"https://.../H9999/2026/PractitionerRole-001.json",
"https://.../H9999/2026/PractitionerRole-002.json",
"https://.../H9999/2026/Organization-001.json"
]
}
La división mantiene cada archivo en un tamaño manejable para el rastreador; la canalización pasa al siguiente archivo numerado cuando un bundle supera un tamaño excesivo o un límite de entradas.
La publicación tiene una regla estricta: un rastreo nunca debe aterrizar en un directorio
parcialmente escrito. Un archivo como Organization-042.json contiene recursos distintos de una
ejecución a la siguiente, por lo que sobreescribirlo en su lugar mientras el manifiesto antiguo aún
apunta a él produce una lectura inconsistente. Por tanto, la publicación es un intercambio atómico:
se eliminan los archivos antiguos, se suben los nuevos bundles y, a continuación, se sube index.json
en último lugar. Esa última subida es el único paso que pone en línea la nueva versión, de modo que un
rastreador en mitad de la publicación ve el directorio de ayer, el de hoy o un breve 404 durante el
intercambio, pero nunca una mezcla parcialmente escrita. Una ejecución que falle a mitad genera una
alerta. No existe reanudación parcial: la siguiente ejecución simplemente reconstruye todo el directorio
desde cero.
Servir al rastreador
CMS recomienda solicitudes condicionales, y el endpoint las sirve. Cada archivo lleva un ETag
(una huella de su contenido que cambia cuando el archivo lo hace) y una marca temporal Last-Modified;
el rastreador los almacena y, en su siguiente visita, vuelve a descargar un archivo solo cuando su
ETag ha cambiado. Los archivos sin cambios se devuelven como 304 Not Modified sin cuerpo:
GET /mpf-provider-directory/H9999/2026/Organization-042.json
If-None-Match: "a1b2c3" # the ETag the crawler received on its last fetch
→ 304 Not Modified # unchanged since then, so no body
En un directorio de miles de archivos bundle que apenas cambian de un día para otro, esa es la
diferencia entre un rastreo costoso y uno económico. También explica la publicación atómica: el ETag
debe cambiar exactamente cuando cambia el contenido.
Ese endpoint actúa como proxy de un bucket privado en lugar de exponer el bucket directamente, y no requiere autenticación: el directorio Plan-Net está concebido para ser de acceso abierto, sin registro de cliente.
¿Desea construir el suyo propio?
Construirlo representa una ingeniería relativamente modesta para cualquier persona que trabaje habitualmente con servidores FHIR: un trabajo diario de exportación-filtrado-empaquetado-publicación. Pero el cuidado reside en hacerlo correctamente en cada ejecución, y todo ello presupone que en el servidor FHIR ya existen datos correctos de Plan-Net. Lograr esto es un proyecto en sí mismo. La calidad de sus datos debe monitorizarse de forma continua, validando el conjunto de recursos PDex Plan-Net frente a los criterios MPF de CMS.
Este directorio se incluye como módulo opcional de Payerbox, la plataforma de Health Samurai para los requisitos de pagadores de CMS, que también proporciona las APIs de CMS-0057-F con vencimiento en 2027.
¿Está construyendo un directorio de proveedores para Medicare Plan Finder? Hable con nuestro equipo para comenzar.
