# Dokumentasi Endpoint SAP

## Informasi Umum

- **Base URL SAP Gateway**: `https://fiori.spunindo.com/sap/bc/zsr_jsonhd/`
- **SAP Client**: `300`
- **Authentication**: Basic Auth via parameter (`sap-user`, `sap-password`)
- **Format Response**: JSON (`format=json`)
- **Bahasa**: English (`sap-language=EN`)

---

## 1. Endpoint: ZFBILLING (Data Billing)

| Item | Detail |
|------|--------|
| **Environment Variable** | `SAP_BILLING` |
| **SAP Function Module** | `ZFBILLING` |
| **Base URL** | `https://fiori.spunindo.com/sap/bc/zsr_jsonhd/ZFBILLING?sap-client=300&sap-user=JKT-1&sap-password=jabaran123!&sap-language=EN&format=json` |
| **Response Key** | `ET_ZVBILLING` |
| **File Referensi** | `app/Http/Controllers/DashboardController.php` (line 528) |

### Parameter

| Parameter | Tipe | Wajib | Deskripsi | Contoh |
|-----------|------|-------|-----------|--------|
| `sap-client` | string | Ya | SAP Client ID | `300` |
| `sap-user` | string | Ya | Username SAP | `JKT-1` |
| `sap-password` | string | Ya | Password SAP | `jabaran123!` |
| `sap-language` | string | Tidak | Bahasa | `EN` |
| `format` | string | Tidak | Format response | `json` |
| **`fromdate`** | string (YYYY-MM-DD) | **Tidak** | **Tanggal awal billing** | `2026-01-01` |
| **`todate`** | string (YYYY-MM-DD) | **Tidak** | **Tanggal akhir billing** | `2026-12-31` |

> **Catatan**: Parameter `fromdate` dan `todate` digunakan untuk filter rentang tanggal billing (kolom `BILLDATE`).

### Contoh URL Lengkap

```
https://fiori.spunindo.com/sap/bc/zsr_jsonhd/ZFBILLING?sap-client=300&sap-user=JKT-1&sap-password=jabaran123!&sap-language=EN&format=json&fromdate=2026-01-01&todate=2026-12-31
```

### Contoh Penggunaan dalam Kode (PHP)

```php
$url_billing = env('SAP_BILLING') . '&fromdate=' . urlencode($fromDate) . '&todate=' . urlencode($toDate);
$responseBilling = Http::timeout(120)->get($url_billing);
$billingData = json_decode($responseBilling->body(), true);
$getBilling = $billingData['ET_ZVBILLING'] ?? [];
```

### Response Structure (Key `ET_ZVBILLING`)

Setiap item dalam array memiliki field sebagai berikut:
`MANDT, ITMNO, ITEMD, MATNR, MATGR, MARAMATKL, SLOC, FISYR, PERIOD, BILLDATE, BUDAT, ZZGSM, ZZWIDTHROLL, ZZLENGTHROLL, BILLQTY, SALESU, NUM, DENOM, UNITOM, FKLMG, ACTWEIGHT, LMENG, GROSSWT, UNIT, NETPR, PER, MEAS, NUMCONV, DENOMCONV, UNITCONV, NETPRKG, WAERK, MEINS, NETVAL, TAX, TOTVAL, CRCY, PAYER, PAYERD, SOLDTO, SOLDTOD, CITY, INCO1, INCO2, SHIPPOINT, ORG, CNCL, BILLTYPE, BILLCAT, DOCCAT, DISTCH, DISTCHD, DIVISION, PPROC, CUSTGRP, CUSTGRPD, BEZEI, STATUS, INVLISTTYP, ORCOUNTRYTX, ORTXNO, DSCOUNTRYTX, JOURVALUSD, CRCYUSD, JOURVALIDR, CRCYIDR, ACTJOURVALUSD, ACTCRCYUSD, ACTJOURVALIDR, ACTCRCYIDR, DOCNO, RFDOC, SALESDOC, SALESDOCITEM, CRTDBY, TIME, CRTDON, SLSMAN, VMSL, LAND1, LANDX, REGIO, BEZEI2, BILLDOC`

---

## 2. Endpoint: Z_GET_PAYMENT (Data Pembayaran)

| Item | Detail |
|------|--------|
| **Environment Variable** | `SAP_PAYMENT` |
| **SAP Function Module** | `Z_GET_PAYMENT` |
| **Base URL** | `https://fiori.spunindo.com/sap/bc/zsr_jsonhd/Z_GET_PAYMENT?sap-client=300&sap-user=JKT-1&sap-password=jabaran123!&sap-language=EN&format=json` |
| **Response Key** | `ET_ZVGETPAYBILL` |
| **File Referensi** | `app/Http/Controllers/DashboardController.php` (line 529) |

### Parameter

