{ "openapi": "3.1.0", "info": { "title": "Astana POS API", "version": "1.0", "description": "REST API untuk sistem POS Astana (POS, inventori, resit, pembayaran). Auth: header `Token: Bearer `. Dijana dari registry astana-mcp." }, "servers": [ { "url": "https://api.astanabiz.com/v1.0" } ], "security": [ { "TokenAuth": [] } ], "tags": [ { "name": "Webhooks" }, { "name": "Categories" }, { "name": "Sub categories" }, { "name": "Measurements" }, { "name": "Taxes" }, { "name": "Customers" }, { "name": "Employee" }, { "name": "Suppliers" }, { "name": "Product" }, { "name": "Product Image" }, { "name": "Receipts" }, { "name": "Orders" }, { "name": "Shops" }, { "name": "Payment types" }, { "name": "Order types" }, { "name": "Modifiers" }, { "name": "GRN" }, { "name": "Inventory" }, { "name": "Merchant" }, { "name": "Online orders" }, { "name": "Shifts" }, { "name": "POS Devices" }, { "name": "Timecards" }, { "name": "Purchase Orders" } ], "paths": { "/webhooks": { "get": { "operationId": "astana_get_webhook", "summary": "Dapatkan satu webhook mengikut ID.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "id, merchant_id, url, type, status, created_at, updated_at" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Unique identifier webhook.", "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_create_webhook", "summary": "Cipta webhook baharu.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Sama struktur seperti GET /webhooks" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "URL destinasi (uri)." }, "type": { "type": "string", "description": "inventory_levels.update | products.update | customers.update | receipts.update | credit_note.update" }, "status": { "type": "string", "description": "ENABLED | DISABLED" }, "master_username": { "type": "string", "description": "Master account username merchant (email)." } }, "required": [ "url", "type", "status", "master_username" ] } } } } }, "delete": { "operationId": "astana_delete_webhook", "summary": "Padam webhook mengikut ID.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "deleted_object_ids" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/category": { "get": { "operationId": "astana_list_categories", "summary": "Senaraikan kategori item.", "tags": [ "Categories" ], "responses": { "200": { "description": "categories[]: id, category_name, item_classification_code, created_at, updated_date" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "category_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 10, maksimum 250.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor pagination dari response sebelumnya.", "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_upsert_category", "summary": "Cipta atau kemaskini kategori.", "tags": [ "Categories" ], "responses": { "200": { "description": "id, name, item_classification_code, created_at" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category_name": { "type": "string" }, "item_classification_code": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "category_name", "created_at" ], "additionalProperties": true } } } } }, "delete": { "operationId": "astana_delete_category", "summary": "Padam kategori.", "tags": [ "Categories" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category_id": { "type": "string" } }, "required": [ "category_id" ] } } } } } }, "/sub_category": { "get": { "operationId": "astana_list_sub_categories", "summary": "Senaraikan sub-kategori.", "tags": [ "Sub categories" ], "responses": { "200": { "description": "sub_categories[]: id, category_name, sub_category_name, created_at, updated_date · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "sub_category_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 10, maksimum 250.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor pagination dari response sebelumnya.", "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_upsert_sub_category", "summary": "Cipta atau kemaskini sub-kategori.", "tags": [ "Sub categories" ], "responses": { "200": { "description": "id, category_name, sub_category_name, created_at" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category_id": { "type": "string" }, "sub_category_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "category_id", "sub_category_name", "created_at" ], "additionalProperties": true } } } } }, "delete": { "operationId": "astana_delete_sub_category", "summary": "Padam sub-kategori.", "tags": [ "Sub categories" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category_id": { "type": "string" }, "sub_category_id": { "type": "string" } }, "required": [ "category_id", "sub_category_id" ] } } } } } }, "/measurements": { "get": { "operationId": "astana_list_measurements", "summary": "Senaraikan unit ukuran.", "tags": [ "Measurements" ], "responses": { "200": { "description": "measurements[]: id, measurement_name, weight_scale_enable, created_at, updated_date · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "measurement_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 10, maksimum 250.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor pagination dari response sebelumnya.", "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_upsert_measurement", "summary": "Cipta atau kemaskini unit ukuran.", "tags": [ "Measurements" ], "responses": { "200": { "description": "id, measurement_name, weight_scale_enable, created_at, updated_at" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "measurement_name": { "type": "string" }, "weight_scale_enable": { "type": "integer", "description": "0 atau 1." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "measurement_name", "weight_scale_enable", "created_at" ], "additionalProperties": true } } } } }, "delete": { "operationId": "astana_delete_measurement", "summary": "Padam unit ukuran.", "tags": [ "Measurements" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "measurement_id": { "type": "string" } }, "required": [ "measurement_id" ] } } } } } }, "/taxes": { "get": { "operationId": "astana_list_taxes", "summary": "Senaraikan cukai dan caj.", "tags": [ "Taxes" ], "responses": { "200": { "description": "taxes[]: id, tax_type, tax_code, tax_name, rate, shops[], created_at · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "tax_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 10, maksimum 250.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor pagination dari response sebelumnya.", "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_upsert_tax", "summary": "Cipta atau kemaskini cukai/caj.", "tags": [ "Taxes" ], "responses": { "200": { "description": "id, tax_type, calculation_method, tax_code, tax_name, rate, shops, created_at" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_type": { "type": "string", "description": "TAX | CHARGE" }, "calculation_method": { "type": "string", "description": "ADDED | INCLUDED | FIXED" }, "tax_name": { "type": "string" }, "rate": { "type": "integer" }, "apply_tax_after_other_taxes": { "type": "integer", "description": "0 atau 1." }, "is_tax_price_change": { "type": "integer", "description": "0 atau 1." }, "shops": { "type": "array", "items": {}, "description": "Senarai uuid shop." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "tax_type", "tax_name", "rate", "shops", "created_at" ], "additionalProperties": true } } } } }, "delete": { "operationId": "astana_delete_tax", "summary": "Padam cukai mengikut kod dan shops.", "tags": [ "Taxes" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_code": { "type": "string" }, "shops": { "type": "array", "items": {}, "description": "Senarai shop id." } }, "required": [ "tax_code", "shops" ] } } } } } }, "/customers": { "get": { "operationId": "astana_list_customers", "summary": "Senaraikan pelanggan.", "tags": [ "Customers" ], "responses": { "200": { "description": "customers[]: id, customer_code, name, email, phone_number, total_spent, total_points, credit_limit, membership_status … · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "customer_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_upsert_customer", "summary": "Cipta atau kemaskini pelanggan. Guna additional_fields untuk medan lain (address, city, id_type, dsb).", "tags": [ "Customers" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "id_type": { "type": "string", "description": "NA | NRIC | PASSPORT | ARMY | MyPR | MyKAS | BRN" }, "id_number": { "type": "string" }, "credit_limit": { "type": "number" } }, "required": [ "first_name" ], "additionalProperties": true } } } } }, "delete": { "operationId": "astana_delete_customer", "summary": "Padam pelanggan.", "tags": [ "Customers" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string" } }, "required": [ "customer_id" ] } } } } } }, "/employee": { "get": { "operationId": "astana_list_employees", "summary": "Senaraikan pekerja.", "tags": [ "Employee" ], "responses": { "200": { "description": "employees[]: id, Name, User_Role, POS_Login_PIN, POS_user_name, Backoffice_login_email, Phone, shops · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "employee_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 10, maksimum 250.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor pagination dari response sebelumnya.", "schema": { "type": "string" } } ] } }, "/suppliers": { "get": { "operationId": "astana_list_suppliers", "summary": "Senaraikan pembekal.", "tags": [ "Suppliers" ], "responses": { "200": { "description": "suppliers[]: id, supplier_name, supplier_id, phone_number, email, type, address, created_at · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "supplier_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "updated_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_upsert_supplier", "summary": "Cipta atau kemaskini pembekal.", "tags": [ "Suppliers" ], "responses": { "200": { "description": "id, supplier_name, supplier_id, phone_number, email, type, address, created_at" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_name": { "type": "string" }, "supplier_id": { "type": "string" }, "type": { "type": "string", "description": "Cash | Credit | N/A" }, "created_at": { "type": "string", "format": "date-time" }, "phone_number": { "type": "string" }, "email": { "type": "string" } }, "required": [ "supplier_name", "supplier_id", "type", "created_at" ], "additionalProperties": true } } } } }, "delete": { "operationId": "astana_delete_supplier", "summary": "Padam pembekal.", "tags": [ "Suppliers" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": "string" } }, "required": [ "supplier_id" ] } } } } } }, "/products": { "get": { "operationId": "astana_list_products", "summary": "Senaraikan produk dengan field penuh.", "tags": [ "Product" ], "responses": { "200": { "description": "products[]: id, product_code, product_name, category, cost, barcode, measurement, tax_codes, variants, shops, components …" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "product_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "1-100, default 10.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_upsert_product", "summary": "Cipta atau kemaskini produk. Guna additional_fields untuk medan penuh (components, modifiers_ids, option names, dsb).", "tags": [ "Product" ], "responses": { "200": { "description": "OK" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_code": { "type": "string" }, "product_name": { "type": "string" }, "cost": { "type": "number" }, "stock_control": { "type": "boolean" }, "is_variant": { "type": "boolean" }, "shops": { "type": "array", "items": {} }, "variants": { "type": "array", "items": {} }, "tax_ids": { "type": "array", "items": {} } }, "required": [ "product_code", "product_name", "cost", "stock_control", "is_variant", "shops" ], "additionalProperties": true } } } } } }, "/product_image": { "post": { "operationId": "astana_upload_product_image", "summary": "Muat naik imej produk (multipart). `image` ialah path fail tempatan .png/.jpg/.jpeg.", "tags": [ "Product Image" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "product_code": { "type": "string" }, "image": { "type": "string", "format": "binary", "description": "Path fail tempatan pada mesin yang menjalankan server MCP." } }, "required": [ "product_code", "image" ] } } } } }, "delete": { "operationId": "astana_delete_product_image", "summary": "Padam imej produk.", "tags": [ "Product Image" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "product_code", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/receipts": { "get": { "operationId": "astana_list_receipts", "summary": "Senaraikan resit / invois.", "tags": [ "Receipts" ], "responses": { "200": { "description": "receipts[]: receipt_number, receipt_type, total_money, customer_id, line_products, payments …" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "receipt_numbers", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "shop_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/void_receipts": { "get": { "operationId": "astana_list_void_receipts", "summary": "Senaraikan resit yang di-void.", "tags": [ "Receipts" ], "responses": { "200": { "description": "receipts[] + deleted_by, deleted_date · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "receipt_numbers", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "shop_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/credit_note_and_refund": { "get": { "operationId": "astana_list_credit_notes", "summary": "Senaraikan nota kredit dan bayaran balik tunai.", "tags": [ "Receipts" ], "responses": { "200": { "description": "receipts[] · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "receipt_numbers", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "shop_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_create_credit_note", "summary": "Cipta nota kredit atau bayaran balik tunai.", "tags": [ "Receipts" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receipt_number": { "type": "string" }, "shop_id": { "type": "string" }, "pos_device_id": { "type": "string" }, "receipt_type": { "type": "string", "description": "CASH_REFUND | CREDIT_NOTE" }, "transaction_date": { "type": "string", "format": "date-time" }, "line_products": { "type": "array", "items": {}, "description": "[{product_id, product_line_no, quantity, comment}]" } }, "required": [ "receipt_number", "shop_id", "pos_device_id", "receipt_type", "transaction_date", "line_products" ], "additionalProperties": true } } } } } }, "/orders": { "get": { "operationId": "astana_list_orders", "summary": "Senaraikan pesanan. Julat tarikh wajib.", "tags": [ "Orders" ], "responses": { "200": { "description": "orders[]: order_number, order_date_time, total_money, customer_id, line_products, payments, order_status …" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "order_numbers", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "shop_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/shops": { "get": { "operationId": "astana_list_shops", "summary": "Senaraikan kedai merchant.", "tags": [ "Shops" ], "responses": { "200": { "description": "shops[]: id, shop_name, address, phone_number, city, email, longitude, latitude, terminal_list, is_enable" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "shop_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "updated_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/payment_types": { "get": { "operationId": "astana_list_payment_types", "summary": "Senaraikan jenis pembayaran.", "tags": [ "Payment types" ], "responses": { "200": { "description": "payment_types[]: id, payment_type_name, shops, created_date, updated_date" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "payment_type_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_upsert_payment_type", "summary": "Cipta atau kemaskini jenis pembayaran.", "tags": [ "Payment types" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_type_code": { "type": "string" }, "payment_type_name": { "type": "string" }, "payment_type_category": { "type": "string", "description": "cth: Cash, Card, Cheque." }, "status": { "type": "integer", "description": "0 atau 1." } }, "required": [ "payment_type_code", "payment_type_name", "payment_type_category", "status" ], "additionalProperties": true } } } } }, "delete": { "operationId": "astana_delete_payment_type", "summary": "Padam jenis pembayaran.", "tags": [ "Payment types" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_type_id": { "type": "string" } }, "required": [ "payment_type_id" ] } } } } } }, "/order_types": { "get": { "operationId": "astana_list_order_types", "summary": "Senaraikan jenis pesanan.", "tags": [ "Order types" ], "responses": { "200": { "description": "order_type[]: id, order_type_name, is_enable, created_at, updated_date · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "order_type_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 10, maksimum 250.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor pagination dari response sebelumnya.", "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_upsert_order_type", "summary": "Cipta atau kemaskini jenis pesanan.", "tags": [ "Order types" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_type_name": { "type": "string" }, "status": { "type": "integer", "description": "0 atau 1." } }, "required": [ "order_type_name" ], "additionalProperties": true } } } } }, "delete": { "operationId": "astana_delete_order_type", "summary": "Padam jenis pesanan.", "tags": [ "Order types" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_type_id": { "type": "string" } }, "required": [ "order_type_id" ] } } } } } }, "/modifiers": { "get": { "operationId": "astana_list_modifiers", "summary": "Senaraikan kumpulan modifier.", "tags": [ "Modifiers" ], "responses": { "200": { "description": "modifier_groups[]: id, modifier_group_name, modifiers, shops, created_date, updated_date" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "modifier_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "delete": { "operationId": "astana_delete_modifier", "summary": "Padam kumpulan modifier.", "tags": [ "Modifiers" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modifier_group_id": { "type": "string" } }, "required": [ "modifier_group_id" ] } } } } } }, "/grn": { "get": { "operationId": "astana_list_grn", "summary": "Senaraikan Good Receive Notes.", "tags": [ "GRN" ], "responses": { "200": { "description": "grn_list[]: grn_id, shop_id, supplier_id, grn_number, grn_amount, grn_date, grn_status, items, additional_cost · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "shop_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "grn_numbers", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_create_grn", "summary": "Cipta Good Receive Note.", "tags": [ "GRN" ], "responses": { "200": { "description": "success" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": "string" }, "shop_id": { "type": "string" }, "grn_date": { "type": "string", "format": "date-time" }, "payment_method_id": { "type": "string" }, "grn_total": { "type": "number" }, "items": { "type": "array", "items": {}, "description": "[{product_id, qty, unit_cost, total_unit_cost, expire_mode, expire_date}]" } }, "additionalProperties": true } } } } } }, "/inventory": { "get": { "operationId": "astana_list_inventory", "summary": "Dapatkan paras stok produk.", "tags": [ "Inventory" ], "responses": { "200": { "description": "inventory_levels[]: product_id, shop_id, product_code, in_stock · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "product_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "shop_ids", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "astana_update_inventory", "summary": "Kemaskini paras stok.", "tags": [ "Inventory" ], "responses": { "200": { "description": "code, details" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inventory_levels": { "type": "array", "items": {}, "description": "[{shop_id, product_id, in_stock}]" } }, "required": [ "inventory_levels" ], "additionalProperties": true } } } } } }, "/merchant": { "get": { "operationId": "astana_get_merchant", "summary": "Dapatkan maklumat merchant.", "tags": [ "Merchant" ], "responses": { "200": { "description": "merchant[]: id, business_name, email, country, currency, created_at" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } } } }, "/online_orders": { "post": { "operationId": "astana_place_online_order", "summary": "Hantar pesanan dalam talian. Guna additional_fields untuk medan penuh (fixed_charges, order_total_discounts, dsb).", "tags": [ "Online orders" ], "responses": { "200": { "description": "success · order_reference_id, order_reference_number, system_unique_id, order_date" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "shop_id": { "type": "string" }, "order_reference_number": { "type": "string" }, "order_reference_id": { "type": "string" }, "order_total": { "type": "number" }, "channel_order_status_id": { "type": "integer", "description": "Sepatutnya 0." }, "channel_order_status_name": { "type": "string", "description": "Sepatutnya \"pending\"." }, "customer_phone": { "type": "string" }, "order_date_time": { "type": "string", "format": "date-time" }, "order_items": { "type": "array", "items": {} }, "order_payments": { "type": "array", "items": {} } }, "additionalProperties": true } } } } } }, "/online_order_status": { "get": { "operationId": "astana_get_online_order_status", "summary": "Semak status pesanan dalam talian.", "tags": [ "Online orders" ], "responses": { "200": { "description": "order_status[]: system_unique_id, order_reference_id, order_reference_number, order_status, status_name · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "system_unique_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 10, maksimum 250.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor pagination dari response sebelumnya.", "schema": { "type": "string" } } ] } }, "/cancel_online_order": { "post": { "operationId": "astana_cancel_online_order", "summary": "Batal pesanan dalam talian.", "tags": [ "Online orders" ], "responses": { "200": { "description": "success · code, details, order_reference_id, order_reference_number" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "system_unique_id": { "type": "string" } }, "required": [ "system_unique_id" ] } } } } } }, "/shifts": { "get": { "operationId": "astana_list_shifts", "summary": "Senaraikan shift POS dengan ringkasan tunai dan jualan.", "tags": [ "Shifts" ], "responses": { "200": { "description": "employees[] (kunci wrapper sebenar API Astana): id, store_id, opened_at, closed_at, starting_cash, expected_cash, gross_sales, net_sales, payments … · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "shift_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pos_device_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/pos_devices": { "get": { "operationId": "astana_list_pos_devices", "summary": "Senaraikan terminal POS.", "tags": [ "POS Devices" ], "responses": { "200": { "description": "terminals[]: Shop_name, POS_name, pos_key, status" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "pos_keys", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 10, maksimum 250.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor pagination dari response sebelumnya.", "schema": { "type": "string" } } ] } }, "/timecards": { "get": { "operationId": "astana_list_timecards", "summary": "Senaraikan timecards (clock-in / clock-out) pekerja.", "tags": [ "Timecards" ], "responses": { "200": { "description": "timecards[]: id, shop_id, employee_name, clock_in, clock_out, total_hours · cursor" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "shop_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "employee_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/purchase_orders": { "get": { "operationId": "astana_list_purchase_orders", "summary": "Senaraikan purchase order.", "tags": [ "Purchase Orders" ], "responses": { "200": { "description": "purchase_orders[]: po_id, shop_id, supplier_name, po_number, po_amount, po_date, po_status, items …" }, "401": { "description": "UNAUTHORIZED — token tiada/tidak sah" }, "429": { "description": "Had kadar dilampaui (300/300s)" } }, "parameters": [ { "name": "shop_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "po_numbers", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] } } }, "components": { "securitySchemes": { "TokenAuth": { "type": "apiKey", "in": "header", "name": "Token", "description": "Nilai header: `Bearer `" } } } }