@qrcommunication/rppsapi

SDK TypeScript pour interroger l'ensemble des sources de donnees RPPS (Repertoire Partage des Professionnels de Sante) de l'Annuaire Sante, publiees par l'ANS (Agence du Numerique en Sante) et data.gouv.fr.

En un seul appel, le SDK recupere et fusionne les donnees de 6 sources publiques pour constituer le profil complet d'un professionnel de sante : identite, activites, diplomes, savoir-faire, cartes CPS et messageries MSSante.

Fonctionnalites

Profil complet en un appel : fusionne 6 sources de donnees pour un numero RPPS donne
Recherche multicritere : recherche par nom, prenom et/ou code postal avec pagination
Requetes paralleles : toutes les sources sont interrogees simultanement via Promise.all
Zero dependance : utilise uniquement fetch natif (Node 18+)
TypeScript natif : types complets pour l'autocompletion et la surete de type
Gestion d'erreurs resiliente : chaque source est isolee, un echec ne bloque pas les autres
Metadonnees detaillees : statut, nombre de resultats et duree de chaque source
Sources desactivables : possibilite de desactiver individuellement chaque source
FHIR optionnel : la source FHIR est automatiquement desactivee sans cle API
ESM natif : module ES moderne, compatible avec les bundlers actuels

Sources de donnees

Le SDK interroge 6 sources publiques distinctes :

Source	API	Description	Donnees
Personne-Activite	Tabular API data.gouv.fr	Fichier principal de l'Annuaire Sante	Identite, profession, structures d'exercice, adresses
Diplomes & Autorisations	Tabular API data.gouv.fr	Diplomes obtenus et autorisations d'exercice	Type de diplome, discipline, autorisations
Savoir-faire	Tabular API data.gouv.fr	Competences et specialites declarees	Specialites, competences, qualifications
Cartes CPS/CPF	Tabular API data.gouv.fr	Cartes de professionnel de sante	Numero de carte, type, dates de validite
Messageries MSSante	Tabular API data.gouv.fr	Boites aux lettres securisees MSSante	Adresses BAL, structures de rattachement
FHIR Annuaire Sante	API FHIR ANS (Gravitee)	Standard FHIR R4 de l'ANS	Practitioner, PractitionerRole (necessite une cle API)

Les 5 sources Tabular API sont en acces libre, sans authentification. Seule la source FHIR necessite une cle API Gravitee.

Installation

# npm
npm install @qrcommunication/rppsapi

# pnpm
pnpm add @qrcommunication/rppsapi

# yarn
yarn add @qrcommunication/rppsapi

# bun
bun add @qrcommunication/rppsapi

Quick Start

import { RppsClient } from '@qrcommunication/rppsapi';

const client = new RppsClient();

// Recuperer le profil complet d'un praticien
const profil = await client.getByRpps('10000001866');

console.log(profil.identite.nomExercice);       // Nom du praticien
console.log(profil.profession.libelle);          // Ex: "Medecin"
console.log(profil.activites.length);            // Nombre de structures d'exercice
console.log(profil.diplomesEtAutorisations);     // Diplomes et autorisations
console.log(profil.metadata.totalDurationMs);    // Temps total en ms

API Reference

`new RppsClient(options?)`

Cree une instance du client SDK. Tous les parametres sont optionnels.

import { RppsClient } from '@qrcommunication/rppsapi';

const client = new RppsClient({
  fhirApiKey: process.env.FHIR_API_KEY,
  timeout: 60_000,
});

Options de configuration

Parametre	Type	Defaut	Description
`fhirBaseUrl`	`string`	`https://gateway.api.esante.gouv.fr/fhir/v2`	URL de base de l'API FHIR Annuaire Sante
`fhirApiKey`	`string`	`''`	Cle API FHIR (header `ESANTE-API-KEY`). Sans cette cle, la source FHIR est automatiquement desactivee
`tabularBaseUrl`	`string`	`https://tabular-api.data.gouv.fr/api/resources`	URL de base de l'API Tabular data.gouv.fr
`timeout`	`number`	`30000`	Timeout en millisecondes pour chaque requete HTTP
`tabularPageSize`	`number`	`100`	Nombre maximum de lignes par requete vers l'API Tabular
`disabledSources`	`SourceName[]`	`[]`	Liste des sources a desactiver. Valeurs possibles : `'fhir'`, `'personne-activite'`, `'diplomes'`, `'savoir-faire'`, `'carte-cps'`, `'mssante'`
`headers`	`Record<string, string>`	`{}`	Headers HTTP supplementaires appliques a toutes les requetes

