# Astana POS API v1.0

> REST/HTTPS/JSON API untuk sistem POS Astana (POS, inventori, resit, pelanggan, pembayaran). Base URL `https://api.astanabiz.com/v1.0`. Auth: header `Token: Bearer <access_token>`. Had kadar 300 req/300s. Pagination guna `cursor`. Tarikh format `Y-m-d H:i:s`.

## Endpoints

- `GET /webhooks` — Dapatkan satu webhook mengikut ID. [tool: astana_get_webhook] (wajib: id)
- `POST /webhooks` — Cipta webhook baharu. [tool: astana_create_webhook] (wajib: url, type, status, master_username)
- `DELETE /webhooks` — Padam webhook mengikut ID. [tool: astana_delete_webhook] (wajib: id)
- `GET /category` — Senaraikan kategori item. [tool: astana_list_categories]
- `POST /category` — Cipta atau kemaskini kategori. [tool: astana_upsert_category] (wajib: category_name, created_at)
- `DELETE /category` — Padam kategori. [tool: astana_delete_category] (wajib: category_id)
- `GET /sub_category` — Senaraikan sub-kategori. [tool: astana_list_sub_categories]
- `POST /sub_category` — Cipta atau kemaskini sub-kategori. [tool: astana_upsert_sub_category] (wajib: category_id, sub_category_name, created_at)
- `DELETE /sub_category` — Padam sub-kategori. [tool: astana_delete_sub_category] (wajib: category_id, sub_category_id)
- `GET /measurements` — Senaraikan unit ukuran. [tool: astana_list_measurements]
- `POST /measurements` — Cipta atau kemaskini unit ukuran. [tool: astana_upsert_measurement] (wajib: measurement_name, weight_scale_enable, created_at)
- `DELETE /measurements` — Padam unit ukuran. [tool: astana_delete_measurement] (wajib: measurement_id)
- `GET /taxes` — Senaraikan cukai dan caj. [tool: astana_list_taxes]
- `POST /taxes` — Cipta atau kemaskini cukai/caj. [tool: astana_upsert_tax] (wajib: tax_type, tax_name, rate, shops, created_at)
- `DELETE /taxes` — Padam cukai mengikut kod dan shops. [tool: astana_delete_tax] (wajib: tax_code, shops)
- `GET /customers` — Senaraikan pelanggan. [tool: astana_list_customers]
- `POST /customers` — Cipta atau kemaskini pelanggan. Guna additional_fields untuk medan lain (address, city, id_type, dsb). [tool: astana_upsert_customer] (wajib: first_name)
- `DELETE /customers` — Padam pelanggan. [tool: astana_delete_customer] (wajib: customer_id)
- `GET /employee` — Senaraikan pekerja. [tool: astana_list_employees]
- `GET /suppliers` — Senaraikan pembekal. [tool: astana_list_suppliers]
- `POST /suppliers` — Cipta atau kemaskini pembekal. [tool: astana_upsert_supplier] (wajib: supplier_name, supplier_id, type, created_at)
- `DELETE /suppliers` — Padam pembekal. [tool: astana_delete_supplier] (wajib: supplier_id)
- `GET /products` — Senaraikan produk dengan field penuh. [tool: astana_list_products]
- `POST /products` — Cipta atau kemaskini produk. Guna additional_fields untuk medan penuh (components, modifiers_ids, option names, dsb). [tool: astana_upsert_product] (wajib: product_code, product_name, cost, stock_control, is_variant, shops)
- `POST /product_image` — Muat naik imej produk (multipart). `image` ialah path fail tempatan .png/.jpg/.jpeg. [tool: astana_upload_product_image] (wajib: product_code, image)
- `DELETE /product_image` — Padam imej produk. [tool: astana_delete_product_image] (wajib: product_code)
- `GET /receipts` — Senaraikan resit / invois. [tool: astana_list_receipts]
- `GET /void_receipts` — Senaraikan resit yang di-void. [tool: astana_list_void_receipts]
- `GET /credit_note_and_refund` — Senaraikan nota kredit dan bayaran balik tunai. [tool: astana_list_credit_notes]
- `POST /credit_note_and_refund` — Cipta nota kredit atau bayaran balik tunai. [tool: astana_create_credit_note] (wajib: receipt_number, shop_id, pos_device_id, receipt_type, transaction_date, line_products)
- `GET /orders` — Senaraikan pesanan. Julat tarikh wajib. [tool: astana_list_orders] (wajib: created_at_min, created_at_max)
- `GET /shops` — Senaraikan kedai merchant. [tool: astana_list_shops]
- `GET /payment_types` — Senaraikan jenis pembayaran. [tool: astana_list_payment_types]
- `POST /payment_types` — Cipta atau kemaskini jenis pembayaran. [tool: astana_upsert_payment_type] (wajib: payment_type_code, payment_type_name, payment_type_category, status)
- `DELETE /payment_types` — Padam jenis pembayaran. [tool: astana_delete_payment_type] (wajib: payment_type_id)
- `GET /order_types` — Senaraikan jenis pesanan. [tool: astana_list_order_types]
- `POST /order_types` — Cipta atau kemaskini jenis pesanan. [tool: astana_upsert_order_type] (wajib: order_type_name)
- `DELETE /order_types` — Padam jenis pesanan. [tool: astana_delete_order_type] (wajib: order_type_id)
- `GET /modifiers` — Senaraikan kumpulan modifier. [tool: astana_list_modifiers]
- `DELETE /modifiers` — Padam kumpulan modifier. [tool: astana_delete_modifier] (wajib: modifier_group_id)
- `GET /grn` — Senaraikan Good Receive Notes. [tool: astana_list_grn]
- `POST /grn` — Cipta Good Receive Note. [tool: astana_create_grn]
- `GET /inventory` — Dapatkan paras stok produk. [tool: astana_list_inventory] (wajib: shop_ids)
- `POST /inventory` — Kemaskini paras stok. [tool: astana_update_inventory] (wajib: inventory_levels)
- `GET /merchant` — Dapatkan maklumat merchant. [tool: astana_get_merchant]
- `POST /online_orders` — Hantar pesanan dalam talian. Guna additional_fields untuk medan penuh (fixed_charges, order_total_discounts, dsb). [tool: astana_place_online_order]
- `GET /online_order_status` — Semak status pesanan dalam talian. [tool: astana_get_online_order_status]
- `POST /cancel_online_order` — Batal pesanan dalam talian. [tool: astana_cancel_online_order] (wajib: system_unique_id)
- `GET /shifts` — Senaraikan shift POS dengan ringkasan tunai dan jualan. [tool: astana_list_shifts]
- `GET /pos_devices` — Senaraikan terminal POS. [tool: astana_list_pos_devices]
- `GET /timecards` — Senaraikan timecards (clock-in / clock-out) pekerja. [tool: astana_list_timecards]
- `GET /purchase_orders` — Senaraikan purchase order. [tool: astana_list_purchase_orders]

## Fail

- [OpenAPI 3.1 spec](openapi.json): spesifikasi mesin penuh
- [Dokumentasi penuh](astana-api.md): panduan + semua endpoint (Markdown)