La référence de l'API, en libre accès.
Tout ce qu'il faut pour intégrer Facturation médicale sans nous écrire : l'authentification, les routes, chaque champ de la facture, les formats rendus, les erreurs et les quotas. L'API n'est pas encore ouverte au public : cette référence est celle du code, pour préparer votre intégration, et la liste d'attente vous prévient de l'ouverture.
Rien de la requête ne survit à la réponse.
Vue d'ensemble #
- URL de base :
https://facturation-medicale.ch. HTTPS obligatoire. - Le principe : une requête porte toutes les données d'une facture, et la réponse est le document, XML, PDF ou les deux. Rien de la requête ne survit à la réponse.
- Standard :
generalInvoiceRequest5.0 du Forum Datenaustausch, schéma du 13.12.2024. Chaque XML est validé contre lui avant d'être rendu. - Deux familles de factures : l'AI en tiers payant (loi IVG, adressée à la Centrale de compensation), et les prestations par convention et complémentaires, LAMal, LCA, LAA ou LAM, en tiers payant ou en tiers garant.
- Les données sont en JSON, en UTF-8.
Bon à savoir. Le serveur ne conserve ni les corps de requête, ni les XML et PDF produits, ni les en-têtes. Si vous avez besoin de retrouver une facture plus tard, c'est à votre logiciel de la garder : nous ne pourrons pas la régénérer sans que vous nous renvoyiez les données.
Bon à savoir. L'API construit la facture ; elle ne la transmet pas. Le XML se dépose dans l'outil de votre intermédiaire de transmission (MediData ou CuraLINE), sous contrat avec vous, qui l'achemine à la Centrale de compensation ou à l'assureur.
Ce que le serveur journalise #
Une ligne par requête : méthode, route (sans paramètres), statut, durée, identifiant du compte, format rendu. Ni corps, ni en-têtes, ni message d'erreur, ni message du validateur.
Un test automatique le vérifie à chaque version : il démarre le vrai serveur sur une base jetable, lui envoie des factures valides, invalides, illisibles et refusées par le schéma qui portent des valeurs reconnaissables (nom, n° AVS, numéro de décision, libellé), puis cherche ces valeurs dans la sortie du serveur, dans la base et sur le disque. Il échoue s'il en trouve une.
Authentification et routes #
Chaque requête authentifiée porte l'en-tête Authorization: Bearer <clé>. La clé se crée dans votre espace client, qui ne l'affiche qu'une fois. Nous n'en gardons que l'empreinte SHA-256 : une clé perdue ne se retrouve pas, elle se révoque et se remplace, depuis le même écran.
Toute clé valide lit ses fournisseurs et les tables publiques, et valide ses factures à blanc (dry_run=1), même sans abonnement : c'est l'essai gratuit, qui laisse brancher toute une intégration avant de payer. La génération d'une facture demande un abonnement actif, à l'un des quatre paliers : sans lui, la requête reçoit 402 abonnement_requis.
Bon à savoir. Rangez la clé dans un gestionnaire de secrets ou une variable d'environnement, jamais dans le code ni dans un dépôt. Les exemples de cette page la lisent dans la variable FACTURATION_CLE.
Les routes #
| Méthode et route | Rôle | Authentification |
|---|---|---|
GET /sante | sonde de santé, sans donnée | non |
GET /v1/fournisseurs | liste les fournisseurs configurés sur votre compte | oui |
GET /v1/offices-ai | la table des 27 offices AI : numéro, canton, GLN, adresse | oui |
GET /v1/tarifs | les codes de tarif du Forum Datenaustausch : code, libellé, lois | oui |
POST /v1/factures | génère une facture et la rend dans le format demandé par Accept | oui |
POST /v1/factures?dry_run=1 | construit la facture et la passe au schéma, sans rien rendre ni décompter | oui |
Les fournisseurs #
Un fournisseur de prestations se configure une fois dans votre espace, et chaque facture le désigne par son identifiant. Cette rubrique dit comment le lire, et pourquoi la requête ne le décrit jamais.
GET /v1/fournisseurs #
Liste les fournisseurs configurés sur votre compte, avec l'identifiant à passer dans chaque facture.
curl -sS https://facturation-medicale.ch/v1/fournisseurs \
-H "Authorization: Bearer $FACTURATION_CLE"
const reponse = await fetch("https://facturation-medicale.ch/v1/fournisseurs", {
headers: { "Authorization": `Bearer ${process.env.FACTURATION_CLE}` },
});
if (!reponse.ok) {
const { erreur } = await reponse.json();
throw new Error(`Refus ${reponse.status} : ${erreur}`);
}
const { fournisseurs } = await reponse.json();
console.log(fournisseurs);
import os
import requests
reponse = requests.get(
"https://facturation-medicale.ch/v1/fournisseurs",
headers={"Authorization": f"Bearer {os.environ['FACTURATION_CLE']}"},
timeout=30,
)
if not reponse.ok:
raise RuntimeError(f"Refus {reponse.status_code} : {reponse.json()['erreur']}")
print(reponse.json()["fournisseurs"])
Réponse 200 :
{
"fournisseurs": [
{ "id": "7f1c9a7e-…", "raisonSociale": "Fournisseur Exemple Sàrl", "gln": "7601000000002" }
]
}
Le fournisseur se désigne, il ne se décrit pas #
La raison sociale, l'adresse structurée, le GLN, le RCC (facultatif), l'IBAN ou le QR-IBAN, le rôle et le lieu, la langue, le motif de traitement par défaut et le n° TVA (facultatif) se saisissent une fois, dans votre espace client. Chaque fournisseur passe par le moteur, sur une facture de pure forme, avant d'être enregistré : un GLN sans sa somme de contrôle, un IBAN étranger ou une raison sociale trop longue pour le standard sont refusés dès la saisie, sous le nom du champ. La requête ne porte que l'identifiant du fournisseur.
Une facture ne peut donc pas sortir au nom d'un fournisseur que votre compte n'a pas déclaré. Avec un QR-IBAN, la QR-facture porte une référence QR ; avec un IBAN ordinaire, une référence RF, calculée de la même façon depuis le numéro de facture.
Générer une facture #
Une requête POST /v1/factures porte toutes les données d'une facture, et la réponse est le document. Les champs, ce que le moteur calcule, puis deux exemples complets à rejouer.
POST /v1/factures : le corps #
Content-Type: application/json, 256 Ko au plus. Les champs marqués « oui » sont obligatoires ; les autres peuvent être omis.
| Champ | Type | Obligatoire | Règle |
|---|---|---|---|
fournisseur | texte | oui | identifiant d'un fournisseur de votre compte |
mode | texte | non | tiersPayant (par défaut, et imposé avec assureur.officeAi) ou tiersGarant |
loi | texte | selon le cas | IVG, imposée avec assureur.officeAi ; sinon obligatoire, parmi KVG, VVG, UVG, MVG, ORG |
facture.numero | texte | oui | 35 caractères au plus, avec au moins un chiffre : la référence QR en est tirée |
facture.date | date | non | AAAA-MM-JJ ; par défaut, la date du jour à l'heure suisse |
facture.langue | texte | non | fr, de ou it ; par défaut, celle du fournisseur |
facture.sousType | texte | non | normale (par défaut), copie ou storno ; un storno porte ses quantités en négatif |
assure.nom, assure.prenom | texte | oui | 35 caractères chacun |
assure.sexe | texte | oui | f ou m ; d accepté avec assure.sexeLegal |
assure.dateNaissance | date | oui | AAAA-MM-JJ |
assure.noAvs | texte | oui | 756 suivi de dix chiffres, points admis ; somme de contrôle vérifiée, rendu sur 13 chiffres sans points |
assure.adresse | objet | oui | rue, numero, npa, localite, pays (CH par défaut) ; rue et localité 35 caractères |
assure.noAssure | texte | non | le numéro d'assuré chez l'assureur (LAMal, LCA), 35 caractères |
garant | objet | non | une autre personne ou une entreprise qui répond de la facture (parent, employeur) ; le patient par défaut |
assureur.officeAi | texte | l'un des deux | le numéro à trois chiffres d'un office AI de la table ; son GLN et son adresse en sont tirés |
assureur.gln, .nom, .adresse | objet | l'un des deux | tout autre assureur : GLN à 13 chiffres avec sa somme de contrôle, raison sociale 35 caractères ; facultatif en tiers garant |
decision.numero | texte | oui avec officeAi | 14 chiffres dont les trois premiers sont ceux de l'office, ou 6 chiffres IVS280 pour une mesure d'instruction |
decision.date | date | non | AAAA-MM-JJ |
sinistre.numero, sinistre.date | texte, date | non | pour UVG et MVG : le numéro de sinistre de l'assureur, 35 caractères |
traitement.debut, traitement.fin | date | oui | AAAA-MM-JJ, la fin après le début, chaque prestation dans la période |
traitement.canton | texte | oui | code à deux lettres |
traitement.motif | texte | non | disease, accident, birthdefect, maternity, prevention, unknown ; par défaut, celui du fournisseur |
prestations[] | liste | oui | au moins une ligne |
prestations[].tarif | texte | oui | trois caractères, présent et actif dans la table des tarifs, et valable pour la loi |
prestations[].code | texte | oui | 30 caractères ; le code de votre convention, sans validation tarifaire |
prestations[].libelle | texte | oui | 350 caractères |
prestations[].quantite | nombre | oui | décimales permises ; négatif seulement en storno |
prestations[].prixUnitaire | nombre | oui | en francs ; le montant est la quantité multipliée par le prix, arrondie au centime |
prestations[].dateDebut, .dateFin | date | début oui | dans la période de traitement |
prestations[].tauxTva | nombre | non | 0 par défaut ; 2.6, 3.8 et 8.1 acceptés |
prestations[].remarque, remarque | texte | non | 350 caractères |
Ce que le moteur calcule #
- Le destinataire : la Centrale de compensation (GLN
7601003002751) pour l'AI, sinon l'assureur en tiers payant, ou le fournisseur lui-même en tiers garant (le document est remis au patient). - Les montants de chaque ligne, le total, la TVA par taux rencontré, arrondis au centime.
- La référence QR (27 chiffres) ou RF de la QR-facture, depuis les chiffres du numéro de facture.
- L'identifiant unique de la requête et sa date, dans le format du standard.
Bon à savoir. Le moteur vérifie la forme, pas les tarifs : le code de tarif doit exister dans la liste du Forum et s'appliquer à la loi, les codes de prestation sont ceux de votre convention, et vous en répondez. Une valeur que le standard ne peut pas porter arrête la génération plutôt que d'être tronquée ; le refus 422 liste tous les champs en cause d'un coup.
Exemple : une mesure AI #
Données fictives, à enregistrer dans facture.json pour les appels qui suivent : une mesure de réadaptation professionnelle facturée à l'office AI du canton de Vaud, en tiers payant. L'identifiant de fournisseur est celui que rendGET /v1/fournisseurs sur votre compte.
{
"fournisseur": "7f1c9a7e-…",
"facture": { "numero": "2026-0412", "date": "2026-12-20", "langue": "fr" },
"assure": {
"nom": "Exemple", "prenom": "Zoé", "sexe": "f", "dateNaissance": "1990-05-12",
"noAvs": "756.1234.5678.97",
"adresse": { "rue": "Rue du Test", "numero": "1", "npa": "1000", "localite": "Lausanne" }
},
"assureur": { "officeAi": "322" },
"decision": { "numero": "32220260001234", "date": "2026-02-10" },
"traitement": { "debut": "2026-09-01", "fin": "2026-12-19", "canton": "VD" },
"prestations": [
{ "tarif": "908", "code": "COACH", "libelle": "Coaching individuel", "quantite": 12, "prixUnitaire": 150.00, "dateDebut": "2026-09-01", "dateFin": "2026-12-19" },
{ "tarif": "908", "code": "SOUT", "libelle": "Soutien spécifique", "quantite": 6, "prixUnitaire": 120.00, "dateDebut": "2026-09-01", "dateFin": "2026-12-19" },
{ "tarif": "908", "code": "ADMIN", "libelle": "Administration", "quantite": 1, "prixUnitaire": 80.00, "dateDebut": "2026-12-19" }
],
"remarque": "Mesure selon décision du 10.02.2026"
}
Exemple : une thérapie en tiers garant #
La même API, pour une séance de thérapie complémentaire que le patient paie et se fait rembourser par son assurance complémentaire (loi LCA, tarif 590). Le PDF rendu est la facture au patient et son justificatif de remboursement.
{
"fournisseur": "7f1c9a7e-…",
"facture": { "numero": "2026-0413", "date": "2026-12-20" },
"mode": "tiersGarant",
"loi": "VVG",
"assure": {
"nom": "Exemple", "prenom": "Zoé", "sexe": "f", "dateNaissance": "1990-05-12",
"noAvs": "756.1234.5678.97",
"adresse": { "rue": "Rue du Test", "numero": "1", "npa": "1000", "localite": "Lausanne" }
},
"traitement": { "debut": "2026-12-01", "fin": "2026-12-15", "canton": "VD" },
"prestations": [
{ "tarif": "590", "code": "1200", "libelle": "Massage classique, 60 min", "quantite": 2, "prixUnitaire": 130.00, "dateDebut": "2026-12-01", "dateFin": "2026-12-15" }
]
}
Les appels #
D'abord une validation à blanc, qui construit la facture et la passe au schéma sans rien rendre ni décompter, puis la génération. La clé est lue dans la variable d'environnement FACTURATION_CLE. En cas de 422, la liste champsnomme chaque champ refusé et sa raison.
# 1. Validation à blanc : le XML est construit et passé au schéma 5.0, rien n'est rendu ni décompté.
curl -sS -X POST "https://facturation-medicale.ch/v1/factures?dry_run=1" \
-H "Authorization: Bearer $FACTURATION_CLE" -H "Content-Type: application/json" \
--data-binary @facture.json
# 2. Génération : le XML 5.0 validé, pour l'intermédiaire de transmission.
curl -sS -X POST https://facturation-medicale.ch/v1/factures \
-H "Authorization: Bearer $FACTURATION_CLE" -H "Content-Type: application/json" \
-H "Accept: application/xml" --data-binary @facture.json -o facture.xml
# 3. Ou le XML et le PDF avec sa QR-facture, ensemble dans un zip.
curl -sS -X POST https://facturation-medicale.ch/v1/factures \
-H "Authorization: Bearer $FACTURATION_CLE" -H "Content-Type: application/json" \
-H "Accept: application/zip" --data-binary @facture.json -o facture.zip
import { readFile, writeFile } from "node:fs/promises";
const URL_BASE = "https://facturation-medicale.ch/v1/factures";
const corps = await readFile("facture.json", "utf8");
async function appeler({ validationABlanc = false, format = "application/xml" } = {}) {
const url = validationABlanc ? `${URL_BASE}?dry_run=1` : URL_BASE;
const reponse = await fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.FACTURATION_CLE}`,
"Content-Type": "application/json",
"Accept": format,
},
body: corps,
});
if (reponse.status === 422) {
const { erreur, champs = [] } = await reponse.json();
for (const { champ, raison } of champs) console.error(`${champ} : ${raison}`);
throw new Error(erreur);
}
if (!reponse.ok) {
const { erreur } = await reponse.json();
throw new Error(`Refus ${reponse.status} : ${erreur}`);
}
return reponse;
}
// 1. Validation à blanc : le XML est construit et passé au schéma, rien n'est rendu ni décompté.
console.log(await (await appeler({ validationABlanc: true })).json());
// { valide: true, destinataire: "7601003002751", montant: 2600 }
// 2. Génération : le XML 5.0 validé. Le statut est vérifié avant d'écrire le fichier.
const reponse = await appeler({ format: "application/xml" });
await writeFile("facture.xml", Buffer.from(await reponse.arrayBuffer()));
console.log("Quota restant :", reponse.headers.get("Factures-Quota-Restant"));
// 3. Le PDF avec sa QR-facture, depuis la même facture.
const pdf = await appeler({ format: "application/pdf" });
await writeFile("facture.pdf", Buffer.from(await pdf.arrayBuffer()));
import os
import sys
import requests
URL = "https://facturation-medicale.ch/v1/factures"
with open("facture.json", "rb") as fichier:
corps = fichier.read()
def appeler(validation_a_blanc: bool = False, format: str = "application/xml") -> requests.Response:
params = {"dry_run": "1"} if validation_a_blanc else None
entetes = {
"Authorization": f"Bearer {os.environ['FACTURATION_CLE']}",
"Content-Type": "application/json",
"Accept": format,
}
reponse = requests.post(URL, headers=entetes, data=corps, params=params, timeout=60)
if reponse.status_code == 422:
for champ in reponse.json().get("champs", []):
print(f"{champ['champ']} : {champ['raison']}", file=sys.stderr)
sys.exit(1)
if not reponse.ok:
raise RuntimeError(f"Refus {reponse.status_code} : {reponse.json()['erreur']}")
return reponse
# 1. Validation à blanc : le XML est construit et passé au schéma, rien n'est rendu ni décompté.
print(appeler(validation_a_blanc=True).json())
# {'valide': True, 'destinataire': '7601003002751', 'montant': 2600}
# 2. Génération : le XML 5.0 validé. Le statut est vérifié avant d'écrire le fichier.
reponse = appeler(format="application/xml")
with open("facture.xml", "wb") as fichier:
fichier.write(reponse.content)
print("Quota restant :", reponse.headers.get("Factures-Quota-Restant"))
# 3. Le PDF avec sa QR-facture, depuis la même facture.
with open("facture.pdf", "wb") as fichier:
fichier.write(appeler(format="application/pdf").content)
Réponse, erreurs et quotas #
Les formats #
En génération, 200 et le document dans le format que demande l'en-tête Accept. Le XML et le PDF sont produits de la même facture normalisée : ce que le PDF affiche est ce que le XML porte.
Accept | Rendu | Nom de fichier |
|---|---|---|
application/xml (par défaut) | le XML 5.0 validé, en UTF-8 | Facture 2026-0412.xml |
application/pdf | la facture lisible avec la QR-facture en pied ; en tiers garant, la facture au patient et son justificatif de remboursement | Facture 2026-0412.pdf |
application/zip | les deux fichiers ci-dessus, dans un zip | Facture 2026-0412.zip |
Les en-têtes #
| En-tête | Valeur |
|---|---|
Content-Type | le format rendu |
Content-Disposition | attachment; filename="Facture 2026-0412.xml" : le nom de fichier Facture <numéro>, suivi de son extension |
Cache-Control | no-store |
Factures-Quota-Restant | le nombre de factures encore possibles ce mois |
En validation à blanc (dry_run=1) : 200 et le corps suivant, avec le GLN du destinataire et le montant total, sans document et sans décompte.
{ "valide": true, "destinataire": "7601003002751", "montant": 2600 }
Les erreurs #
Toujours en JSON, sous la forme { "erreur": "<code>" }. Jamais une valeur reçue dans la réponse.
| Statut | erreur | Quand |
|---|---|---|
| 400 | json_illisible | le corps n'est pas du JSON |
| 401 | cle_invalide | clé absente, inconnue ou révoquée |
| 402 | abonnement_requis | génération demandée sans abonnement actif ; la validation à blanc reste ouverte |
| 404 | fournisseur_inconnu | l'identifiant ne désigne aucun fournisseur du compte |
| 404 | route_inconnue | la route n'existe pas |
| 405 | methode_non_acceptee | méthode non prévue sur cette route |
| 406 | format_non_disponible | Accept ne demande ni XML, ni PDF, ni zip |
| 413 | corps_trop_gros | plus de 256 Ko |
| 415 | type_non_accepte | autre chose que application/json |
| 422 | facture_invalide | une ou plusieurs valeurs refusées ; champs les liste toutes |
| 422 | schema_refuse | le XML construit ne passe pas le schéma ; details porte les messages du validateur, expurgés des valeurs |
| 429 | quota_atteint | le quota du mois est épuisé |
| 500 | erreur_interne | tout le reste, sans détail |
Exemple de 422, tel que le moteur le rend :
{
"erreur": "facture_invalide",
"champs": [
{ "champ": "assure.noAvs", "raison": "un numéro AVS à 13 chiffres commençant par 756, avec sa somme de contrôle" },
{ "champ": "decision.numero", "raison": "les trois premiers chiffres doivent être ceux de l'office AI de la facture" }
]
}
Bon à savoir. La raison décrit la règle, jamais la valeur reçue. Vous pouvez donc l'afficher ou la journaliser telle quelle de votre côté sans faire sortir une donnée de patient.
Les quotas #
Une facture générée compte une unité sur le mois civil, à l'heure suisse, quel que soit son format. Une validation à blanc, un refus ou une erreur ne comptent pas. Le décompte est atomique : deux requêtes simultanées à la limite ne peuvent pas la dépasser toutes les deux.
Le quota dépend du palier : 10, 50, 250 ou 2 000 factures par mois, et se relève en changeant de palier depuis votre espace ; au-delà, un plan personnalisé. Quand il est atteint, la requête reçoit 429 quota_atteint jusqu'au mois suivant. L'en-têteFactures-Quota-Restant de chaque réponse vous permet de le voir venir.
Depuis un agent : le serveur MCP #
Un assistant (Claude, ou l'agent de votre propre outil) peut produire la facture par des outils plutôt que par des requêtes HTTP : Facturation médicale est aussi un serveur MCP, à l'adressehttps://facturation-medicale.ch/mcp (transport Streamable HTTP), authentifié par la même clé que l'API, dans l'en-têteAuthorization: Bearer <clé>. Avec Claude Code, par exemple :
claude mcp add --transport http facturation-medicale https://facturation-medicale.ch/mcp \
--header "Authorization: Bearer $FACTURATION_CLE"Les outils #
| Outil | Ce qu'il rend |
|---|---|
lister_fournisseurs | les fournisseurs de votre compte, avec l'identifiant qu'attend le champ fournisseur |
lister_offices_ai | la table des 27 offices AI : numéro à trois chiffres, canton, GLN, adresse |
decrire_facture | les champs, les lois, les modes et les règles de la facture, pour que l'agent sache la remplir |
valider_facture | l'équivalent de dry_run=1 : contrôle complet, schéma compris, rien de rendu, rien de décompté |
generer_facture | le XML 5.0 validé, dans la réponse, en clair : il pèse quelques kilo-octets, et rien ne reste sur le serveur |
Le serveur MCP est posé sur l'API, dans le même processus : les arguments des outils sont le corps de POST /v1/factures, les refus sont ceux de l'API (erreur et champs, jamais une valeur reçue), le quota est le même, et rien de ce qu'un appel porte ne survit à sa réponse. Sans abonnement, l'agent peut lister, décrire et valider ; la génération demande un abonnement, comme par l'API.
Bonnes pratiques #
- Validez en
dry_run=1pendant l'intégration : chaque règle et le schéma sont contrôlés, rien n'est décompté. - Ne journalisez pas vous-même les corps de requête : la promesse « rien ne reste » vaut aussi de votre côté.
- Gardez le XML rendu : c'est lui que votre intermédiaire transmet, et nous ne pouvons pas le régénérer sans vos données.
- Donnez à chaque facture un numéro unique chez vous : le serveur ne le vérifie pas, puisqu'il ne garde rien.
- Pour annuler une facture déjà transmise, générez-la de nouveau en
storno, avec ses quantités en négatif. - Gardez la clé hors du code et des dépôts. Une clé exposée se révoque dans votre espace, et une autre la remplace aussitôt.
- Créez une clé par usage (production, essais, outil d'automatisation) : vous révoquez l'une sans couper les autres.