Finalize an upload session created by Initiate large upload (POST /v2/files/large-upload). The parts array must include every part that was uploaded, with the etag returned by the storage backend for each part PUT.

On success the file is marked as uploaded and returned in the response. The file's processing status may still be pending while downstream processing runs. A 502 response indicates the storage backend rejected the finalization (for example, a part etag mismatch) — the client may retry.

Idempotent for already-DONE files: a retry of a previously-successful complete call (or a complete call arriving after the auto-finalize backstop has already finalised the row) returns 200 with the file metadata instead of 409. FAILED / CANCELLED still return 409.

To cancel an in-progress upload, simply stop calling the API: abandoned file records are garbage-collected after 24 hours, and any incomplete S3 multipart parts are reaped by an S3 bucket lifecycle rule.

Required scope: data:file_import or doc:file_import