Note : Si fhirApiKey n'est pas fournie, la source 'fhir' est automatiquement ajoutee a disabledSources. Il n'est pas necessaire de la desactiver manuellement.

`client.getByRpps(rpps)`

Recupere le profil complet d'un professionnel de sante a partir de son numero RPPS. Interroge toutes les sources activees en parallele et fusionne les resultats.

const profil = await client.getByRpps('10000001866');

Parametres

Parametre	Type	Description
`rpps`	`string`	Numero RPPS du praticien (exactement 11 chiffres)

Retour : `Promise<RppsFullProfile>`

interface RppsFullProfile {
  rpps: string;                              // Numero RPPS (11 chiffres)
  identificationNationale: string;           // Identification nationale PP (prefixe + RPPS)
  identite: Identite;                        // Civilite, nom, prenom
  profession: Profession;                    // Profession et categorie professionnelle
  activites: Activite[];                     // Structures d'exercice avec adresses
  diplomesEtAutorisations: DiplomeEtAutorisation[]; // Diplomes et autorisations
  savoirFaire: SavoirFaire[];               // Specialites et competences
  cartesCps: CarteCps[];                    // Cartes CPS/CPF
  messageriesMssante: MessagerieMssante[];  // Boites aux lettres MSSante
  fhir: FhirData;                           // Donnees FHIR brutes
  metadata: {
    sources: SourceStatus[];                // Statut de chaque source
    queriedAt: string;                      // Horodatage ISO 8601
    totalDurationMs: number;                // Duree totale en ms
  };
}

Erreurs

Condition	Message
RPPS invalide (pas 11 chiffres)	`Numero RPPS invalide : "xxx". Le RPPS doit contenir exactement 11 chiffres.`

Comportement resilient : si une source echoue (timeout, erreur HTTP), les autres sources retournent leurs resultats normalement. Le champ metadata.sources permet d'identifier les sources en echec.

`client.search(criteria, options?)`

Recherche des praticiens par nom, prenom et/ou code postal. La recherche s'effectue sur la source Personne-Activite via l'API Tabular.

const resultats = await client.search(
  { nom: 'DUPONT', codePostal: '75' },
  { page: 1, pageSize: 20 },
);

Parametres

Parametre	Type	Description
`criteria`	`RppsSearchCriteria`	Criteres de recherche (au moins un champ obligatoire)
`options.page`	`number`	Numero de page (defaut : `1`)
`options.pageSize`	`number`	Nombre de resultats par page (defaut : valeur de `tabularPageSize` du client)

Criteres de recherche

Champ	Type	Operateur	Description
`nom`	`string`	`contains` (insensible a la casse)	Nom d'exercice du praticien (recherche partielle)
`prenom`	`string`	`contains` (insensible a la casse)	Prenom d'exercice (recherche partielle)
`codePostal`	`string`	`exact` si 5 chiffres, `contains` sinon	Code postal de la structure d'exercice

Important : Au moins un critere doit etre fourni, sinon une erreur est levee.

Retour : `Promise<RppsSearchResponse>`

interface RppsSearchResponse {
  results: RppsSearchResult[];  // Resultats dedupliques par RPPS
  total: number;                // Nombre total de resultats cote serveur
  page: number;                 // Page courante
  pageSize: number;             // Taille de page utilisee
  durationMs: number;           // Duree de la requete en ms
  criteria: RppsSearchCriteria; // Criteres utilises
}

interface RppsSearchResult {
  rpps: string;
  identificationNationale: string;
  civilite: string;
  nomExercice: string;
  prenomExercice: string;
  profession: CodeLabel;
  categorieProfessionnelle: CodeLabel;
  modeExercice: CodeLabel;
  savoirFaire: CodeLabel;
  structure: {
    raisonSociale: string;
    codePostal: string;
    libelleCommune: string;
    departement: string;
  };
}

