# BE-FE Endpoint Contract Handoff

Tanggal: 2026-04-24  
Source of truth: `internal/server/http.go` (backend aktif)

## Base URL

- Production: `https://apibazzar.softcomp.io/api/v1`
- Semua endpoint (kecuali health/login/refresh/logout) butuh header:
  - `Authorization: Bearer <access_token>`

## Auth

- `POST /auth/login`
- `POST /auth/refresh`
- `POST /auth/logout`
- `GET /auth/me`

## Products

- `GET /products`
- `POST /products`
- `PUT /products/:id`
- `PATCH /products/:id/promo-price`
- `POST /products/promo-price/bulk`
- `GET /products/resolve`
- `GET /products/scan`
- `GET /products/:id`
- `DELETE /products/:id`

Import/Export:
- `POST /import/products`
- `GET /import/products/template`
- `GET /import/jobs/:id`
- `GET /export/products`

## POS

- `POST /pos/cart/price-preview`
- `POST /pos/price-preview` (alias endpoint)
- `POST /pos/cart/select-free-item`
- `POST /pos/checkout`
- `POST /pos/returns`
- `GET /pos/sales/:id/receipt`
- `POST /pos/sales/:id/edit-preview`
- `PUT /pos/sales/:id`
- `POST /pos/sales/:id/edit` (alias commit)

### Contract penting: `POST /pos/returns`

Payload yang didukung saat ini:

```json
{
  "sale_id": 92,
  "reason": "alasan return",
  "items": [
    { "product_id": 5971, "qty": 1 }
  ]
}
```

Catatan:
- `exchange_items` **belum didukung** di endpoint ini.
- Jika FE kirim `exchange_items`, BE akan balas 4xx (validasi), bukan 500.
- FE disarankan fallback: kirim ulang payload tanpa `exchange_items`.

## Reports

- `GET /reports/sales`
- `GET /reports/sales/export.xlsx`
- `GET /reports/sales/payment-recap`
- `GET /reports/sales/detail-preview`
- `GET /reports/sales/export-items`

## Prices (Approval)

- `GET /prices/change-requests`
- `POST /prices/change-requests`
- `POST /prices/change-requests/:id/approve`
- `POST /prices/change-requests/:id/reject`

## Promos

Manage (role manage):
- `GET /promos`
- `POST /promos`
- `POST /promos/price-items`
- `PUT /promos/shopping-bag-rule`
- `GET /promos/bundling`
- `POST /promos/bundling`
- `PUT /promos/:id`
- `POST /promos/:id/activate`
- `POST /promos/:id/deactivate`

Scan/read:
- `GET /promos/shopping-bag-rule`
- `GET /promos/bundling/match`

## Stocks

- `POST /stocks/adjustments`
- `POST /stocks/opname`
- `GET /stocks/alerts`
- `GET /stocks/alerts/summary`
- `GET /stocks/movements`
- `GET /stocks/:product_id/summary`

Compatibility alias:
- `POST /inventory/adjustments` (alias ke stock adjustment)

## Members

- `GET /members`
- `POST /members`

## Employees

`/api/v1` endpoints:
- `GET /employees`
- `GET /employees/:id/transactions`
- `POST /employees`
- `PUT /employees/:id`
- `PATCH /employees/:id`
- `DELETE /employees/:id`

Compatibility alias tanpa prefix `/api/v1` juga tersedia:
- `GET /employees`
- `GET /employees/:id/transactions`
- `POST /employees`
- `PUT /employees/:id`
- `PATCH /employees/:id`
- `DELETE /employees/:id`

## Settings

`/api/v1/settings`:
- `GET /settings/general`
- `PUT /settings/general`
- `GET /settings/permissions`
- `GET /settings/users`
- `POST /settings/users`
- `PUT /settings/users/:id`
- `DELETE /settings/users/:id`
- `GET /settings/users/:id/permissions`
- `PUT /settings/users/:id/permissions`
- `POST /settings/data/purge`
- `POST /settings/data/purge-selected`
- `POST /settings/data/transactions/delete-one`
- `POST /settings/session-policy/force-logout`

Compatibility alias tanpa prefix `/api/v1/settings` juga tersedia dengan path sama.

## Automation

- `GET /automation/free-items`
- `POST /automation/free-items`
- `PUT /automation/free-items/:id`
- `DELETE /automation/free-items/:id`

## Reconciliation

- `POST /reconciliation/automation/dry-run`
- `POST /reconciliation/automation/apply`

## Health

- `GET /healthz`

## FE Integration Checklist (wajib)

1. Base URL FE harus `https://apibazzar.softcomp.io/api/v1`.
2. Semua request protected pakai bearer token dari `/auth/login`.
3. Untuk return:
   - Default pakai payload `sale_id + reason + items`.
   - Jika ada fitur exchange di FE, jangan hard-fail:
     - kirim `exchange_items` hanya jika endpoint BE baru sudah tersedia, atau
     - fallback otomatis ke payload return lama.
4. Jangan asumsi endpoint alias ada di semua modul; pakai daftar ini sebagai acuan.