| Parameter | Tipe | Wajib | Deskripsi | Contoh |
|-----------|------|-------|-----------|--------|
| `sap-client` | string | Ya | SAP Client ID | `300` |
| `sap-user` | string | Ya | Username SAP | `JKT-1` |
| `sap-password` | string | Ya | Password SAP | `jabaran123!` |
| `sap-language` | string | Tidak | Bahasa | `EN` |
| `format` | string | Tidak | Format response | `json` |
| **`f_paydt`** | string (YYYY-MM-DD) | **Tidak** | **Tanggal awal pembayaran** | `2026-01-01` |
| **`t_paydt`** | string (YYYY-MM-DD) | **Tidak** | **Tanggal akhir pembayaran** | `2026-12-31` |

> **Catatan**: Parameter `f_paydt` dan `t_paydt` digunakan untuk filter rentang tanggal pembayaran.

### Contoh URL Lengkap

```
https://fiori.spunindo.com/sap/bc/zsr_jsonhd/Z_GET_PAYMENT?sap-client=300&sap-user=JKT-1&sap-password=jabaran123!&sap-language=EN&format=json&f_paydt=2026-01-01&t_paydt=2026-12-31
```

### Contoh Penggunaan dalam Kode (PHP)

```php
$url_payment = env('SAP_PAYMENT') . '&f_paydt=' . urlencode($fromDate) . '&t_paydt=' . urlencode($toDate);
$responsePayment = Http::timeout(120)->get($url_payment);
$paymentData = json_decode($responsePayment->body(), true);
$getPayment = $paymentData['ET_ZVGETPAYBILL'] ?? [];
```

### Response Structure (Key `ET_ZVGETPAYBILL`)

Setiap item dalam array memiliki field sebagai berikut:
`MANDT, CCODE, FISYEAR, DOCNUMBER, POST_DATE, REF_DOC, REF_ITEM, TRCURR, TRAMNT, CCCURR, CCAMNT, GLCURR, GLAMNT, VLQTY, ACCOUNT, CLRDATE, CLRDOC, CLRYEAR, ACCTY, DC, NETDATE, CUST, REFPROC, SALESMAN`

---

## 3. Endpoint: Z_GET_NEW_CUST (Data Customer Baru)

| Item | Detail |
|------|--------|
| **Environment Variable** | `SAP_CUSTOMER` |
| **SAP Function Module** | `Z_GET_NEW_CUST` |
| **Base URL** | `https://fiori.spunindo.com/sap/bc/zsr_jsonhd/Z_GET_NEW_CUST?sap-client=300&sap-user=JKT-1&sap-password=jabaran123!&sap-language=EN&format=json` |
| **Response Key** | `ET_ZVGETNCUST` |
| **File Referensi** | `app/Http/Controllers/DashboardController.php` (line 47) |

### Parameter

| Parameter | Tipe | Wajib | Deskripsi | Contoh |
|-----------|------|-------|-----------|--------|
| `sap-client` | string | Ya | SAP Client ID | `300` |
| `sap-user` | string | Ya | Username SAP | `JKT-1` |
| `sap-password` | string | Ya | Password SAP | `jabaran123!` |
| `sap-language` | string | Tidak | Bahasa | `EN` |
| `format` | string | Tidak | Format response | `json` |
| **`serdat`** | string (YYYYMM) | **Tidak** | **Periode (tahun + bulan)** | `202601` |

> **Catatan**: Parameter `serdat` digunakan untuk filter periode layanan dalam format `YYYYMM` (tahun + bulan tanpa separator). Endpoint ini dipanggil 12 kali (per bulan) menggunakan multi cURL untuk mendapatkan data satu tahun penuh.

### Contoh URL Lengkap

```
https://fiori.spunindo.com/sap/bc/zsr_jsonhd/Z_GET_NEW_CUST?sap-client=300&sap-user=JKT-1&sap-password=jabaran123!&sap-language=EN&format=json&serdat=202601
```

### Contoh Penggunaan dalam Kode (PHP)

```php
$serdat = $year . str_pad($month, 2, '0', STR_PAD_LEFT); // misal: 202601
$urls[] = env('SAP_CUSTOMER') . '&serdat=' . $serdat;
// Dipanggil parallel untuk bulan 1-12
```

### Response Structure (Key `ET_ZVGETNCUST`)

Setiap item dalam array memiliki field sebagai berikut:
`MANDT, KUNNR, NAME1, KUNNRS, NAME1S, ERDAT`

---

## 4. Endpoint: ZFM_RF_GET_ONHAND (Data Sales On Hand)

| Item | Detail |
|------|--------|
| **SAP Function Module** | `ZFM_RF_GET_ONHAND` |
| **Base URL** | `https://fioridev.spunindo.com/sap/bc/zsr_jsonhd/ZFM_RF_GET_ONHAND?sap-client=110&sap-user=INT-1&sap-password=msj123456&sap-language=EN&format=json` |
| **Response Key** | `ET_DATA` |
| **File Referensi** | `app/Jobs/SapOnHandSyncJob.php`, `app/Http/Controllers/RptsapController.php` |

