### Open Keruyun API URL Construction Example Source: https://open.keruyun.com/docs/zh/tseUEXQBzPVmqdQuLVjE This example demonstrates how to construct a URL for Open Keruyun API calls, incorporating common parameters like appKey, shopIdenty, timestamp, version, and sign. It illustrates the order of parameters for shop authorization. ```URL 域名+URI+appKey=301001&shopIdenty=247900001&version=2.0×tamp=1425635264&sign=6512bd43d9caa6e02c990b0a82652dca6512bd43d9caa6e02c990b0a82652dca 如：https://openapi.keruyun.com/open/v1/crm/fetchCoupInstanceDetail?appKey=add847549e27ad89bc054b0ee6a32233&shopIdenty=810324111×tamp=1568171280001&version=2.0&sign=1e977750fa488a792426ccbb580cc5d73b7a5d2d88ff46ea76bc6ddee1c8e837 ``` -------------------------------- ### Sign Calculation Example - API Request Source: https://open.keruyun.com/docs/zh/InxgrXYBUYesgvE2gN9R Demonstrates how to construct the 'sign' value for an API request by concatenating common and business parameters, followed by SHA256 hashing. The example shows the final URL with the calculated sign. ```text sign=SHA256(appKey301001shopIdenty247900001timestamp1425635264version2.0body{"aaa":1,"name"：周}66e53b22f1496d183e71b4ab90f4acf7) ``` -------------------------------- ### Example Parameter Concatenation - Merchant Authorization Source: https://open.keruyun.com/docs/zh/InxgrXYBUYesgvE2gN9R Illustrates the process of concatenating parameters for the merchant authorization interface before SHA256 signing. This includes appKey, shopIdenty, timestamp, version, body (as a JSON string), and token. ```text appKey：7857ca1808d370e2501290bc853eecdc shopIdenty：810094162 timestamp：1528683797798 version：2.0 body：{"aaa":1} token：66e53b22f1496d183e71b4ab90f4acf7 ``` -------------------------------- ### Business Request Example (JSON) Source: https://open.keruyun.com/docs/zh/WMeUEXQBzPVmqdQu2FlA_b=cater This JSON object demonstrates a typical request payload for business operations, specifying user identification and login type. It is used as input for the API. ```json { "loginId":"18698442598", "loginType":0 } ``` -------------------------------- ### Example Business Parameters JSON Source: https://open.keruyun.com/docs/zh/kXcd2YIBQmWK-9w5YZ_R Illustrates the structure for providing business parameters in a JSON format. This includes fields like brandIdenty, operation, and dishTypeIds, which are specific to certain API calls. ```json { "brandIdenty":32295, "operation":1, "dishTypeIds":[261813213542561792,263716834186703872] } ``` -------------------------------- ### API Response Example (JSON) Source: https://open.keruyun.com/docs/zh/WMeUEXQBzPVmqdQu2FlA_b=cater This JSON object illustrates a successful API response, including a return code and detailed customer information. The 'result' field contains CRM user base information. ```json { "code": 1, "result": { "brandId": 3268, "memberId": 5757576, "customerId": 800000095, "customerMainId": 800000095, "customerName": "2ewe", "commercialName": "门店1", "mobile": "18987668844", "sex": 1, "levelId": 8123812, "isDisable": 1 } } ``` -------------------------------- ### Example Parameter Concatenation - Brand Authorization Source: https://open.keruyun.com/docs/zh/InxgrXYBUYesgvE2gN9R Illustrates the process of concatenating parameters for the brand authorization interface before SHA256 signing. This includes appKey, brandId, timestamp, version, body (as a JSON string), and token. ```text appKey：7857ca1808d370e2501290bc853eecdc brandId：32296 timestamp：1528683797798 version：2.0 token：66e53b22f1496d183e71b4ab90f4acf7 body：{"aaa":1} ``` -------------------------------- ### GET /v1/stores/{store_id}/tables Source: https://open.keruyun.com/docs/zh/tseUEXQBzPVmqdQuLVjE This endpoint retrieves a list of tables within a specific store. Use the store ID to get the list of tables and their corresponding details. ```APIDOC ## GET /v1/stores/{store_id}/tables ### Description Retrieves a list of tables within a specific store. ### Method GET ### Endpoint /v1/stores/{store_id}/tables ### Parameters #### Path Parameters - **store_id** (integer) - Required - The ID of the store to retrieve tables for. ### Request Example ```json {} ``` ### Response #### Success Response (200) - **table_id** (integer) - The ID of the table. - **table_name** (string) - The name of the table. #### Response Example ```json [ { "table_id": 1, "table_name": "Table 1" }, { "table_id": 2, "table_name": "Table 2" } ] ``` ``` -------------------------------- ### Common FAQ Source: https://open.keruyun.com/docs/zh/WMeUEXQBzPVmqdQu2FlA_b=cater Frequently asked questions covering various aspects of the platform, including orders, members, products, and authorization. ```APIDOC ## Common FAQ ### Description This section addresses common questions encountered by developers, categorized for easy navigation. #### Order Related ### Description Frequently asked questions pertaining to order processing, status, and management. #### Member Related ### Description Frequently asked questions concerning member management, profiles, and loyalty programs. #### Product Related ### Description Frequently asked questions about product information, inventory, and pricing. #### Authorization Related ### Description Frequently asked questions related to API authorization, token management, and permissions. #### Other ### Description Miscellaneous frequently asked questions not covered in other categories. ``` -------------------------------- ### System Integration Source: https://open.keruyun.com/docs/zh/cHMn4HUBczuQcdqkVT4j_b=cater&v=v2 APIs for system integrations, including OAuth, merchant authorization. ```APIDOC ## System Integration ### Description APIs facilitating system integrations, covering authentication and authorization processes. ### OAuth Silent Login #### Get Access Token - **Endpoint**: /api/integration/oauth/access_token - **Method**: POST #### Refresh Access Token - **Endpoint**: /api/integration/oauth/refresh_token - **Method**: POST #### Get User Information - **Endpoint**: /api/integration/oauth/userinfo - **Method**: GET ### Merchant Authorization #### Query Authorized Organizations for Application - **Endpoint**: /api/integration/merchant/authorized_organizations - **Method**: GET #### Get Authorization QR Code - **Endpoint**: /api/integration/merchant/authorization_qr - **Method**: GET ``` -------------------------------- ### Smart Edition API Documentation Source: https://open.keruyun.com/docs/zh/WMeUEXQBzPVmqdQu2FlA_b=cater Comprehensive API documentation for the Smart Edition, including headquarters and store basic information, organization and employee management, products, orders, and more. ```APIDOC ## Smart Edition API Documentation ### Description This section details the APIs available for the Smart Edition, covering various modules for managing business operations. ### Headquarters Basic Information #### Query Brand Information ### Description Retrieves details about a specific brand. ### Store Basic Information #### Query Store List by Brand ### Description Fetches a list of stores associated with a given brand. #### Store Basic Information API List ### Description Provides a list of available APIs for managing store basic information. #### Get Store Details by Store ID ### Description Retrieves detailed information for a specific store using its ID. #### Query Store Table List ### Description Fetches a list of tables within a specified store. #### Get Table Information by Table ID ### Description Retrieves details for a specific table using its ID. #### Query Store Service Fee List ### Description Fetches a list of service fees applicable to a store. #### Get Store Service Fee Details by Service Fee ID ### Description Retrieves detailed information for a specific store service fee. #### Query Super Administrators ### Description Fetches information about super administrators for a store or brand. ### Organization and Employee #### Store Archives ##### Store Archives API List ### Description Lists all available APIs for managing store archives. ##### Query Organization Tree ### Description Retrieves the organizational hierarchy, including stores and departments. ##### Query Store Information (Including Third-Party Organization ID) ### Description Fetches store information, including any associated third-party organization IDs. ##### Organization Information Notification ### Description Receives notifications about changes to organization information. ##### Modify Store Basic Information ### Description Allows modification of a store's basic information. ##### Third-Party Custom Organization ID Change Event ### Description Handles events related to changes in third-party custom organization IDs. #### Headquarters Employee Management ##### Headquarters Employee Management API List ### Description Lists all available APIs for managing employees at the headquarters level. ##### Headquarters - Create Employee ### Description Creates a new employee record at the headquarters. ##### Headquarters - Enable Employee ### Description Enables an existing employee account at the headquarters. ##### Headquarters - Modify Employee Information ### Description Modifies the information of an existing headquarters employee. ##### Headquarters - Query Employee Details ### Description Retrieves the details of a specific headquarters employee. ##### Headquarters - Disable Employee ### Description Disables an existing employee account at the headquarters. ##### Headquarters - Query Employee List ### Description Fetches a list of employees at the headquarters. ##### Employee Information Change Notification ### Description Receives notifications about changes to employee information. #### Store Employee Management ##### Store Employee Management API List ### Description Lists all available APIs for managing employees at the store level. ##### Store - Create Employee ### Description Creates a new employee record at the store level. ##### Store - Modify Employee Information ### Description Modifies the information of an existing store employee. ##### Store - Disable Employee ### Description Disables an existing employee account at the store level. ##### Store - Query Employee Details ### Description Retrieves the details of a specific store employee. ##### Store - Enable Employee ### Description Enables an existing employee account at the store level. ##### Store - Query Employee List ### Description Fetches a list of employees at the store level. ### Product #### Query Store Product Information (Paginated) ### Description Retrieves a paginated list of product information for a store. #### Query Store Product Details ### Description Fetches detailed information for a specific product in a store. #### Query Store Product Category Information ### Description Retrieves information about product categories within a store. #### Store Product Open Message ### Description Handles open messages related to store products. #### Query Store Product Inventory ### Description Fetches the inventory levels for products in a store. #### Product Inventory Information Change ### Description Handles notifications about changes in product inventory. #### Batch Price Modification for Store Products ### Description Allows for batch modification of prices for store products. ### Order Information #### Query Order Details (Reporting) ### Description Retrieves order details for reporting purposes. #### Query Order Details (Transaction) ### Description Retrieves order details for transaction processing. #### Query Order List ### Description Fetches a list of orders. ##### Order Re-print Notification ### Description Handles notifications for order re-prints. ##### Order Change Event Synchronization (Reporting) ### Description Synchronizes order change events for reporting. ##### Order Change Event Synchronization (Transaction) ### Description Synchronizes order change events for transaction processing. ### kpos Device Management #### Device Binding ### Description Binds a device to the kpos system. #### Query Device by SN ### Description Retrieves device information using its serial number. #### Unbind Device by Device ID ### Description Unbinds a device from the kpos system using its ID. ### Kitchen Display System (KDS) #### Local Area Network Mode ##### Query Order by Pickup Code ### Description Retrieves an order using its pickup code in LAN mode. ##### Start Delivery ### Description Initiates the delivery process for an order in LAN mode. ##### End Delivery ### Description Marks the completion of delivery for an order in LAN mode. #### Cloud Public Network Mode ##### Query Order by Pickup Code ### Description Retrieves an order using its pickup code in cloud mode. ##### Start Delivery ### Description Initiates the delivery process for an order in cloud mode. ##### End Delivery ### Description Marks the completion of delivery for an order in cloud mode. ### Pre-ordering #### Create/Modify Open Pre-order Menu ### Description Creates or modifies an open pre-order menu. #### Query Pre-order Menu ### Description Retrieves information about pre-order menus. ##### Delete Pre-order Menu ### Description Deletes a pre-order menu. ##### Pre-order Operation Event ### Description Handles events related to pre-order operations. ### C-end Reservation #### C-end Reservation Order Placement ### Description Allows customers to place reservations via the C-end interface. #### Cancel C-end Reservation ### Description Allows cancellation of C-end reservations. ##### C-end Reservation Status Change Message ### Description Receives messages about changes in C-end reservation status. ##### Query C-end Reservation Order Details ### Description Retrieves details for a specific C-end reservation order. ##### Query C-end Reservation Order List (Paginated) ### Description Fetches a paginated list of C-end reservation orders. ### kpos Business Compensation #### Query Request Execution Result for Timeout Scenarios ### Description Retrieves the execution result for requests that timed out in kpos business compensation scenarios. ### Member #### Member API List ### Description Lists all available APIs for member management. ##### Member Creation ### Description Creates a new member profile. ##### Modify Member Information ### Description Modifies the information of an existing member. ##### Batch Query Member Details ### Description Retrieves details for multiple members in a single request. ##### Query Member Tag List ### Description Fetches a list of tags associated with members. ##### Query Member Card Scheme Level Rules ### Description Retrieves the rules for member card schemes and levels. ##### Member Asset Query ### Description Queries a member's assets, such as points or coupons. ##### Member Query ### Description Searches for member information. ##### Stored Value Top-up Interface ### Description Handles top-up operations for member stored value accounts. ##### Member Stored Value Consumption Interface ### Description Handles consumption operations for member stored value accounts. ##### Member Stored Value Reversal Interface ### Description Handles reversal operations for member stored value transactions. ###### Points ####### Add Points ### Description Adds points to a member's account. ####### Deduct Points ### Description Deducts points from a member's account. ####### Query Points Rules ### Description Retrieves the rules for point accrual and redemption. ####### Member Query Points Flow ### Description Queries the transaction history of member points. ###### Coupons ####### Coupon Template ######## Query Coupon Template Details ### Description Retrieves detailed information for a specific coupon template. ######## Query Coupon Template List ### Description Fetches a list of available coupon templates. ######## Coupon Template Change Event Notification ### Description Receives notifications about changes to coupon templates. ######## Query Coupon Template Applicable Stores ### Description Retrieves the stores where a coupon template is applicable. ######## Query Coupon Template Applicable Products ### Description Retrieves the products for which a coupon template is applicable. ####### Coupon Instance ######## Void Coupon ### Description Voids a specific coupon instance. ######## Issue Coupon ### Description Issues a coupon instance to a member. ######## Query Coupon Instance Details ### Description Retrieves detailed information for a specific coupon instance. ######## Query Coupon Instance List ### Description Fetches a list of coupon instances. ### Third-Party Coupons #### Query Coupon ### Description Queries information about third-party coupons. #### Redeem Coupon ### Description Redeems a third-party coupon. #### Unredeem Coupon ### Description Reverses the redemption of a third-party coupon. ### Third-Party Members #### Member Query ##### Member and Asset Query ### Description Queries member information and associated assets. #### Member Asset Payment ##### Member Asset Redemption ### Description Redeems member assets. ##### Member Asset Unredemption ### Description Reverses the redemption of member assets. ##### Query Redemption Result ### Description Retrieves the result of an asset redemption operation. ### Supply Chain 2.0 #### Loss Reporting Outbound Query ##### Loss Reporting Outbound Order List ### Description Fetches a list of loss reporting outbound orders. ##### Loss Reporting Outbound Order Details ### Description Retrieves details for a specific loss reporting outbound order. #### Other Inbound/Outbound Query ##### Other Inbound Order List ### Description Fetches a list of other inbound orders. ##### Other Inbound Order Details ### Description Retrieves details for a specific other inbound order. ##### Other Outbound Order Details ### Description Retrieves details for a specific other outbound order. ##### Other Outbound Order List ### Description Fetches a list of other outbound orders. #### Inter-organization Transfer Query ##### Inter-organization Transfer Order List ### Description Fetches a list of inter-organization transfer orders. ##### Inter-organization Transfer Order Details ### Description Retrieves details for a specific inter-organization transfer order. #### Inventory Profit/Loss Query ##### Inventory List ### Description Fetches a list of inventory items. ##### Inventory Details ### Description Retrieves details for a specific inventory item. #### Inter-organization Transfer Query (Revised) ##### Inter-organization Transfer Outbound Order Details ### Description Retrieves details for an inter-organization transfer outbound order. ##### Inter-organization Transfer Inbound Order List ### Description Fetches a list of inter-organization transfer inbound orders. ##### Inter-organization Transfer Outbound Order List ### Description Fetches a list of inter-organization transfer outbound orders. ##### Inter-organization Transfer Inbound Order Details ### Description Retrieves details for an inter-organization transfer inbound order. #### POS Deduction Query ##### Consumption Outbound Order Details ### Description Retrieves details for a consumption outbound order. ##### Consumption Outbound Order List ### Description Fetches a list of consumption outbound orders. ``` -------------------------------- ### Get Store/Brand Token Source: https://open.keruyun.com/docs/zh/WMeUEXQBzPVmqdQu2FlA_b=cater Obtain authentication tokens required for accessing store and brand-specific APIs. ```APIDOC ## Get Store/Brand Token ### Description This API allows you to obtain authentication tokens necessary for accessing store and brand-specific resources. These tokens are crucial for authorizing your requests. ### Method POST (Assumed, typically for token generation) ### Endpoint `/oauth/token` (Example endpoint, actual may vary) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **grant_type** (string) - Required - Typically 'client_credentials' or similar for obtaining access tokens. - **client_id** (string) - Required - Your application's client ID. - **client_secret** (string) - Required - Your application's client secret. ### Request Example ```json { "grant_type": "client_credentials", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET" } ``` ### Response #### Success Response (200) - **access_token** (string) - The obtained access token. - **token_type** (string) - The type of token (e.g., 'Bearer'). - **expires_in** (integer) - The lifetime of the token in seconds. #### Response Example ```json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 7200 } ``` ``` -------------------------------- ### GET /api/inventory/query Source: https://open.keruyun.com/docs/zh/InxgrXYBUYesgvE2gN9R This endpoint is used to query inventory levels. It allows retrieving the current stock level of items. ```APIDOC ## GET /api/inventory/query ### Description Queries inventory levels for specified items. ### Method GET ### Endpoint /api/inventory/query ### Query Parameters - **item_id** (integer) - Optional - The ID of the item to query. If not provided, all items will be returned. ### Request Example /api/inventory/query?item_id=123 ### Response #### Success Response (200) - **item_id** (integer) - The ID of the item. - **quantity** (integer) - The current quantity in stock. #### Response Example ```json { "item_id": 123, "quantity": 95 } ``` ``` -------------------------------- ### System Integration API Source: https://open.keruyun.com/docs/zh/WMeUEXQBzPVmqdQu2FlA_b=cater APIs for system integration, including OAuth single sign-on and merchant authorization. ```APIDOC ## System Integration API ### Description APIs for system integration purposes, including OAuth for single sign-on and merchant authorization flows. ### Endpoints * **4.3.16.1**: OAuth Single Sign-On * **4.3.16.1.1**: Get Access Token * **4.3.16.1.2**: Refresh Access Token * **4.3.16.1.3**: Get User Information * **4.3.16.2**: Merchant Authorization * **4.3.16.2.1**: Query Authorized Institutions for Application * **4.3.16.2.2**: Get Authorization QR Code ``` -------------------------------- ### Kitchen Display System (KDS) APIs Source: https://open.keruyun.com/docs/zh/iMeYEXQBzPVmqdQufV3I APIs for interacting with the Kitchen Display System for order preparation. ```APIDOC ## GET /api/kitchen/orders ### Description Retrieves orders from the kitchen display system based on the mode (LAN or Cloud). ### Method GET ### Endpoint /api/kitchen/orders ### Parameters #### Query Parameters - **mode** (string) - Required - The mode to query orders from ('LAN' or 'Cloud'). - **pickupCode** (string) - Optional - Filter orders by pickup code. ### Response #### Success Response (200) - **orders** (array) - List of order objects relevant to the kitchen display. - **orderId** (string) - Unique identifier for the order. - **pickupCode** (string) - The code for picking up the order. - **items** (array) - Items included in the order. - **status** (string) - Current status of the order preparation. #### Response Example { "orders": [ { "orderId": "ordK101", "pickupCode": "P789", "items": [ {"name": "Burger", "quantity": 1}, {"name": "Fries", "quantity": 1} ], "status": "in_progress" } ] } ## POST /api/kitchen/order/{orderId}/start-delivery ### Description Marks an order as 'in progress' for delivery in the kitchen system. ### Method POST ### Endpoint /api/kitchen/order/{orderId}/start-delivery ### Parameters #### Path Parameters - **orderId** (string) - Required - The ID of the order to update. ### Response #### Success Response (200) - **message** (string) - Confirmation message indicating the order status update. #### Response Example { "message": "Order ordK101 marked as in progress for delivery." } ## POST /api/kitchen/order/{orderId}/complete-delivery ### Description Marks an order as 'completed' for delivery in the kitchen system. ### Method POST ### Endpoint /api/kitchen/order/{orderId}/complete-delivery ### Parameters #### Path Parameters - **orderId** (string) - Required - The ID of the order to update. ### Response #### Success Response (200) - **message** (string) - Confirmation message indicating the order is completed. #### Response Example { "message": "Order ordK101 delivery completed." } ``` -------------------------------- ### OAUTH Authorization Service APIs Source: https://open.keruyun.com/docs/zh/kXcd2YIBQmWK-9w5YZ_R APIs for OAuth 2.0 authorization, including getting user info, handling callbacks, and obtaining tokens. ```APIDOC ## OAUTH Authorization Service APIs ### Description APIs related to the OAuth 2.0 authorization flow. ### Endpoints - `/oauth/user/info` (GET): Get user information. - `/oauth/login/callback` (GET): Successful login callback. - `/oauth/code` (GET): Get authorization code. - `/oauth/token` (POST): Get access token. ``` -------------------------------- ### Product Management Source: https://open.keruyun.com/docs/zh/MMeUEXQBzPVmqdQutFlp APIs for managing products, including querying, pricing, and inventory. ```APIDOC ## GET /api/products ### Description Query products available in a store, with pagination. ### Method GET ### Endpoint /api/products ### Parameters #### Query Parameters - **storeId** (string) - Required - The ID of the store. - **page** (integer) - Optional - The page number for pagination. Defaults to 1. - **pageSize** (integer) - Optional - The number of items per page. Defaults to 20. ### Response #### Success Response (200) - **products** (array) - List of product objects. - **id** (string) - The unique identifier for the product. - **name** (string) - The name of the product. - **price** (number) - The current price of the product. #### Response Example ```json { "products": [ { "id": "prod-xyz", "name": "Cheeseburger", "price": 8.99 } ] } ``` ``` ```APIDOC ## POST /api/products/batch-price-update ### Description Update prices for multiple products in a store in a single request. ### Method POST ### Endpoint /api/products/batch-price-update ### Parameters #### Request Body - **storeId** (string) - Required - The ID of the store. - **priceUpdates** (array) - Required - A list of product price updates. - **productId** (string) - Required - The ID of the product. - **newPrice** (number) - Required - The new price for the product. ### Request Example ```json { "storeId": "store-abc", "priceUpdates": [ { "productId": "prod-xyz", "newPrice": 9.50 }, { "productId": "prod-pqr", "newPrice": 5.00 } ] } ``` ### Response #### Success Response (200) - **message** (string) - Confirmation message indicating the batch update status. #### Response Example ```json { "message": "Batch price update processed successfully." } ``` ``` -------------------------------- ### GET /v1/stores/{store_id}/servicefees Source: https://open.keruyun.com/docs/zh/tseUEXQBzPVmqdQuLVjE This endpoint retrieves a list of service fees configured for a specific store. Useful for understanding pricing and additional charges. ```APIDOC ## GET /v1/stores/{store_id}/servicefees ### Description Retrieves a list of service fees configured for a specific store. ### Method GET ### Endpoint /v1/stores/{store_id}/servicefees ### Parameters #### Path Parameters - **store_id** (integer) - Required - The ID of the store to retrieve service fees for. ### Request Example ```json {} ``` ### Response #### Success Response (200) - **service_fee_id** (integer) - The ID of the service fee. - **service_fee_name** (string) - The name of the service fee. #### Response Example ```json [ { "service_fee_id": 1, "service_fee_name": "Gratuity" }, { "service_fee_id": 2, "service_fee_name": "Service Charge" } ] ``` ``` -------------------------------- ### System Integration - OAuth Source: https://open.keruyun.com/docs/zh/kXcd2YIBQmWK-9w5YZ_R APIs for system integration, focusing on OAuth for authentication and user information retrieval. ```APIDOC ## 4.3.16.1 OAuth SSO ### Description APIs for OAuth-based Single Sign-On, including obtaining and refreshing access tokens, and retrieving user information. ### Method POST / GET ### Endpoint /api/oauth/access_token /api/oauth/refresh_token /api/oauth/user_info ### Parameters #### Request Body - **client_id** (string) - Required - Client identifier. - **client_secret** (string) - Required - Client secret. - **grant_type** (string) - Required - Grant type (e.g., 'authorization_code'). - **code** (string) - Required - Authorization code. - **refresh_token** (string) - Required for refresh - Refresh token. ### Request Example ```json { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "grant_type": "authorization_code", "code": "AUTHORIZATION_CODE" } ``` ### Response #### Success Response (200) - **access_token** (string) - The obtained access token. - **refresh_token** (string) - The refresh token. - **expires_in** (integer) - Token expiration time in seconds. - **user_info** (object) - User details. #### Response Example ```json { "access_token": "ACCESS_TOKEN_HERE", "expires_in": 3600 } ``` ``` -------------------------------- ### GET /v1/stores/{store_id} Source: https://open.keruyun.com/docs/zh/tseUEXQBzPVmqdQuLVjE This endpoint retrieves details for a single store by its ID. This includes store name, address, contact details, and other relevant information. ```APIDOC ## GET /v1/stores/{store_id} ### Description Retrieves details for a single store by its ID. ### Method GET ### Endpoint /v1/stores/{store_id} ### Parameters #### Path Parameters - **store_id** (integer) - Required - The ID of the store to retrieve. ### Request Example ```json {} ``` ### Response #### Success Response (200) - **store_name** (string) - The name of the store. - **store_address** (string) - The address of the store. #### Response Example ```json { "store_id": 456, "store_name": "Store 1", "store_address": "123 Main St" } ``` ``` -------------------------------- ### GET /v1/headquarters/brands/{brand_id} Source: https://open.keruyun.com/docs/zh/tseUEXQBzPVmqdQuLVjE This endpoint retrieves information about a specific brand. Use the brand ID to fetch details such as name, description, and other relevant information. ```APIDOC ## GET /v1/headquarters/brands/{brand_id} ### Description Retrieves information about a specific brand using its ID. ### Method GET ### Endpoint /v1/headquarters/brands/{brand_id} ### Parameters #### Path Parameters - **brand_id** (integer) - Required - The ID of the brand to retrieve. ### Request Example ```json {} ``` ### Response #### Success Response (200) - **brand_name** (string) - The name of the brand. - **brand_description** (string) - A description of the brand. #### Response Example ```json { "brand_id": 123, "brand_name": "Example Brand", "brand_description": "A sample brand description." } ``` ``` -------------------------------- ### Kitchen Display System (KDS) APIs Source: https://open.keruyun.com/docs/zh/WMeUEXQBzPVmqdQu2FlA APIs for interacting with the Kitchen Display System, supporting both local network and cloud modes for order management. ```APIDOC ## GET /api/kds/local/order/pickup-code/{pickupCode} ### Description In local network mode, retrieves order details using a pickup code. ### Method GET ### Endpoint /api/kds/local/order/pickup-code/{pickupCode} ### Parameters #### Path Parameters - **pickupCode** (string) - Required - The pickup code for the order. ### Request Example ```json { "example": "Not applicable for GET request" } ``` ### Response #### Success Response (200) - **order** (object) - Details of the order. - **orderId** (string) - The unique identifier for the order. - **items** (array) - List of items in the order. #### Response Example ```json { "order": { "orderId": "ord1001", "items": [ { "name": "Fries", "quantity": 1 } ] } } ``` ``` ```APIDOC ## POST /api/kds/local/order/start-delivery ### Description In local network mode, signals the start of order delivery. ### Method POST ### Endpoint /api/kds/local/order/start-delivery ### Parameters #### Request Body - **deliveryInfo** (object) - Required - Information about the delivery start. - **orderId** (string) - Required - The ID of the order being delivered. ### Request Example ```json { "deliveryInfo": { "orderId": "ord1001" } } ``` ### Response #### Success Response (200) - **message** (string) - Confirmation message. #### Response Example ```json { "message": "Delivery started." } ``` ``` ```APIDOC ## POST /api/kds/cloud/order/end-delivery ### Description In cloud network mode, signals the end of order delivery. ### Method POST ### Endpoint /api/kds/cloud/order/end-delivery ### Parameters #### Request Body - **deliveryInfo** (object) - Required - Information about the delivery end. - **orderId** (string) - Required - The ID of the order whose delivery has ended. ### Request Example ```json { "deliveryInfo": { "orderId": "ord1001" } } ``` ### Response #### Success Response (200) - **message** (string) - Confirmation message. #### Response Example ```json { "message": "Delivery ended." } ``` ``` -------------------------------- ### POST /websites/open_keruyun_zh Source: https://open.keruyun.com/docs/zh/iMeYEXQBzPVmqdQufV3I Endpoint for placing takeout orders. This endpoint accepts a detailed request body containing all necessary information for order creation, including business parameters, shop details, product information, delivery preferences, payment information, and optional customer and discount details. ```APIDOC ## POST /websites/open_keruyun_zh ### Description Endpoint for placing takeout orders. This endpoint accepts a detailed request body containing all necessary information for order creation, including business parameters, shop details, product information, delivery preferences, payment information, and optional customer and discount details. ### Method POST ### Endpoint /websites/open_keruyun_zh ### Parameters #### Request Body - **tpOrderId** (String) - Required - Third-party order number, must be unique within a store. - **needInvoice** (Int) - Optional - Whether an invoice is needed. 1: Yes, 0: No. Defaults to 0. - **invoiceTitle** (String) - Optional - Invoice title. Required if `needInvoice` is 1. - **invoicedAmount** (String) - Optional - Invoicable amount in cents. If provided, the invoiced amount cannot exceed this value. - **taxpayerId** (String) - Optional - Taxpayer identification number. Required if `needInvoice` is 1. - **createTime** (Long) - Required - Order creation timestamp. - **status** (Int) - Optional - Order status. 1: Pending acceptance, 2: Accepted. Defaults to 1. Accepted orders trigger cloud printing. - **remark** (String) - Optional - Order remarks. Emojis are not supported. - **peopleCount** (Int) - Required - Number of diners. - **shop** (Shop) - Required - Shop information. - **products** (List) - Required - Product information. - **delivery** (Delivery) - Required - Delivery information. - **payment** (TakeoutPayment) - Required - Payment information. - **customers** (List) - Optional - Customer information. - **discountDetails** (List) - Optional - Discount details. - **isPrint** (Integer) - Optional - Whether to print. 1: Print, 0: Do not print. If empty, defaults to printing type 9 (consumption slip). - **printTemplateTypes** (Integer[]) - Optional - Specifies print template types. 8: Kitchen slip, 9: Consumption slip, 15: Label. If `isPrint` is 1 and this is not provided, printing is disabled. Invalid types are ignored. - **thirdSerialNo** (String) - Optional - Third-party pickup number. - **invoiceUrl** (String) - Optional - Invoice URL. Maximum length is 500 characters. - **takeMealBarcode** (String) - Optional - Backend meal pickup barcode. Maximum length is 500 characters. ### Request Example ```json { "tpOrderId": "TP12345", "needInvoice": 1, "invoiceTitle": "Example Company", "invoicedAmount": "10000", "taxpayerId": "1234567890", "createTime": 1678886400, "peopleCount": 2, "shop": { "shopIdenty": 1001, "tpShopId": "SHOPXYZ", "shopName": "Example Cafe" }, "products": [ { "name": "Coffee", "tpId": "COF001", "quantity": 1, "price": 300, "packagePrice": 0, "packageQuantity": 0, "totalFee": 300, "type": 0 } ], "delivery": { "expectTime": 1678890000, "deliveryParty": 1, "receiverName": "John Doe", "receiverPhone": "13800138000", "delivererAddress": "123 Main St", "coordinateType": 2, "longitude": 121.473701, "latitude": 31.230413 }, "payment": { "totalFee": 300, "deliveryFee": 50, "packageFee": 0, "discountFee": 0, "platformDiscountFee": 0, "shopDiscountFee": 0, "shopFee": 250, "userFee": 300, "serviceFee": 0, "subsidies": 0, "payType": 2 } } ``` ### Response #### Success Response (200) - **orderId** (String) - The unique identifier for the created order. - **message** (String) - A success message indicating the order was placed. #### Response Example ```json { "orderId": "ORD98765", "message": "Order placed successfully." } ``` ### Nested Structures #### Shop - **shopIdenty** (Long) - Required - Keruyun store ID. - **tpShopId** (String) - Required - Partner merchant ID. - **shopName** (String) - Required - Partner merchant name. #### TakeoutProduct - **name** (String) - Required - Product name. - **id** (Long) - Optional - Keruyun product ID. If empty, matches by name + specification; otherwise, treated as an online dish. - **parentUuid** (String) - Optional - Parent UUID for sub-dishes or add-ons in a set meal (developer-defined unique identifier for the dish in the order). Not applicable for single dishes. - **uuid** (String) - Optional - Developer-defined unique identifier for the dish in the order. Required if the dish has add-ons or sub-dishes. Not applicable for single dishes without add-ons. - **type** (Integer) - Required - Dish type: 0: Single dish, 1: Set meal, 2: Add-on. Sub-dishes for set meals should be 0. - **tpId** (String) - Required - Partner product ID. - **quantity** (Int) - Required - Quantity. - **unit** (String) - Optional - Product unit. - **price** (Int) - Required - Unit price in cents. - **packagePrice** (Int) - Required - Package box unit price in cents. - **packageQuantity** (Int) - Required - Package box quantity. - **packName** (String) - Optional - Package box name. - **totalFee** (Int) - Required - Total product fee = (unit price + price adjustment) * quantity, in cents. - **properties** (List) - Optional - Product specification properties. - **remark** (String) - Optional - Order remark. #### ProductProperty - **name** (String) - Required - Dish property name. - **id** (Long) - Optional - Dish property ID. If empty, matches by name; otherwise, added to remarks. - **type** (Int) - Required - Property type: 1: Preparation method, 2: Tag, 3: Remark, 4: Specification. - **reprice** (Int) - Required - Price adjustment in cents (positive for increase, negative for decrease). Required if `type` is preparation method. #### Delivery - **expectTime** (Long) - Required - Expected delivery time (timestamp in seconds). 0 for immediate delivery. For self-pickup appointments, this is the pickup time. - **deliveryParty** (Int) - Required - Delivery method: 1: Merchant self-delivery (including third-party platforms integrated via Keruyun), 2: Platform delivery, 3: Self-pickup. - **receiverName** (String) - Required - Receiver's name. Special emojis are not supported. - **receiverPhone** (String) - Required - Receiver's phone number. - **receiverGender** (Int) - Optional - Receiver's gender: 0: Female, 1: Male, -1: Unknown. Defaults to 1. - **delivererName** (String) - Optional - Delivery person's name. - **delivererPhone** (String) - Optional - Delivery person's phone number. - **delivererAddress** (String) - Optional - Delivery address. Required for merchant self-delivery. - **coordinateType** (Int) - Optional - Coordinate system type. Required for merchant self-delivery: 1: Baidu, 2: Gaode. - **longitude** (Double) - Optional - Delivery address longitude (0-180). Required for merchant self-delivery. - **latitude** (Double) - Optional - Delivery address latitude (0-90). Required for merchant self-delivery. #### TakeoutPayment - **memberId** (Long) - Optional - Member customer ID. Required for member payments. - **promotionId** (String) - Optional - Coupon ID. Only applicable for coupon payments. - **memberCardNumber** (Int) - Optional - Member card number. - **memberPassword** (Int) - Optional - Member password (MD5 encrypted). Required for member balance payments. - **totalFee** (Long) - Required - Total order price = (total product amount + package fee + delivery fee) in cents. - **deliveryFee** (Int) - Required - Delivery fee in cents. - **packageFee** (Int) - Required - Package fee = package quantity * package unit price, in cents. - **discountFee** (Int) - Required - Total discount amount = (total platform discount + total merchant discount) in cents. - **platformDiscountFee** (Int) - Required - Total platform discount amount in cents. - **shopDiscountFee** (Int) - Required - Total merchant discount amount. If `discountDetails` is provided, this is the sum of merchant discounts and Keruyun coupons. If not provided, it represents the merchant discount. - **shopFee** (Int) - Required - Total amount received by the merchant. For platform/merchant self-delivery: Total order price - merchant-borne discounts - service fee - delivery fee + subsidies. For self-pickup: Total order price - merchant-borne discounts - service fee + subsidies. In cents. If discount amount > total order price, this field should be 0. - **userFee** (Int) - Required - Total amount paid by the user = Total order price - total discount amount, in cents. If discount amount > total order price, this field should be 0. - **serviceFee** (Int) - Required - Service fee (e.g., commission paid by merchant to platform) in cents. - **subsidies** (Int) - Required - Platform subsidies provided to the merchant per order, in cents. - **payType** (Int) - Required - Payment method: 1: Offline/Cash on delivery, 2: Online payment, 3: Member card balance, 4: Coupon. #### Customer - **id** (Long) - Optional - Member customer ID. - **phoneNumber** (String) - Required - Member phone number. - **name** (String) - Required - Member name. Special characters are not supported. - **gender** (Int) - Required - Member gender. #### DiscountDetail - **discountType** (Int) - Required - Discount type: 1: Keruyun coupon (only cash coupons currently, and coupon amount must be >= total order price), 2: Platform discount, 3: Merchant discount. - **discountFee** (Int) - Required - Discount amount. - **promotionId** (Long) - Optional - Promotion or coupon ID. Required if `discountType` is coupon. - **couponId** (Long) - Optional - Coupon template ID. Required if `discountType` is coupon. - **customerId** (Long) - Optional - Member customer ID. Required if `discountType` is coupon and must match at least one ID in `DinnerOrderMember`. - **description** (String) - Optional - Discount description. ``` -------------------------------- ### Open Keruyun Zh API Request Structure Source: https://open.keruyun.com/docs/zh/kXcd2YIBQmWK-9w5YZ_R Details on the HTTP request methods (POST, GET) and the required request header for POST requests. ```APIDOC ## Open Keruyun Zh API Request Structure ### Description This section outlines the two supported HTTP request methods (POST and GET) for the Open Platform API. For POST requests, a specific Content-Type header is required. ### Request Methods - **HTTP POST**: Used for requests that modify or send data. - **HTTP GET**: Used for retrieving data. ### Request Headers (for POST requests) - **Content-Type**: `application/json` ```