Comptabiliser un relevé bancaire révisé

POST 
/api/v1/bank_statements/:id/commit

Comptabilise les lignes extraites du relevé au grand livre et clôt sa révision. Le 200 retourne le relevé en posted, avec committed à true.

Votre POST est la confirmation, pour tout le téléversement. La plateforme ne comptabilise pas des chiffres dont personne n'a pris la responsabilité, et cet appel porte donc cette assertion : vous avez lu les lignes (GET /bank_statements/{id}/lines), corrigé ce qui devait l'être (PATCH /bank_statements/{id}/lines), et vous les comptabilisez. Il n'y a aucun appel de confirmation de révision à faire d'abord - et parce que la comptabilisation passe le téléversement entier, la confirmation que ce POST porte couvre chacun de ses fichiers, et pas seulement celui du chemin.

L'UNITÉ EST LE TÉLÉVERSEMENT, PAS LE FICHIER. Tout relevé créé par un même POST multipart appartient à un même lot, et un lot est comptabilisé en entier ou pas du tout. Comptabiliser n'importe quel fichier d'un téléversement les comptabilise donc TOUS - et un seul voisin qui doit encore être traité refuse l'appel entier avec batch_unresolved, sans avoir rien écrit. Comptabilisez une fois par téléversement, pas une fois par fichier ; un second appel nommant un voisin trouve le travail déjà fait.

Rien n'est écrit partiellement. Toute la comptabilisation tient dans une seule transaction, si bien que chaque 422 ci-dessous laisse le grand livre exactement dans l'état où il était, et la même Idempotency-Key peut être renvoyée une fois corrigé ce qui a été refusé.

Un 4xx n'est PAS une annulation, et c'est la raison d'envoyer l'en-tête. Si cette plateforme échoue pendant qu'elle construit la réponse, la comptabilisation a déjà abouti et vous pouvez recevoir un 4xx portant sur une comptabilité qui EST au grand livre. La clé est ce qui ferme cela : la rejouer répond 409 idempotency_key_consumed, ce qui vous dit que le premier appel est allé au bout et a comptabilisé. Lisez GET /bank_statements/{id} - state: posted et committed: true signifient que le travail est fait. Recomptabiliser est sans danger dans tous les cas : un fichier déjà comptabilisé répond 200 et ne comptabilise rien de nouveau.

Request

Responses

200

The upload was posted. The statement comes back at posted, with committed true.

401

The request carries no bearer token, or one that is invalid or expired. doorkeeper_authorize! is the first gate of the chain, so this is answered before the statement, the feature flag and any Idempotency-Key are resolved - and before anything is posted.

403

The token may not perform this call, and four gates answer it identically: the OAuth SCOPE derived from the HTTP verb (this one needs write), the workspace GRANT the application holds, the bank_reconciliation FEATURE FLAG, and the action's own Pundit check. All four render the same body, so message is what distinguishes them; nothing was posted in any case. The example below is refused on the scope.

404

Aucun relevé portant cet identifiant n'est atteignable par les habilitations du jeton. Un relevé appartenant à un autre espace de travail répond de la même manière, si bien que la réponse ne permet pas d'en sonder l'existence.

409

This Idempotency-Key is claimed and its outcome is not replayable. Nothing was posted by THIS call, and the two codes differ in what to do next. idempotency_request_in_progress: a first call is still running - read GET /bank_statements/{id} and let state tell you whether it reached posted, rather than looping. idempotency_key_consumed: the first call FINISHED and posted, then failed while building its response - nothing is running, so do not poll; confirm with GET /bank_statements/{id} and treat the upload as committed. A commit carries no body, so its fingerprint can never differ from the first call's and idempotency_key_reuse is unreachable here; a completed first call replays its stored 200 instead of conflicting. The key frees itself 24 hours after first receipt.

422

The commit was refused and NOTHING was posted. Branch on code, which is what tells you where the remedy is - the six are not interchangeable:

• statement_not_reviewable - the file's own state forbids it: it is archived, or its extraction has not finished. Poll GET /bank_statements/{id} until state moves; correcting lines will not clear it. No details. An already-posted file is NOT this refusal - it answers 200 with the posted row, so a retry after a timeout is always safe.
• statement_excluded - the file you named is excluded from its upload (excluded: true), so the commit leaves it out and will not post the rest of the upload in its name. Either commit by naming another file of the upload, or put this one back with POST /bank_statements/{id}/include and commit again. Polling never clears it. No details.
• account_not_ready - the target bank account cannot receive accounting: no ledger attached, the account deactivated, or your bank no longer sharing it. The remedy is on the ACCOUNT, so polling the statement is pointless.
• batch_unresolved - the statement you named is committable, but another file of the same upload still owes work. message says how many and details says WHICH, keyed <statement_id>.<reason>. .not_reviewed means that file could not be opened for review - read its state: pending or processing means let the extraction finish, failed means retry it. Any other suffix names a field of that file to correct through its own PATCH /lines. Then commit again, once.
• validation_failed - THIS file's extraction is defective, and details is keyed by the field to correct through PATCH /bank_statements/{id}/lines. It also carries details.idempotency_key when the required header is absent or outside 1-255 characters, which is refused in front of the action.
• posting_failed - the ledger itself refused the projection, or a confirmed match could not be imputed. The file is still committable, so this is the one refusal that is worth retrying unchanged once the accounting configuration is fixed.