Draft an allocation against a bank operation
POST/api/v1/bank_operations/:bank_operation_id/allocations
Creates a proposed allocation. This is a draft and nothing else: no payment is written, no ledger line is touched and the invoice stays unpaid. Settling the money is POST /api/v1/bank_operations/{id}/reconciliation, which takes the complete allocation set and the operation's version.
The invoice must belong to the OPERATION'S OWN company, and the same domain rules the application enforces apply here: an incoming movement settles a sales invoice, an outgoing one a purchase invoice, the currencies must agree, and the invoice must still be open and payable.
Idempotency-Key is REQUIRED. A replay under the same key and the same body returns the stored response with Idempotency-Replayed: true and creates nothing; the same key with a different body is 409 idempotency_key_reuse.
Request
Responses
- 201
- 401
- 403
- 404
- 409
- 422
The drafted allocation.
The request carries no bearer token, or one that is invalid or expired.
The token does not hold the write scope, or the bank_reconciliation feature is off for the operation's workspace.
No operation with this id is reachable by the token's grants.
A first request bearing the same Idempotency-Key is still in flight (idempotency_request_in_progress), or the key was replayed with a DIFFERENT body (idempotency_key_reuse). Nothing was written either way. Neither is retryable as it stands: send a fresh key, or resend the original body to replay the stored response.
The body was refused. code says which refusal it is: validation_failed for a missing or negative allocated_amount, an invoice reference that is missing or does not resolve, a pair already allocated, or a domain rule (direction, currency, an invoice that is not open and payable); allocation_exceeds_operation when the operation's active allocations would then settle more than the movement carries. A missing Idempotency-Key is validation_failed with details.idempotency_key.
The body is checked in this order and the first refusal is the one answered: allocated_amount (details.allocated_amount), the invoice reference (details.invoice_document), the operation's budget (details.base), then the pair and the domain rules. Those last two carry their reason in message and have no details key.
The invoice reference has two distinct refusals, both under details.invoice_document, told apart by the message, which the API sends in French. Send no invoice_document_id at all and it is est obligatoire. Send one that does not resolve - an id of another company, an id that exists nowhere, or a value that is not an id at all, null included - and it is est introuvable dans l'entreprise de cette opération. Those three cases answer IDENTICALLY on purpose, so the response cannot be used to probe for an invoice you cannot otherwise see.