Deduplication : Les resultats sont automatiquement dedupliques par numero RPPS. Un praticien exerCant dans plusieurs structures n'apparait qu'une seule fois (premiere occurrence conservee).

Erreurs

Condition	Message
Aucun critere fourni	`Au moins un critere de recherche est obligatoire (nom, prenom ou codePostal).`

Sources individuelles

Pour un usage avance, chaque source est exportee individuellement. Ces fonctions permettent d'interroger une source specifique sans passer par le client.

`fetchFhirByRpps(rpps, options?)`

Interroge l'API FHIR Annuaire Sante pour obtenir les ressources Practitioner et PractitionerRole.

import { fetchFhirByRpps } from '@qrcommunication/rppsapi';

const fhir = await fetchFhirByRpps('10000001866', {
  headers: { 'ESANTE-API-KEY': 'votre-cle-api' },
});

console.log(fhir.practitioner);       // FhirPractitioner | null
console.log(fhir.practitionerRoles);  // FhirPractitionerRole[]

Parametre	Type	Description
`rpps`	`string`	Numero RPPS
`options.baseUrl`	`string`	URL de base FHIR
`options.timeout`	`number`	Timeout en ms
`options.headers`	`Record<string, string>`	Headers HTTP (doit inclure `ESANTE-API-KEY`)

`fetchPersonneActivite(rpps, options?)`

Recupere l'identite, la profession et les activites (structures d'exercice) d'un praticien.

import { fetchPersonneActivite } from '@qrcommunication/rppsapi';

const result = await fetchPersonneActivite('10000001866');

console.log(result.identite);    // Identite
console.log(result.profession);  // Profession
console.log(result.activites);   // Activite[]

`searchPersonneActivite(criteria, options?)`

Recherche directe dans la source Personne-Activite, avec filtres et pagination.

import { searchPersonneActivite } from '@qrcommunication/rppsapi';

const result = await searchPersonneActivite(
  { nom: 'MARTIN', codePostal: '75015' },
  { pageSize: 50, page: 1 },
);

console.log(result.results);  // RppsSearchResult[]
console.log(result.total);    // number

`fetchDiplomes(rpps, options?)`

Recupere les diplomes obtenus et les autorisations d'exercice.

import { fetchDiplomes } from '@qrcommunication/rppsapi';

const diplomes = await fetchDiplomes('10000001866');
// DiplomeEtAutorisation[]

`fetchSavoirFaire(rpps, options?)`

Recupere les savoir-faire (specialites, competences, qualifications).

import { fetchSavoirFaire } from '@qrcommunication/rppsapi';

const sf = await fetchSavoirFaire('10000001866');
// SavoirFaire[]

`fetchCartesCps(rpps, options?)`

Recupere les cartes CPS et CPF associees au praticien.

import { fetchCartesCps } from '@qrcommunication/rppsapi';

const cartes = await fetchCartesCps('10000001866');
// CarteCps[]

`fetchMssante(rpps, options?)`

Recupere les boites aux lettres MSSante du praticien.

import { fetchMssante } from '@qrcommunication/rppsapi';

const messageries = await fetchMssante('10000001866');
// MessagerieMssante[]

Options communes des sources Tabular

Toutes les fonctions fetchPersonneActivite, fetchDiplomes, fetchSavoirFaire, fetchCartesCps et fetchMssante acceptent les memes options :

Parametre	Type	Defaut	Description
`baseUrl`	`string`	`https://tabular-api.data.gouv.fr/api/resources`	URL de base de l'API Tabular
`timeout`	`number`	`30000`	Timeout en ms
`pageSize`	`number`	`100`	Nombre de lignes par page
`headers`	`Record<string, string>`	`{}`	Headers HTTP supplementaires

`validateRpps(rpps)`

Utilitaire de validation d'un numero RPPS. Verifie que la chaine contient exactement 11 chiffres apres nettoyage des espaces.

import { validateRpps } from '@qrcommunication/rppsapi';

const clean = validateRpps('10000001866');  // '10000001866'
validateRpps('123');                         // throw Error
validateRpps('1234567890A');                 // throw Error

Parametre	Type	Description
`rpps`	`string`	Numero RPPS a valider

