Lots et fichiers

Vous ne constituez pas les lots : Ophelix le fait. Une facture sécurisée attend l’heure d’envoi de son praticien, puis part dans un lot (Batch, bat_…) avec celles qui vont au même endroit. Les lots d’un même envoi pour une même caisse partent dans un fichier (Transmission, trm_…). La caisse répond à chaque lot par un accusé de réception.

Droits de clé : batches:read et batches:write. Un lot ne porte ni acte ni patient : ses critères, son numéro, ses totaux et son accusé.

Cycle de vie

État	Sens
`created`	Lot constitué et signé, pas encore parti. Il repart au passage suivant si l’envoi échoue
`sent`	Parti dans un fichier, en attente de l’accusé de réception
`acknowledged`	Accusé positif : la caisse a pris le lot
`failed`	Accusé négatif : la caisse ne l’a pas pris. `failure_code` et `failure_label` disent pourquoi

Ses factures suivent : batched à la constitution, transmitted à l’envoi, acknowledged à l’accusé positif. Un accusé négatif ne rejette que la facture qu’il désigne : voir Retours des caisses.

Je veux…

Je veux…	Appel
Savoir ce qui partira au prochain envoi	`GET /v1/batches/upcoming`
Envoyer tout de suite, sans attendre l’heure	`POST /v1/batches/send`
Régler l’heure d’envoi d’un praticien	`PATCH /v1/practitioners/{id}`
Lister les lots refusés	`GET /v1/batches?status=failed`
Lire un lot	`GET /v1/batches/{id}`
Lister les factures d’un lot	`GET /v1/claims?batch=bat_…`
Trouver le lot d’une facture	`GET /v1/claims/{id}?expand[]=batch`
Lire un fichier envoyé	`GET /v1/transmissions/{id}`
Reconstituer un lot refusé	`POST /v1/batches/{id}/rebuild`
Lire les accusés d’un lot	`GET /v1/acknowledgments?batch=bat_…`
Simuler un accusé	`POST /v1/test-helpers/batches/{id}/acknowledgment`

L’heure d’envoi

Chaque praticien a son heure, batch_cutoff, à l’heure de Paris : 19:00 par défaut. Une facture sécurisée avant cette heure part le jour même, une facture sécurisée après part le lendemain. Le planificateur passe chaque minute : un lot se forme dans la minute qui suit l’heure.


curl -X PATCH https://api.ophelix.fr/v1/practitioners/prac_… \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"batch_cutoff": "12:30"}'

null reprend l’heure par défaut.

Comment les factures se regroupent

Un lot réunit les factures d’une même situation de facturation qui partagent :

le type de facture, FSE ou DRE ;
le régime et la caisse de l’organisme destinataire ;
le destinataire du règlement : tiers payant ou non ;
le mode de sécurisation : secured, degraded ou sesam_sans_vitale ;
le mode, test ou production.

Le numéro d’un lot va de 001 à 999 pour la FSE et de AAA à ZZZ pour la DRE, par situation de facturation, puis repart au début. Un fichier se numérote sans trou dans son mode.

Sans carte Vitale

Une feuille dégradée (mode: degraded) ne se met en lot qu’avec d’autres feuilles dégradées : le critère que rendent les services SESAM-Vitale porte le mode. L’organisme n’accuse pas réception d’un lot de FSE dégradées : il reste sent, acknowledgment_expected vaut false, acknowledgment_due_at reste null, et il n’est jamais en retard. Ses factures restent transmitted jusqu’à leur paiement.

Événements

batch.created à la constitution, batch.sent à l’envoi, puis batch.acknowledged ou batch.failed, et batch.overdue si l’accusé tarde plus de 48 heures. Chaque facture du lot émet en plus son propre claim.<état>. Écoutez batch.failed pour savoir qu’un lot est à reconstituer.

En mode test

Le simulateur signe et envoie : aucune caisse n’est jointe. L’accusé ne vient pas seul : déclenchez-le sur un lot sent avec arl_positive ou arl_negative. Le simulateur écrit alors le fichier d’accusés de la caisse, qui suit le chemin d’un fichier déposé. Voir Cartes et scénarios de test.

Pièges

Une facture secured n’est pas encore partie. Elle s’annule encore ; une fois en lot, plus.
Un accusé porte sur tout le lot. Négatif, il fait échouer le lot ; seule la facture que son code désigne passe à rejected, avec rejection_code à arl_negative. Les autres attendent la reconstitution.
Un lot de feuilles dégradées n’a pas d’accusé. N’attendez pas batch.acknowledged : acknowledgment_expected le dit.
Un lot ne se reconstitue qu’une fois. Refusé à nouveau, ses factures passent à rejected et se réémettent une à une.
En production, le moteur réel n’est pas raccordé : aucun lot ne se forme, et POST /v1/batches/send répond 503 engine_unavailable dès qu’une facture attend.