POST /import

Halaman ini mencakup empat endpoint yang bekerja bersama untuk mengimpor data dari file Excel: upload file, preview validasi, polling status, dan commit eksekusi.

Referensi Cepat (Quick Reference)

Endpoint	Method	URL	Fungsi
Upload File	`POST`	`/api/{project}/{endpoint}/import-upload`	Upload file Excel untuk diproses
Preview Validasi	`POST`	`/api/{project}/{endpoint}/import-preview`	Memulai validasi asinkron
Cek Status	`GET`	`/api/{project}/{endpoint}/import-status?job_id=xxx`	Polling status validasi atau commit
Commit	`POST`	`/api/{project}/{endpoint}/import-commit`	Eksekusi INSERT/UPDATE ke database

Ikhtisar (Overview)

Proses import berjalan dalam tiga langkah utama dengan polling status di antara langkah:

Upload — Upload file Excel melalui POST /import-upload. Server mengembalikan upload_id beserta preview data.
Preview — Kirim POST /import-preview untuk memulai validasi asinkron. Gunakan GET /import-status untuk memantau progres validasi hingga status preview_ok atau preview_error.
Commit — Jika validasi berhasil (preview_ok), kirim POST /import-commit untuk mengeksekusi operasi INSERT/UPDATE ke database. Gunakan GET /import-status kembali untuk memantau hingga status completed.

Langkah 1: Upload File (Step 1: Upload File)

POST /import-upload

Upload file Excel untuk diproses. Request menggunakan Content-Type: multipart/form-data.

Request:

Parameter	Tipe	Wajib	Keterangan
`file`	file	Ya	File Excel (.xlsx) yang akan diimpor

POST /api/mini-inventory/supplier/import-upload
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="suppliers.xlsx"
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

[binary file content]
--boundary--

Response Sukses (200 OK):

{
    "success": true,
    "upload_id": "upload-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "total_rows": 150,
    "preview": [
        {
            "supplier_code": "SUP-001",
            "supplier_name": "PT Maju Jaya",
            "email": "info@majujaya.com",
            "phone": "021-5551234",
            "is_active": true
        },
        {
            "supplier_code": "SUP-002",
            "supplier_name": "CV Berkah Sentosa",
            "email": "contact@berkahsentosa.com",
            "phone": "021-5555678",
            "is_active": true
        }
    ],
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Array preview berisi beberapa baris pertama dari file yang di-upload untuk keperluan verifikasi visual sebelum melanjutkan ke langkah validasi.

Langkah 2: Preview Validasi (Step 2: Validation Preview)

POST /import-preview

Memulai proses validasi asinkron terhadap data yang sudah di-upload.

Request:

POST /api/mini-inventory/supplier/import-preview

{
    "upload_id": "upload-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response Sukses (200 OK):

{
    "success": true,
    "job_id": "preview-b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "status": "validating",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Polling Status (Status Polling)

GET /import-status

Polling status job validasi atau commit menggunakan job_id.

GET /api/mini-inventory/supplier/import-status?job_id=preview-b2c3d4e5-f6a7-8901-bcde-f23456789012

Status: validating

{
    "success": true,
    "job_id": "preview-b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "status": "validating",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Status: preview_ok (validasi berhasil)

{
    "success": true,
    "job_id": "preview-b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "status": "preview_ok",
    "summary": {
        "valid": 145,
        "invalid": 3,
        "skip": 2
    },
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Status: preview_error (ditemukan error pada data)

{
    "success": true,
    "job_id": "preview-b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "status": "preview_error",
    "errors": [
        {
            "rowIndex": 12,
            "rowData": {
                "supplier_code": "",
                "supplier_name": "PT Tanpa Kode",
                "email": "invalid-email"
            },
            "messages": [
                "Field supplier_code is required",
                "Field email must be a valid email address"
            ]
        },
        {
            "rowIndex": 45,
            "rowData": {
                "supplier_code": "SUP-001",
                "supplier_name": "PT Duplikat",
                "email": "dup@example.com"
            },
            "messages": [
                "Duplicate supplier_code: SUP-001 already exists"
            ]
        }
    ],
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Status: completed (commit selesai)

{
    "success": true,
    "job_id": "commit-c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "completed",
    "result": {
        "inserted": 120,
        "updated": 25,
        "skipped": 2,
        "failed": 3
    },
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Langkah 3: Commit (Step 3: Commit)

POST /import-commit

Mengeksekusi operasi INSERT/UPDATE ke database berdasarkan hasil validasi preview. Endpoint ini hanya dapat dipanggil jika status job preview adalah preview_ok.

Request:

POST /api/mini-inventory/supplier/import-commit

{
    "preview_job_id": "preview-b2c3d4e5-f6a7-8901-bcde-f23456789012"
}

Response Sukses (200 OK):

{
    "success": true,
    "job_id": "commit-c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "processing",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Setelah menerima response ini, gunakan GET /import-status?job_id=commit-c3d4e5f6-... untuk memantau progres commit hingga status completed.

Commit hanya dapat dieksekusi jika status preview adalah preview_ok. Percobaan commit terhadap job dengan status lain akan menghasilkan error.

Strategi Upsert (Upsert Strategies)

Perilaku import terhadap record yang sudah ada di database ditentukan oleh konfigurasi upsertStrategy.

Strategi	Record Sudah Ada	Record Baru
`update_existing`	UPDATE dengan data baru	INSERT
`insert_only`	SKIP dengan error	INSERT
`skip_existing`	SKIP tanpa error (silent)	INSERT

Strategi default adalah update_existing jika tidak dikonfigurasi secara eksplisit.

Konfigurasi (Configuration)

Perilaku import dikontrol melalui objek importConfig di konfigurasi payload.

Contoh importConfig di payload

{
    "importConfig": {
        "upsertKeys": ["supplier_code"],
        "upsertStrategy": "update_existing",
        "lookupFields": {
            "category_name": {
                "targetTable": "category",
                "targetField": "category_id",
                "lookupField": "category_name"
            }
        }
    }
}

Properti	Tipe	Keterangan
`upsertKeys`	array	Field yang digunakan untuk mendeteksi apakah record sudah ada di database
`upsertStrategy`	string	Strategi penanganan record duplikat: `update_existing`, `insert_only`, atau `skip_existing`
`lookupFields`	object	Konfigurasi resolusi nama ke ID. Misalnya, kolom `category_name` di Excel otomatis di-resolve ke `category_id` berdasarkan tabel referensi

Konfigurasi lookupFields memungkinkan pengguna mengisi nama yang mudah dibaca di file Excel (misalnya nama kategori), sementara sistem secara otomatis mencarikan ID yang sesuai dari tabel referensi.

Langkah Selanjutnya (Next Steps)

POST /export untuk mengekspor data ke Excel
POST /read untuk memverifikasi data setelah import
Kode Error untuk referensi lengkap HTTP status code

POST /import

On this page