Retour : string - Le numero RPPS nettoye (trimmed).

Erreur : Error avec le message Numero RPPS invalide : "xxx". Le RPPS doit contenir exactement 11 chiffres.

Types

Le SDK exporte l'ensemble des interfaces TypeScript necessaires.

RppsFullProfile

Type de retour principal de getByRpps. Voir la section API Reference > getByRpps pour la structure complete.

Identite

Identite civile et d'exercice du praticien.

Champ	Type	Description
`civilite`	`CodeLabel`	Civilite de l'etat civil (ex: `{ code: "M", libelle: "Monsieur" }`)
`civiliteExercice`	`CodeLabel`	Civilite d'exercice (ex: `{ code: "DR", libelle: "Docteur" }`)
`nomExercice`	`string`	Nom d'exercice
`prenomExercice`	`string`	Prenom d'exercice

Profession

Profession exercee et categorie professionnelle.

Champ	Type	Description
`code`	`string`	Code profession (nomenclature ANS)
`libelle`	`string`	Libelle de la profession (ex: `"Medecin"`, `"Pharmacien"`)
`categorie`	`CodeLabel`	Categorie professionnelle (ex: civil, militaire)

Activite

Structure d'exercice et conditions d'activite du praticien.

Champ	Type	Description
`modeExercice`	`CodeLabel`	Mode d'exercice (liberal, salarie, benevole)
`savoirFaire`	`CodeLabel`	Savoir-faire lie a l'activite
`typeSavoirFaire`	`CodeLabel`	Type de savoir-faire (specialite, competence, etc.)
`secteurActivite`	`CodeLabel`	Secteur d'activite (cabinet, hopital, etc.)
`sectionTableauPharmaciens`	`CodeLabel`	Section du tableau de l'Ordre des pharmaciens
`role`	`CodeLabel`	Role dans la structure
`genreActivite`	`CodeLabel`	Genre d'activite
`autoriteEnregistrement`	`string`	Autorite d'enregistrement
`structure`	`Structure`	Structure d'exercice (voir ci-dessous)

Structure

Structure d'exercice (cabinet, etablissement, pharmacie, etc.).

Champ	Type	Description
`identifiantTechnique`	`string`	Identifiant technique de la structure
`raisonSociale`	`string`	Raison sociale du site
`enseigneCommerciale`	`string`	Enseigne commerciale
`numeroSiret`	`string`	Numero SIRET
`numeroSiren`	`string`	Numero SIREN
`numeroFinessSite`	`string`	Numero FINESS du site
`numeroFinessEtablissementJuridique`	`string`	Numero FINESS de l'etablissement juridique
`telephone`	`string`	Telephone principal
`telephone2`	`string`	Telephone secondaire
`telecopie`	`string`	Numero de telecopie (fax)
`email`	`string`	Adresse email
`codeDepartement`	`string`	Code departement
`libelleDepartement`	`string`	Nom du departement
`ancienIdentifiant`	`string`	Ancien identifiant de la structure
`adresse`	`AdresseStructure`	Adresse postale complete

AdresseStructure

Adresse postale d'une structure d'exercice.

Champ	Type	Description
`complementDestinataire`	`string`	Complement destinataire
`complementPointGeographique`	`string`	Complement geographique
`numeroVoie`	`string`	Numero de voie
`indiceRepetitionVoie`	`string`	Indice de repetition (bis, ter, etc.)
`codeTypeVoie`	`string`	Code type de voie
`libelleTypeVoie`	`string`	Libelle du type de voie (rue, avenue, etc.)
`libelleVoie`	`string`	Nom de la voie
`mentionDistribution`	`string`	Mention de distribution
`bureauCedex`	`string`	Bureau cedex
`codePostal`	`string`	Code postal
`codeCommune`	`string`	Code commune INSEE
`libelleCommune`	`string`	Nom de la commune
`codePays`	`string`	Code pays
`libellePays`	`string`	Nom du pays

Diplome et Autorisation

interface DiplomeEtAutorisation {
  diplome: Diplome | null;
  autorisation: Autorisation | null;
}

interface Diplome {
  typeDiplome: CodeLabel;   // Type (ex: certificat, diplome d'Etat)
  diplome: CodeLabel;       // Intitule du diplome
}

