Factures

Une facture (Claim, clm_…) est une FSE ou une DRE. Elle se prépare en brouillon, se valide contre les règles, puis se sécurise. Ses prestations (ClaimLine, cli_…) portent le code, la date des soins, la quantité, le coefficient et les montants.

Droits de clé : claims:read et claims:write. Tous les montants sont des entiers, en centimes.

Cycle de vie

État	Sens
`draft`	En cours de saisie, retarifée à chaque modification. Seul état modifiable
`ready`	Droits et tarif validés, en attente de signature
`secured`	Signée
`batched`, `transmitted`	Placée dans un lot, lot envoyé
`acknowledged`	Accusé de réception reçu
`paid`, `partially_paid`	Payée, payée en partie
`rejected`	Rejetée. `rejection_code` dit par qui
`canceled`	Annulée, possible jusqu’à `secured` : une facture mise en lot ne s’annule plus
`adjusted`, `flagged`	Régularisée, signalée. Ces états existent, rien ne les produit encore

Une transition impossible répond 409 conflict.

Je veux…

Je veux…	Appel
Ouvrir un brouillon	`POST /v1/claims`
Changer le contexte d’un brouillon	`PATCH /v1/claims/{id}`
Ajouter une prestation	`POST /v1/claims/{id}/lines`
Corriger une prestation	`PATCH /v1/claims/{id}/lines/{line}`
Retirer une prestation	`DELETE /v1/claims/{id}/lines/{line}`
Savoir ce qui manque	`POST /v1/claims/{id}/validate`
Passer à prête	`POST /v1/claims/{id}/finalize`
Signer	`POST /v1/claims/{id}/secure`
Annuler	`POST /v1/claims/{id}/cancel`
Lire une facture	`GET /v1/claims/{id}`
Lister les factures d’un patient	`GET /v1/claims?patient=pat_…`
Lire sa chronologie	`GET /v1/events?object=clm_…`
Lire les appels qui la visent	`GET /v1/requests?object=clm_…`
Simuler un retour	`POST /v1/test-helpers/claims/{id}/returns`

Le parcours complet, appel par appel : Démarrer en mode test.

Le brouillon

Un brouillon s’enregistre même incomplet : validate dit ce qui manque. Sans coverage ni practice_situation, il prend la dernière lecture de droits du patient et la première situation facturable du praticien.

Contexte d’une facture de médecin

Un médecin dit sous context ce que ni la carte ni les prestations ne portent. Sans sa situation au regard du parcours de soins, ni le lien avec un accident de droit commun, validate le signale sur context.care_pathway et context.common_law_accident.

Champ	Quand	Valeurs
`care_pathway`	toujours, pour un prescripteur	`treating_doctor`, `new_treating_doctor`, `substitute`, `recent_generalist`, `underserved_area`, `away_from_home`, `direct_access`, `outside_direct_access`, `referred_by_treating`, `referred_by_other`, `emergency`, `excluded`, `not_respected`
`treating_doctor_declared`	accès direct, hors résidence, remplacement, orientation	`yes`, `no`, `unknown`
`referring_doctor_last_name`, `referring_doctor_first_name`	patient orienté par un autre médecin	texte
`common_law_accident`	toujours, pour un prescripteur en maladie	booléen
`common_law_accident_date`	si `common_law_accident` vaut `true`	`AAAA-MM-JJ`

Une prescription se lit dans lines[].prescriber. Le cahier des charges en porte une par facture : si les prestations en citent plusieurs différentes, les règles ne la lisent pas.

Prestations

POST, PATCH et DELETE sur /v1/claims/{id}/lines modifient un brouillon et rendent la facture retarifée.

Le tarif se lit à la date des soins, jamais à celle du jour : base_unit_cents. unit_price_cents est le prix demandé, s’il diffère ou s’il n’existe pas de tarif. Le montant vaut prix × coefficient × quantité. referential_versions retient les versions utilisées.

Validation

POST /v1/claims/{id}/validate rend toutes les règles enfreintes d’un coup, sans rien changer :


{
  "object": "claim_validation",
  "claim": "clm_…",
  "valid": false,
  "violations": [
    { "rule": "…", "message": "Les droits lus sont fermés.", "param": "coverage", "line": null }
  ],
  "warnings": []
}

rule identifie la règle, message s’adresse à un humain. line vaut null pour une règle sur la facture entière. warnings a la même forme : la facture peut partir, mais le praticien doit le savoir. Quand un référentiel n’est pas chargé, la règle qui le lit ne juge pas et le dit ici, avec param à referentials. finalize rend la même liste de violations dans une erreur 422 claim_invalid.

Les règles arrivent bloc par bloc : une facture valide ici peut encore être refusée plus tard dans la chaîne.

Certaines règles demandent des informations que la carte du praticien n’a pas : contrat tarifaire, caisse de rattachement, dates d’installation. Elles se renseignent une fois par situation, par une route que cette documentation ne décrit pas encore.

Lister

GET /v1/claims filtre par status, mode, patient, practitioner, fund (le code de la caisse), created[gte] et created[lte]. expand[]=data.patient, data.practitioner et data.coverage déplient ces objets, et déplier un patient laisse une trace de lecture.

Événements

Chaque changement d’état émet exactement un événement claim.<état>, et claim.created ouvre la série. Un événement ne porte ni acte, ni date de soins, ni contexte : des identifiants, l’état et les totaux. Lisez la facture pour le reste. Voir tous les événements claim.*.

Pièges

amount_cents à null n’est pas zéro : une ligne n’a pas encore de prix.
Seul un brouillon se modifie. Pour corriger une facture ready ou secured, annulez-la et rouvrez-en une. Une fois batched, elle ne s’annule plus : la correction passe par une nouvelle facture.
Le dernier mot sur les parts vient du moteur. En mode test, elles viennent d’un taux fictif.
En production, le moteur réel n’est pas raccordé : les écritures répondent 503 engine_unavailable.
Passez une Idempotency-Key à toute création de facture : voir Idempotence.