Réviser les lignes et les soldes d'un relevé

PATCH 
/api/v1/bank_statements/:id/lines

Corrige les lignes extraites et, dans le MÊME appel, les deux soldes du relevé - il n'existe pas de PATCH /bank_statements/{id}, et corriger un solde est le même acte de révision que corriger une ligne. La soumission est atomique : un seul chiffre mal formé refuse l'ensemble et n'écrit rien, si bien que vous ne vous retrouvez jamais avec un relevé à moitié modifié derrière un 422.

La réponse porte les lignes révisées, paginées comme sur le GET, plus un meta qui transporte les soldes du relevé et reconciliation_errors - un avertissement sur un 200, qui vous dit que le relevé ne s'équilibre plus alors même que la correction a été appliquée.

Les états qui acceptent une révision : completed, partial et reviewing - l'extraction est terminée et le fichier est encore ouvert. posted ne l'accepte pas : la comptabilisation est faite, et corriger une ligne ensuite invaliderait une écriture comptable qui existe déjà. pending, processing, failed et archived ne sont pas révisables non plus, et pour quatre raisons différentes. pending signifie seulement que le fichier est stocké et pas encore révisable - jamais qu'une extraction soit en cours ; processing est le seul état qui, lui, signifie que le travail tourne. failed peut encore PORTER les lignes d'une passe antérieure - une relance les conserve, et un échec ultérieur ne les supprime pas -, si bien que GET /bank_statements/{id}/lines les sert toujours, mais elles ne peuvent pas être corrigées tant qu'une extraction réussie n'a pas ramené le fichier à completed ou partial. archived a été conservé sans qu'aucune extraction ne tourne : il n'a rien à réviser, et n'aura jamais rien. Tout état hors des trois états acceptés est refusé par statement_not_reviewable.

Dans un état accepté, les deux corrections sont autorisées sans restriction : n'importe laquelle des lignes du relevé qui n'est pas déjà réconciliée ou passée en comptabilité, et l'un comme l'autre des deux soldes. Ouvrir la révision (reviewing) ne restreint rien - cela enregistre qu'un humain a le fichier en main, et les corrections suivantes sont toujours prises.

Request

Responses

200

The corrections were applied. The reviewed lines come back paginated, with the statement's balances and a freshly recomputed reconciliation_errors alongside them.

400

The page query parameter is not an integer greater than or equal to 1, or it names a page beyond the statement's last one. NOTHING was corrected - the page is answered before the review is applied, so this is safe to resend with a valid page.

401

La requête ne porte aucun jeton bearer, ou en porte un qui est invalide ou expiré. doorkeeper_authorize! est le premier contrôle de la chaîne, si bien que la réponse est rendue avant que l'espace de travail, l'entreprise, le drapeau de fonctionnalité et le relevé ne soient résolus - et avant qu'une Idempotency-Key ne soit revendiquée.

403

Le jeton n'est pas autorisé à effectuer cet appel, et trois contrôles de la chaîne partagée y répondent de manière identique : le SCOPE OAuth déduit du verbe HTTP (celui-ci exige write), l'HABILITATION que l'application détient sur l'espace de travail, et le DRAPEAU DE FONCTIONNALITÉ bank_reconciliation. Le contrôle Pundit propre à l'action en est un quatrième. Les quatre rendent le même corps, message est donc le seul élément qui les distingue ; dans tous les cas, rien n'a été effectué. L'exemple ci-dessous est refusé sur le scope.

404

No statement with this id is reachable by the token's grants, so nothing was corrected. One belonging to another workspace answers the same way, so the response cannot be used to probe for one.

409

You sent the optional Idempotency-Key and it was already used for a DIFFERENT review body - idempotency_key_reuse. Nothing was corrected by this call. This is the conflict the review can actually produce, because unlike the delete it carries a body: two submissions under one key are two different corrections, and the platform refuses rather than guessing which you meant. Send a fresh key, or resend the ORIGINAL body to replay the stored 200. A first call still in flight answers the same status with idempotency_request_in_progress.

422

The submission was refused and NOTHING was written - the whole review is atomic. The body takes one of two shapes and you have to handle both, which is why this response is a oneOf rather than a single object.

No details - the refusal is about the submission or the statement as a whole, and code is what to branch on. validation_failed covers a malformed figure (a thousands separator, a fifth decimal, an out-of-range amount), a lines entry naming a line of another statement or carrying no id at all, and a LINE whose own state forbids correction - already reconciled or posted to the ledger, archived, or still pending. statement_not_reviewable covers the STATEMENT's state, which is answered before anything is written.

With details - the submission was malformed in a way that names the value to resend, and every malformed value is named at once. lines when it is not a list of line objects, or carries more entries than one submission allows; opening_balance / closing_balance when a balance arrived as an object, a list or a boolean; lines[N][field] - the index being the position you sent - when one field of one line did, with label narrower than the rest (text only). The code is validation_failed throughout.