interface Autorisation {
  typeAutorisation: CodeLabel;         // Type d'autorisation
  disciplineAutorisation: CodeLabel;   // Discipline autorisee
}

SavoirFaire

Savoir-faire declare d'un praticien.

Champ	Type	Description
`profession`	`CodeLabel`	Profession associee
`categorieProfessionnelle`	`CodeLabel`	Categorie professionnelle
`typeSavoirFaire`	`CodeLabel`	Type (specialite ordinale, competence, etc.)
`savoirFaire`	`CodeLabel`	Intitule du savoir-faire

CarteCps

Carte de professionnel de sante (CPS) ou de professionnel en formation (CPF).

Champ	Type	Description
`typeCarte`	`CodeLabel`	Type de carte (CPS, CPF)
`numeroCarte`	`string`	Numero de la carte
`identifiantNationalCarte`	`string`	Identifiant national contenu dans la carte
`dateDebutValidite`	`string`	Date de debut de validite
`dateFinValidite`	`string`	Date de fin de validite
`dateOpposition`	`string`	Date d'opposition (si opposee)
`dateMiseAJour`	`string`	Date de derniere mise a jour

MessagerieMssante

Boite aux lettres MSSante (Messagerie Securisee de Sante).

Champ	Type	Description
`typeBal`	`string`	Type de BAL (PER = personnelle, ORG = organisationnelle)
`adresseBal`	`string`	Adresse de la boite aux lettres
`dematerialisation`	`boolean`	Si la BAL accepte la dematerialisation
`savoirFaire`	`CodeLabel`	Savoir-faire associe
`structure`	`object`	Structure de rattachement (identifiant, raison sociale, adresse)

FhirData, FhirPractitioner, FhirPractitionerRole

Structures conformes au standard FHIR R4, simplifiees pour l'usage TypeScript.

interface FhirData {
  practitioner: FhirPractitioner | null;
  practitionerRoles: FhirPractitionerRole[];
}

interface FhirPractitioner {
  resourceType: 'Practitioner';
  id?: string;
  identifier?: FhirIdentifier[];
  active?: boolean;
  name?: FhirHumanName[];
  telecom?: Array<{ system?: string; value?: string; use?: string }>;
  qualification?: FhirQualification[];
  [key: string]: unknown;  // Extensions FHIR supplementaires
}

interface FhirPractitionerRole {
  resourceType: 'PractitionerRole';
  id?: string;
  practitioner?: { reference?: string };
  organization?: { reference?: string; display?: string };
  code?: Array<{ coding?: Array<{ system?: string; code?: string; display?: string }> }>;
  specialty?: Array<{ coding?: Array<{ system?: string; code?: string; display?: string }> }>;
  location?: Array<{ reference?: string; display?: string }>;
  [key: string]: unknown;  // Extensions FHIR supplementaires
}

CodeLabel

Paire code/libelle omnipresente dans les donnees RPPS.

interface CodeLabel {
  code: string;
  libelle: string;
}

SourceStatus

Metadonnees de statut pour chaque source interrogee.

Champ	Type	Description
`source`	`SourceName`	Nom de la source (`'fhir'`, `'personne-activite'`, `'diplomes'`, `'savoir-faire'`, `'carte-cps'`, `'mssante'`)
`success`	`boolean`	`true` si la requete a abouti
`rowCount`	`number`	Nombre d'enregistrements retournes
`durationMs`	`number`	Duree de la requete en ms
`error`	`string`	Message d'erreur (si echec) ou `'disabled'` (si source desactivee)

RppsSearchCriteria et RppsSearchResponse

Voir la section API Reference > search pour la documentation complete de ces types.

Exemples avances

Recherche par nom partiel et code postal

import { RppsClient } from '@qrcommunication/rppsapi';

const client = new RppsClient();

// Recherche partielle : tous les "DUPO" dans Paris (75)
const resultats = await client.search(
  { nom: 'DUPO', codePostal: '75' },
  { pageSize: 20 },
);

for (const r of resultats.results) {
  console.log(`${r.civilite} ${r.prenomExercice} ${r.nomExercice}`);
  console.log(`  ${r.profession.libelle} - ${r.structure.libelleCommune}`);
}

