POST /read-composite

Endpoint /read-composite digunakan untuk mengambil satu record header (master) beserta seluruh detail item terkait dalam satu response. Data dikembalikan dalam struktur bersarang di mana detail item berupa array di dalam object header.

Referensi Cepat (Quick Reference)

Properti	Nilai
Method	`POST`
URL	`/api/{project}/{endpoint}/read-composite`
Content-Type	`application/json`
Status Sukses	`200 OK`
Database	PostgreSQL, MySQL, Oracle
Cache	Tidak di-cache
Parameter Wajib	`where` (array kondisi filter)

Ikhtisar (Overview)

Endpoint ini dirancang untuk mengambil data master-detail secara lengkap dalam satu panggilan API. Contoh penggunaannya antara lain menampilkan halaman detail stock inbound beserta seluruh item barang, atau mengambil data invoice beserta line item untuk keperluan cetak.

Record header diambil berdasarkan kondisi where yang dikirim dalam request body. Detail item diambil berdasarkan konfigurasi detailQuery di payload, yang dapat menyertakan kolom dari tabel lain melalui JOIN.

Endpoint /read-composite tidak menggunakan cache. Setiap request selalu dijalankan langsung ke database untuk memastikan data yang dikembalikan selalu merupakan versi terbaru.

Format Request (Request Format)

Parameter (Parameters)

Request body berisi array where yang digunakan sebagai kondisi filter untuk mengidentifikasi record header.

Parameter	Tipe	Wajib	Keterangan
`where`	array	Ya	Array object `{key, value}` sebagai kondisi filter

Setiap elemen dalam array where memiliki struktur berikut:

Properti	Tipe	Keterangan
`key`	string	Nama kolom yang digunakan sebagai filter
`value`	any	Nilai yang dicocokkan

Parameter where bersifat wajib dan tidak boleh berupa array kosong. Request tanpa where atau dengan array kosong akan menghasilkan response error 400.

Contoh Request (Request Examples)

Mengambil data berdasarkan primary key:

POST /api/mini-inventory/stock-inbound/read-composite

{
    "where": [
        { "key": "stock_inbound_id", "value": "a1b2c3d4-0000-0000-0000-000000000000" }
    ]
}

Mengambil data berdasarkan nomor dokumen:

POST /api/mini-inventory/stock-inbound/read-composite

{
    "where": [
        { "key": "inbound_number", "value": "INB/2026/001" }
    ]
}

Mengambil data dengan beberapa kondisi:

POST /api/mini-inventory/stock-inbound/read-composite

{
    "where": [
        { "key": "inbound_number", "value": "INB/2026/001" },
        { "key": "warehouse_id", "value": "d1000000-0000-0000-0000-000000000000" }
    ]
}

Format Response (Response Format)

Response Sukses (Success Response)

HTTP 200 OK

Response mengembalikan data header sebagai object dengan detail item berupa array bersarang di dalamnya.

{
    "success": true,
    "data": {
        "stock_inbound_id": "a1b2c3d4-0000-0000-0000-000000000000",
        "inbound_number": "INB/2026/001",
        "inbound_date": "2026-04-16",
        "supplier_id": "b1000000-0000-0000-0000-000000000000",
        "supplier_name": "PT Maju Jaya",
        "warehouse_id": "d1000000-0000-0000-0000-000000000000",
        "warehouse_name": "Gudang Utama",
        "notes": "First batch delivery",
        "total_items": 2,
        "total_qty": 35,
        "total_amount": 20000000,
        "created_at": "2026-04-16T10:30:00.000Z",
        "created_by": "Input from API",
        "stock_inbound_item": [
            {
                "stock_inbound_item_id": "e5f6a7b8-0000-0000-0000-000000000001",
                "stock_inbound_id": "a1b2c3d4-0000-0000-0000-000000000000",
                "line_number": 1,
                "item_product_id": "04d71c62-0000-0000-0000-000000000000",
                "product_name": "Widget A",
                "qty_received": 25,
                "uom": "pcs",
                "unit_price": 500000,
                "amount": 12500000
            },
            {
                "stock_inbound_item_id": "e5f6a7b8-0000-0000-0000-000000000002",
                "stock_inbound_id": "a1b2c3d4-0000-0000-0000-000000000000",
                "line_number": 2,
                "item_product_id": "15e82d73-0000-0000-0000-000000000000",
                "product_name": "Widget B",
                "qty_received": 10,
                "uom": "pcs",
                "unit_price": 750000,
                "amount": 7500000
            }
        ]
    },
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Response Error (Error Responses)

400 — Parameter WHERE kosong:

{
    "success": false,
    "error": "Invalid payload",
    "message": "WHERE parameter is required",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

400 — Format WHERE tidak valid:

{
    "success": false,
    "error": "Invalid payload",
    "message": "Invalid WHERE format. Expected array of {key, value} objects",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

500 — Server error:

{
    "success": false,
    "error": "Internal server error",
    "message": "An unexpected error occurred",
    "timestamp": "2026-04-16T10:30:00.000Z"
}

Konfigurasi Detail Query (Detail Query Configuration)

Kolom yang dikembalikan pada array detail item ditentukan oleh konfigurasi detailQuery di payload. Query ini dapat menyertakan JOIN ke tabel lain untuk menampilkan kolom tambahan seperti nama produk atau nama kategori.

Contoh konfigurasi detailQuery:

detailQuery

SELECT
    si.stock_inbound_item_id,
    si.stock_inbound_id,
    si.line_number,
    si.item_product_id,
    p.product_name,
    si.qty_received,
    si.uom,
    si.unit_price,
    si.amount
FROM stock_inbound_item si
LEFT JOIN product p ON p.product_id = si.item_product_id
WHERE si.stock_inbound_id = :header_id
ORDER BY si.line_number ASC

Kolom tambahan dari tabel JOIN (seperti product_name pada contoh di atas) akan disertakan dalam response tanpa perlu konfigurasi tambahan di sisi client.

Langkah Selanjutnya (Next Steps)

POST /create-composite untuk membuat data header beserta detail baru
POST /update-composite untuk memperbarui data header dan detail
Kode Error untuk referensi lengkap HTTP status code

POST /read-composite

On this page