# ERP API Contract — Separate endpoints

The external PO platform must never read or write NAV SQL tables directly. NAV/BC exposes separate web-service endpoints. Every GET supports incremental filtering (`modified_after`) and paging (`page_size`, `cursor`). Every POST accepts `Idempotency-Key`.

## ERP → PO Platform

| Code | Endpoint | Suggested schedule | Purpose |
|---|---|---:|---|
| ERP_LOCATIONS | `GET /api/po/locations` | 60 min | Stores and warehouses |
| ERP_ITEMS | `GET /api/po/items` | 60 min | Item master |
| ERP_VENDORS | `GET /api/po/vendors` | 60 min | Vendor master |
| ERP_VENDOR_ITEMS | `GET /api/po/vendor-items` | 60 min | Vendor-item mapping, MOQ, pack, lead time, price |
| ERP_INVENTORY | `GET /api/po/inventory` | 15 min | Quantity per item/location |
| ERP_SALES_DAILY | `GET /api/po/sales-daily` | 15 min | Daily sales aggregation; initial load should include 5 years |
| ERP_PURCHASE_HISTORY | `GET /api/po/purchase-history` | 60 min | PO/receipt history |
| ERP_OPEN_PO | `GET /api/po/open-purchase-orders` | 15 min | Outstanding purchase quantities |
| ERP_TRANSFERS | `GET /api/po/transfers` | 15 min | Open transfer orders |
| ERP_OFFERS | `GET /api/po/vendor-offers` | 60 min | Vendor offers/contracts |

## PO Platform → ERP

| Code | Endpoint | Purpose |
|---|---|---|
| ERP_CREATE_PO | `POST /api/po/purchase-orders` | Create an approved PO using NAV business logic |
| ERP_CREATE_TRANSFER | `POST /api/po/transfer-orders` | Create approved transfer order |

## Required field examples

### `/api/po/items`
```json
{"data":[{"item_no":"100001","barcode":"628...","description_ar":"...","description_en":"...","base_uom":"PCS","purchase_uom":"CTN","pack_size":24,"unit_cost":10.25,"last_purchase_cost":10.1,"blocked":false,"discontinued":false,"modified_at":"2026-08-11 12:00:00"}],"next_cursor":null,"max_modified_at":"2026-08-11 12:00:00"}
```

### `/api/po/inventory`
```json
{"data":[{"location_code":"WH01","item_no":"100001","on_hand":1500,"reserved_qty":120,"available_qty":1380,"qty_on_sales_order":50,"qty_on_purchase_order":500,"qty_in_transfer_in":0,"qty_in_transfer_out":200,"modified_at":"2026-08-11 12:15:00"}]}
```

### `/api/po/sales-daily`
```json
{"data":[{"sales_date":"2026-08-10","location_code":"S01","item_no":"100001","qty_sold":125,"qty_returned":2,"net_sales":1760.50,"cost_amount":1220,"stockout_minutes":0,"in_stock_minutes":1440,"transaction_count":82}]}
```

### `/api/po/vendor-items`
```json
{"data":[{"vendor_no":"V0001","item_no":"100001","vendor_item_no":"ABC-22","purchase_uom":"CTN","pack_size":24,"moq":240,"order_multiple":24,"lead_time_days":5,"price":10.25,"preferred":true,"ranking":1,"modified_at":"2026-08-11 10:00:00"}]}
```

### `POST /api/po/purchase-orders`
```json
{"external_po_no":"PO-SYS-20260811-0001","vendor_no":"V0001","order_date":"2026-08-11","location_code":"WH01","currency_code":"SAR","lines":[{"line_no":10000,"item_no":"100001","location_code":"WH01","uom":"CTN","quantity":480,"unit_cost":10.25,"discount_percent":0}]}
```
Expected response:
```json
{"success":true,"document_no":"PO-109283"}
```

## NAV rules

1. POST endpoints must call NAV purchase/transfer document business logic; no direct SQL inserts.
2. `external_po_no` + `Idempotency-Key` must be unique to prevent duplicate PO creation on retry.
3. Return validation errors line-by-line where possible.
4. Initial sales migration is a separate bulk process. After the 5-year load, only incremental daily changes are transferred.
5. API endpoints are independent. Failure of Sales does not block Inventory, Vendors, Open PO, etc.

## ERP_INVENTORY_MOVEMENTS
`GET /api/po/inventory-movements`

حقول أساسية: `entry_no`, `item_no`, `location_code`, `posting_date`, `posting_datetime`, `movement_type`, `document_no`, `source_no`, `quantity`, `cost_amount`, `sales_amount`, `remaining_quantity`.

القيم المقترحة لـ `movement_type`: SALE, SALE_RETURN, PURCHASE_RECEIPT, PURCHASE_RETURN, TRANSFER_IN, TRANSFER_OUT, POSITIVE_ADJ, NEGATIVE_ADJ, COUNT, OTHER.

## ERP_PURCHASE_RECEIPTS
`GET /api/po/purchase-receipts`

حقول أساسية: `receipt_no`, `po_no`, `vendor_no`, `receipt_date`, `location_code`, `total_qty`, `total_amount`, `modified_at`.

يفضل Endpoint إضافي للـ receipt lines إذا كانت تفاصيل lot/expiry مطلوبة من NAV.