Recherche puis profil complet (chaining)

import { RppsClient } from '@qrcommunication/rppsapi';

const client = new RppsClient({
  fhirApiKey: process.env.FHIR_API_KEY,
});

// Etape 1 : chercher le praticien
const recherche = await client.search({ nom: 'SIGNOL', codePostal: '87025' });

if (recherche.results.length > 0) {
  // Etape 2 : recuperer le profil complet du premier resultat
  const rpps = recherche.results[0].rpps;
  const profil = await client.getByRpps(rpps);

  console.log(`${profil.identite.civiliteExercice.libelle} ${profil.identite.prenomExercice} ${profil.identite.nomExercice}`);
  console.log(`Diplomes : ${profil.diplomesEtAutorisations.length}`);
  console.log(`Activites : ${profil.activites.length}`);
  console.log(`Cartes CPS : ${profil.cartesCps.length}`);
}

Desactiver certaines sources

import { RppsClient } from '@qrcommunication/rppsapi';

// Ne recuperer que l'identite et les diplomes
const client = new RppsClient({
  disabledSources: ['savoir-faire', 'carte-cps', 'mssante'],
});

const profil = await client.getByRpps('10000001866');

// Les sources desactivees retournent des tableaux vides
console.log(profil.savoirFaire);        // []
console.log(profil.cartesCps);          // []
console.log(profil.messageriesMssante); // []

// Les metadonnees indiquent "disabled"
for (const s of profil.metadata.sources) {
  if (s.error === 'disabled') {
    console.log(`${s.source} : desactivee`);
  }
}

Gestion d'erreurs

import { RppsClient, validateRpps } from '@qrcommunication/rppsapi';

const client = new RppsClient();

// Valider le RPPS avant l'appel
try {
  validateRpps(inputUtilisateur);
} catch (error) {
  console.error('Numero RPPS invalide :', error.message);
  // Afficher un message a l'utilisateur
}

// Gerer les erreurs de l'appel principal
try {
  const profil = await client.getByRpps('10000001866');

  // Verifier les sources en echec
  const echecs = profil.metadata.sources.filter(s => !s.success);
  if (echecs.length > 0) {
    console.warn('Certaines sources ont echoue :');
    for (const s of echecs) {
      console.warn(`  ${s.source} : ${s.error}`);
    }
  }
} catch (error) {
  // Erreur fatale (RPPS invalide, etc.)
  console.error('Erreur lors de la recuperation :', error.message);
}

Utilisation avec la cle FHIR

import { RppsClient } from '@qrcommunication/rppsapi';

const client = new RppsClient({
  fhirApiKey: process.env.FHIR_API_KEY, // Cle Gravitee
  timeout: 60_000,                       // Timeout plus genereux pour FHIR
});

const profil = await client.getByRpps('10000001866');

// Donnees FHIR disponibles
if (profil.fhir.practitioner) {
  console.log('ID FHIR :', profil.fhir.practitioner.id);
  console.log('Actif :', profil.fhir.practitioner.active);
  console.log('Qualifications :', profil.fhir.practitioner.qualification?.length);
  console.log('Roles :', profil.fhir.practitionerRoles.length);

  for (const role of profil.fhir.practitionerRoles) {
    console.log('  Organisation :', role.organization?.display);
    console.log('  Specialites :', role.specialty?.map(s => s.coding?.[0]?.display).join(', '));
  }
}

Configuration FHIR

La source FHIR interroge l'API officielle de l'Annuaire Sante operee par l'ANS. Elle necessite une cle API gratuite.

Obtenir une cle API

Creer un compte sur le portail Gravitee de l'ANS : https://portal.api.esante.gouv.fr
S'abonner a l'API "Annuaire Sante FHIR"
Generer une cle API dans la section "Subscriptions"
Utiliser cette cle dans le parametre fhirApiKey du client

Variables d'environnement recommandees

# .env
FHIR_API_KEY=votre-cle-gravitee-ici

const client = new RppsClient({
  fhirApiKey: process.env.FHIR_API_KEY,
});

Sans cle FHIR : le SDK fonctionne normalement avec les 5 autres sources. La source FHIR est simplement ignoree et profil.fhir contient { practitioner: null, practitionerRoles: [] }.