### Parameter

| Parameter | Tipe | Wajib | Deskripsi | Contoh |
|-----------|------|-------|-----------|--------|
| `sap-client` | string | Ya | SAP Client ID | `110` |
| `sap-user` | string | Ya | Username SAP | `INT-1` |
| `sap-password` | string | Ya | Password SAP | `msj123456` |
| `sap-language` | string | Tidak | Bahasa | `EN` |
| `format` | string | Tidak | Format response | `json` |
| `IP_YEAR` | string | Ya | Tahun fiskal (4 digit) | `2021` |
| `IP_MONTH` | string | Ya | Bulan fiskal (2 digit) | `09` |

### Contoh Request Lengkap

```
https://fioridev.spunindo.com/sap/bc/zsr_jsonhd/ZFM_RF_GET_ONHAND?sap-client=110&sap-user=INT-1&sap-password=msj123456&sap-language=EN&format=json&IP_YEAR=2021&IP_MONTH=09
```

### Response Structure (Key `ET_DATA`)

Setiap item dalam array memiliki field sebagai berikut:
`MANDT, DOCUMENTNUMBER, CUSTOMERCODE, DELIVERYDATE, QUANTITY, FISCALYEAR, FISCALMONTH`

Contoh item:
```json
{
  "MANDT": "",
  "DOCUMENTNUMBER": "0721090003",
  "CUSTOMERCODE": "0001100115",
  "DELIVERYDATE": "2021-09-01",
  "QUANTITY": "5307.120",
  "FISCALYEAR": "2021",
  "FISCALMONTH": "09"
}
```

### Catatan

- **Hanya tersedia di SAP dev** (`fioridev.spunindo.com`, client `110` / `INT-1`) saat pengujian dilakukan. SAP produksi (client `300`) mengembalikan `ERROR_CODE: 500, ERROR_MESSAGE: "Invalid Function.-FL-E-046-:-ZFM_RF_GET_ONHAND---"`.
- `DELIVERYDATE` bisa berupa `Y-m-d`, `d.m.Y`, atau `YYYYMMDD` — job menormalkan semuanya menjadi `Y-m-d`.
- Data disimpan ke tabel `rpt_et_getonhand` (report type `Z_GET_ONHAND`), diproses bersama job SAP lain lewat `SapOnHandSyncJob` dan `RptsapController`.

---

## Informasi Tambahan

### Ringkasan Semua Filter per Endpoint

| Endpoint | Filter Parameter | Format | Dipanggil Dari |
|----------|-----------------|--------|----------------|
| `ZFBILLING` | `fromdate`, `todate` | YYYY-MM-DD | `DashboardController::fetchData()` |
| `Z_GET_PAYMENT` | `f_paydt`, `t_paydt` | YYYY-MM-DD | `DashboardController::fetchData()` |
| `Z_GET_NEW_CUST` | `serdat` | YYYYMM | `DashboardController::getCustomerFromSAP()` |
| `ZFM_RF_GET_ONHAND` | `IP_YEAR`, `IP_MONTH` | YYYY, MM | `SapOnHandSyncJob` (12 panggilan bulanan) |

### Parameter Global (Fixed di .env)

| Parameter | Nilai | Keterangan |
|-----------|-------|------------|
| `sap-client` | `300` | SAP Client |
| `sap-user` | `JKT-1` | Username |
| `sap-password` | `jabaran123!` | Password |
| `sap-language` | `EN` | Bahasa |
| `format` | `json` | Format response |

### Flow Penggunaan SAP API di Aplikasi

1. **fetchData()** dipanggil dari frontend dengan parameter tahun (`req`)
2. System mengambil data **Billing** dan **Payment** dari SAP dalam satu waktu menggunakan `Http::timeout(120)->get()`
3. Data **Customer Baru** diambil per-bulan (12 kali request) menggunakan **multi cURL** untuk paralelisasi
4. Semua data disimpan ke database lokal (`mst_billing`, `mst_payment`, `mst_customer`)
5. Data yang sudah di database lokal kemudian diproses untuk laporan akhir

### Catatan Penting

- Ketiga endpoint adalah **SAP Function Module custom** (Z-prefix) yang di-expose melalui SAP Gateway dengan handler `zsr_jsonhd`
- Parameter filter yang disebutkan di atas adalah yang **terbukti digunakan** dalam kode aplikasi. Mungkin ada parameter tambahan yang didukung oleh function module di sisi SAP, namun belum diimplementasikan di aplikasi ini
- Endpoint menggunakan **multi-threading manual** (cURL) untuk customer, dan **Laravel HTTP Client** untuk billing & payment
- Timeout SAP API diset ke **120 detik** untuk billing dan payment mengingat data yang besar