Retours des caisses

Deux retours répondent à ce qui part :

l’accusé de réception (Acknowledgment, ack_…), par lot : la caisse a pris le lot, ou le refuse avec un code ;
le retour de paiement (Remittance, rem_…), un fichier par envoi de la caisse, au format NOEMIE 580. Il devient des paiements (Payment, pay_…) et des rejets (Rejection, rej_…), chacun rapproché de sa facture.

Droits de clé : batches:read et batches:write, comme les lots.

Aucune boîte aux lettres n’est encore raccordée : un fichier reçu se dépose par l’API, et le simulateur produit les retours en mode test. Les deux passent par le même chemin.

Je veux…

Je veux…	Appel
Déposer un fichier d’accusés	`POST /v1/acknowledgments`
Lister les accusés qu’aucun lot n’attendait	`GET /v1/acknowledgments?matched=false`
Reconstituer un lot refusé	`POST /v1/batches/{id}/rebuild`
Déposer un fichier de retours de paiement	`POST /v1/remittances`
Voir les écarts d’un fichier	`GET /v1/remittances/{id}`
Lister ce qu’une facture a reçu	`GET /v1/payments?claim=clm_…`
Lister les rejets d’une facture	`GET /v1/rejections?claim=clm_…`
Trouver ce qui attend un rapprochement	`GET /v1/payments?matched=false`, `GET /v1/rejections?matched=false`
Rattacher un retour à sa facture à la main	`POST /v1/rejections/{id}/match`
Corriger et réémettre une facture rejetée	`POST /v1/claims/{id}/reissue`
Simuler un retour	`POST /v1/test-helpers/claims/{id}/returns`
Retrouver le virement d’un paiement sur le relevé	Voir Virements et relevés

Accusés de réception

Un fichier déposé est traduit, puis chaque accusé se rattache au lot envoyé qu’il désigne : même émetteur (le numéro de facturation de la situation), même numéro de lot, même caisse, même date de lot. Un accusé qu’aucun lot sent n’attend est gardé, matched à false, pour analyse.

Positif : le lot passe à acknowledged, ses factures aussi.
Négatif : le lot passe à failed. failure_code et failure_label portent le code et le libellé de la caisse. Quand le code désigne une facture, son numéro ouvre le libellé : cette facture seule passe à rejected, avec un rejet de source acknowledgment. Les autres restent transmitted.

Un lot refusé ne repart pas seul : POST /v1/batches/{id}/rebuild forme un nouveau lot, avec un nouveau numéro, les mêmes factures sauf la facture désignée, et le marque retransmission. Il part au prochain passage. Un lot reconstitué ne se reconstitue pas : refusé à son tour, ses factures passent à rejected.

Un lot envoyé sans accusé 48 heures plus tard est signalé : overdue_at se remplit et batch.overdue part une fois. acknowledgment_due_at dit l’échéance.

La traduction passe par le moteur SESAM-Vitale : en production, tant qu’il n’est pas raccordé, POST /v1/acknowledgments répond 503 engine_unavailable.

Retours de paiement

POST /v1/remittances lit un fichier NOEMIE 580 et le rapproche aussitôt. La lecture ne demande pas le moteur : elle marche en production.

Chaque retour du fichier est de l’un de ces types :

Type	Ce qu’il dit	Ce qu’il devient
`01`	Le traitement d’une facture	Un paiement par part payée, un rejet par motif de part rejetée ou différée
`02`	La suite d’une part différée, ou une feuille papier	Rapproché par le numéro de facture seul
`03`	Un paiement ponctuel, sans facture	Un paiement `one_off_payment`
`04`, `05`	Une régularisation, ou une retenue sans facture	Des paiements `regularization`, ou `one_off_deduction`

Une facture se retrouve par son numéro (number, attribué à la signature), sa date, le numéro de facturation du praticien et son type. Elle prend alors l’état que donnent ses parts obligatoire et complémentaire :

Parts	Facture
Toutes payées, en entier	`paid`
Payées, l’une moins que demandé	`partially_paid`
Une rejetée, tous les retours arrivés	`rejected`, `rejection_code` à `rejected_by_fund`
Une différée, ou une attendue	Reste où elle est : un second retour viendra
Régularisée après paiement ou rejet	`adjusted`, `regularized_at` rempli

returns.amo et returns.amc disent l’état de chaque part. paid_amount_cents est la somme signée de ses paiements, régularisations comprises.

Rien ne se perd

Un retour de facture que rien ne reconnaît reste dans le fichier : ses paiements et ses rejets ont claim à null et matched à false, et gardent l’assuré et le bénéficiaire lus dans le retour, pour retrouver la facture. POST /v1/payments/{id}/match ou POST /v1/rejections/{id}/match, avec {"claim": "clm_…"}, rattache tout le retour à la facture, qui prend aussitôt son état.

discrepancies liste ce qui reste à voir dans un fichier :

`type`	Écart
`unmatched`	Un retour de facture sans facture
`underpaid`	Une facture payée moins que demandé
`total_mismatch`	Un virement dont le total annoncé ne tombe pas juste
`unknown_return`	Un type de retour inconnu

Paiements

Un paiement porte son virement : transfer.label le retrouve sur le relevé du praticien, transfer.accounting_date et transfer.payer disent quand et qui. Il appartient à un virement (payout), qui se rapproche du relevé : voir Virements et relevés.

Rejets

Un rejet garde le code et le libellé tels que la caisse les donne, et reason, le même libellé rendu lisible. Ophelix n’invente pas de motif. level dit s’il vise la facture, une prestation (claim_line) ou un code affiné. status vaut deferred quand la caisse n’a pas fini : la facture attend alors son second retour.

editable dit ce que la correction peut changer : coverage et context pour un rejet de la facture, lines pour un rejet de prestation, complementary pour la part complémentaire, rien pour un accusé (la facture se signe à nouveau) ou une part différée.

Corriger et réémettre

POST /v1/claims/{id}/reissue, sur une facture rejected, ouvre une copie en brouillon : mêmes prestations, même contexte, replaces vers l’original et editable repris de ses rejets. Corrigez-la, puis validez et signez comme une facture neuve : elle prend un nouveau numéro, et l’original passe à reissued. replaced_by et reissue_chain suivent la chaîne, de la première facture à la dernière.

Une facture n’a qu’une copie vivante : annulez la copie pour en refaire une.

Événements

batch.acknowledged, batch.failed et batch.overdue pour les accusés ; remittance.received par fichier de retours, avec ses comptes ; puis claim.paid, claim.partially_paid, claim.rejected, claim.adjusted et claim.reissued sur chaque facture. Aucun ne porte de patient ni d’acte.

En mode test

Les retours simulés d’une facture écrivent le fichier que la caisse aurait envoyé, qui suit le chemin d’un fichier déposé : voir Cartes et scénarios de test.

Pièges

Un fichier illisible n’enregistre rien : 422 return_file_unreadable, avec la ligne qui bloque.
Un retour peut arriver avant l’accusé. Une facture transmitted peut passer directement à paid.
Une part différée n’est pas un rejet. N’en tirez rien avant le second retour.
Seule une facture rejected se réémet, et elle ne se modifie pas : on corrige la copie.