Donnees retournees

Structure du profil complet

Lorsque vous appelez getByRpps, le SDK retourne un objet RppsFullProfile dont chaque champ provient d'une source specifique :

Champ	Source	Description
`rpps`	Validation locale	Numero RPPS nettoye (11 chiffres)
`identificationNationale`	Personne-Activite	Identifiant national PP (prefixe type + RPPS, ex: `"810000001866"`)
`identite`	Personne-Activite	Civilite, nom et prenom d'exercice
`profession`	Personne-Activite	Code et libelle de la profession, categorie professionnelle
`activites`	Personne-Activite	Tableau des structures d'exercice avec adresse, mode d'exercice, role et secteur d'activite. Chaque ligne du fichier source correspond a une activite distincte
`diplomesEtAutorisations`	Diplomes	Tableau mixte : chaque entree peut contenir un diplome, une autorisation, ou les deux
`savoirFaire`	Savoir-faire	Specialites, competences et qualifications declarees aupres de l'Ordre
`cartesCps`	Carte CPS	Cartes physiques CPS/CPF avec numeros et dates de validite
`messageriesMssante`	MSSante	Boites aux lettres securisees MSSante avec adresses et structures de rattachement
`fhir`	FHIR ANS	Ressources FHIR R4 brutes : `Practitioner` et `PractitionerRole[]`
`metadata`	Calcul local	Statut de chaque source, horodatage et duree totale

Valeurs par defaut

Si une source echoue ou est desactivee, les champs correspondants prennent des valeurs par defaut :

Type de champ	Valeur par defaut
Tableaux (`activites`, `diplomesEtAutorisations`, etc.)	`[]` (tableau vide)
`identite`	Objet avec des chaines vides et des `CodeLabel` vides
`profession`	Objet avec des chaines vides
`fhir`	`{ practitioner: null, practitionerRoles: [] }`

Performance

Parallelisme

Le SDK interroge toutes les sources activees simultanement via Promise.all. Le temps total d'un appel getByRpps correspond au temps de la source la plus lente, pas a la somme des temps.

Exemple de temps typiques :

Source	Duree moyenne
Personne-Activite	200-500 ms
Diplomes	200-400 ms
Savoir-faire	200-400 ms
Carte CPS	200-400 ms
MSSante	200-400 ms
FHIR	300-800 ms
Total (parallele)	300-800 ms

Pagination automatique

Les sources Tabular gerent automatiquement la pagination. Si un praticien possede plus de lignes que la pageSize configuree, le SDK recupere toutes les pages de maniere transparente.

Optimisation des requetes

Pour reduire le temps de reponse :

Desactiver les sources inutiles via disabledSources
Ajuster le timeout selon votre contexte reseau
Utiliser tabularPageSize eleve si vous attendez beaucoup de resultats par source

Compatibilite

Requirement	Version
Node.js	>= 18.0.0
TypeScript	>= 5.0 (recommande 5.7+)
Format de module	ESM uniquement (`"type": "module"`)

Le SDK utilise l'API fetch native de Node.js (disponible depuis Node 18) et ne depend d'aucune librairie tierce.

Note : Ce package est distribue uniquement en ESM. Si votre projet utilise CommonJS (require), vous devez utiliser un import dynamique : const { RppsClient } = await import('@qrcommunication/rppsapi').

Licence

PolyForm Noncommercial 1.0.0 -- Voir le fichier LICENSE pour les details.

Contribuer

Les contributions sont les bienvenues. Voici les etapes pour participer :

Forker le depot
Creer une branche pour votre fonctionnalite (git checkout -b feature/ma-fonctionnalite)
Ecrire le code et les tests correspondants
Verifier que les tests passent : npm test
Verifier le typage : npm run lint
Soumettre une Pull Request avec une description claire

Commandes de developpement

npm run build       # Compile TypeScript vers dist/
npm run dev         # Compile en mode watch
npm test            # Lance les tests (vitest)
npm run test:watch  # Lance les tests en mode watch
npm run lint        # Verifie le typage (tsc --noEmit)

Structure du projet

