API Upload File

Gambaran Umum

AlurKerja menyediakan satu endpoint upload umum yang menyimpan file ke object storage instance (MinIO, atau S3/COS pada instalasi cloud) dan mengembalikan path objek yang bisa disimpan sendiri oleh pemanggil — misalnya ke kolom master data, ke field custom, atau ke sistem luar.

Endpointnya sepasang:

Seluruh file masuk ke satu bucket yang dikonfigurasi di server (MINIO_BUCKET_NAME). Pemanggil tidak bisa memilih bucket; yang bisa diatur hanya folder di dalam bucket tersebut.

Kapan Memakai Endpoint Ini

Endpoint ini adalah jalur upload umum. Untuk tiga kebutuhan berikut sudah ada endpoint khusus yang menyimpan metadata, memvalidasi tipe file, dan mengikat file ke objek bisnisnya — jangan memakai endpoint umum untuk ketiganya:

Endpoint umum ini tidak memvalidasi ekstensi maupun tipe isi file, dan tidak menyimpan baris metadata apa pun. Yang tersimpan hanyalah objeknya di bucket; hubungan file dengan data bisnis sepenuhnya menjadi tanggung jawab pemanggil.

Di dalam produk, endpoint ini dipakai oleh kolom bertipe file pada Master Data: nilai yang disimpan ke record adalah string url hasil upload.

Mengunggah File

POST /api/v1/integration/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>
x-active-tenant: <slug-workspace>

Contoh:

curl -X POST "https://app.contoh.com/api/v1/integration/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-active-tenant: workspace-saya" \
  -F "file=@ktp-budi.pdf" \
  -F "folder=master-data/pelanggan"

Response 200 OK:

{
  "status": "success",
  "message": "File uploaded successfully",
  "data": {
    "file_name": "ktp-budi.pdf",
    "object_name": "master-data/pelanggan/ktp-budi_1758790000.pdf",
    "url": "/tenant-uploads/master-data/pelanggan/ktp-budi_1758790000.pdf",
    "size": 248310
  }
}

Aturan penamaan objek

Nama objek dibentuk dari nama file asli dengan sisipan unix timestamp (detik) sebelum ekstensi:

laporan-q3.xlsx   →   laporan-q3_1758790000.xlsx

Beberapa konsekuensi yang perlu diketahui:

• Nama file asli dipertahankan apa adanya. Spasi, tanda kurung, dan karakter non-ASCII ikut masuk ke key objek — URL unduhannya wajib di-URL-encode saat dipakai di href atau di pemanggil lain.
• Komponen direktori pada nama file dibuang. File bernama ../../etc/ktp.pdf tersimpan sebagai ktp.pdf; nama file tidak bisa dipakai untuk keluar dari folder.
• Resolusinya per detik, bukan per milidetik. Dua upload dengan nama file yang sama, ke folder yang sama, pada detik yang sama akan menghasilkan key yang sama — yang kedua menimpa yang pertama tanpa pesan error apa pun.

Mengambil File Kembali

GET /api/v1/integration/public/{path}

Nilai url dari response upload bisa langsung ditempel di belakang /api/v1/integration/public:

https://app.contoh.com/api/v1/integration/public/tenant-uploads/master-data/pelanggan/ktp-budi_1758790000.pdf

Dua bentuk path diterima dan menunjuk objek yang sama:

Artinya endpoint ini selalu membaca dari bucket yang dikonfigurasi di server; tidak ada cara meminta objek dari bucket lain lewat URL.

Response-nya adalah isi file dengan Content-Type sesuai yang tersimpan saat upload, dan header Content-Disposition: attachment — browser akan mengunduh, bukan menampilkan inline.

Kode Status

Untuk endpoint unduh:

Batas Ukuran File

Tidak ada satu angka tunggal — yang berlaku adalah batas terkecil di sepanjang jalur permintaan:

Jadi pada instalasi standar, batas efektifnya 80 MB.

Konfigurasi Server

Endpoint ini membaca konfigurasi object storage dari environment variable berikut pada Integration Service:

Pola Pemakaian yang Umum

1. Kirim file ke POST /api/v1/integration/upload bersama folder yang menjelaskan asal datanya.
2. Simpan nilai url dari response ke record milik Anda (kolom master data, variable proses, atau sistem luar) — bukan object_name, supaya prefix bucket ikut tersimpan.
3. Saat perlu menampilkan, rangkai tautan "<base-url>/api/v1/integration/public" + url, dan lakukan URL-encode bila nama file mengandung spasi atau karakter khusus.

Kalau file yang diunggah harus mengikuti daur hidup proses (ikut terhapus saat draft dibatalkan, ikut tercatat di histori task), gunakan lampiran form BPMN, bukan pola di atas.