@qrcommunication/rppsapi/
  src/
    index.ts              # Exports publics
    client.ts             # Classe RppsClient
    types.ts              # Interfaces et types
    utils.ts              # Utilitaires (fetch, validation, etc.)
    sources/
      fhir.ts             # Source FHIR Annuaire Sante
      personne-activite.ts # Source Personne-Activite
      diplomes.ts         # Source Diplomes & Autorisations
      savoir-faire.ts     # Source Savoir-faire
      carte-cps.ts        # Source Cartes CPS/CPF
      mssante.ts          # Source Messageries MSSante
  examples/
    basic-usage.ts        # Exemple : profil complet
    search.ts             # Exemple : recherche
  dist/                   # Build (genere)
  package.json
  tsconfig.json

Changelog

1.0.0

Publication initiale
6 sources de donnees RPPS (FHIR, Personne-Activite, Diplomes, Savoir-faire, Carte CPS, MSSante)
Methode getByRpps : profil complet par numero RPPS
Methode search : recherche multicritere avec pagination
Sources individuelles exportees pour usage avance
Utilitaire validateRpps
Zero dependance, TypeScript natif, ESM

Skill AI (Claude Code, Cursor, Codex, Windsurf, Gemini...)

Ce SDK inclut un skill AI qui donne a votre agent une connaissance complete du SDK : API, types, sources de donnees, configuration, exemples.

Installation automatique

Le script detecte les agents AI installes et installe le skill automatiquement :

bash node_modules/@qrcommunication/rppsapi/skill/install.sh

Agents supportes : Claude Code, Cursor, Codex, Windsurf, Cline, Aider, Gemini CLI.

Installation manuelle

cp -r node_modules/@qrcommunication/rppsapi/skill ~/.claude/skills/sdk-rpps

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
examples		examples
scripts		scripts
skill		skill
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

@qrcommunication/rppsapi

Table des matieres

Fonctionnalites

Sources de donnees

Installation

Quick Start

API Reference

new RppsClient(options?)

Options de configuration

client.getByRpps(rpps)

Parametres

Retour : Promise<RppsFullProfile>

Erreurs

client.search(criteria, options?)

Parametres

Criteres de recherche

Retour : Promise<RppsSearchResponse>

Erreurs

Sources individuelles

fetchFhirByRpps(rpps, options?)

fetchPersonneActivite(rpps, options?)

searchPersonneActivite(criteria, options?)

fetchDiplomes(rpps, options?)

fetchSavoirFaire(rpps, options?)

fetchCartesCps(rpps, options?)

fetchMssante(rpps, options?)

Options communes des sources Tabular

validateRpps(rpps)

Types

RppsFullProfile

Identite

Profession

Activite

Structure

AdresseStructure

Diplome et Autorisation

SavoirFaire

CarteCps

MessagerieMssante

FhirData, FhirPractitioner, FhirPractitionerRole

CodeLabel

SourceStatus

RppsSearchCriteria et RppsSearchResponse

Exemples avances

Recherche par nom partiel et code postal

Recherche puis profil complet (chaining)

Desactiver certaines sources

Gestion d'erreurs

Utilisation avec la cle FHIR

Configuration FHIR

Obtenir une cle API

Variables d'environnement recommandees

Donnees retournees

Structure du profil complet

Valeurs par defaut

Performance

Parallelisme

Pagination automatique

Optimisation des requetes

Compatibilite

Licence

Contribuer

Commandes de developpement

Structure du projet

Changelog

1.0.0

Skill AI (Claude Code, Cursor, Codex, Windsurf, Gemini...)

Installation automatique

Installation manuelle

About

Resources

Stars

Watchers

Forks

Releases

Packages

`new RppsClient(options?)`

`client.getByRpps(rpps)`

Retour : `Promise<RppsFullProfile>`

`client.search(criteria, options?)`

Retour : `Promise<RppsSearchResponse>`

`fetchFhirByRpps(rpps, options?)`

`fetchPersonneActivite(rpps, options?)`

`searchPersonneActivite(criteria, options?)`

`fetchDiplomes(rpps, options?)`

`fetchSavoirFaire(rpps, options?)`

`fetchCartesCps(rpps, options?)`

`fetchMssante(rpps, options?)`

`validateRpps(rpps)`