From 33f21819aabafa496ca645f6b1ab6b5f5d0e9646 Mon Sep 17 00:00:00 2001 From: Colin Mollenhour Date: Tue, 13 May 2025 10:35:02 -0400 Subject: [PATCH 1/7] Add docs for JSONRPC API. --- docs/content/api/jsonrpc/catalog_category.md | 595 +++++++ docs/content/api/jsonrpc/catalog_product.md | 548 +++++++ .../api/jsonrpc/catalog_product_attribute.md | 1379 +++++++++++++++++ .../jsonrpc/cataloginventory_stock_item.md | 219 +++ docs/content/api/jsonrpc/customer.md | 323 ++++ docs/content/api/jsonrpc/customer_address.md | 297 ++++ docs/content/api/jsonrpc/customer_group.md | 68 + docs/content/api/jsonrpc/index.md | 429 +++++ docs/content/api/jsonrpc/sales_order.md | 375 +++++ .../api/jsonrpc/sales_order_creditmemo.md | 323 ++++ .../api/jsonrpc/sales_order_invoice.md | 389 +++++ .../api/jsonrpc/sales_order_shipment.md | 433 ++++++ 12 files changed, 5378 insertions(+) create mode 100644 docs/content/api/jsonrpc/catalog_category.md create mode 100644 docs/content/api/jsonrpc/catalog_product.md create mode 100644 docs/content/api/jsonrpc/catalog_product_attribute.md create mode 100644 docs/content/api/jsonrpc/cataloginventory_stock_item.md create mode 100644 docs/content/api/jsonrpc/customer.md create mode 100644 docs/content/api/jsonrpc/customer_address.md create mode 100644 docs/content/api/jsonrpc/customer_group.md create mode 100644 docs/content/api/jsonrpc/index.md create mode 100644 docs/content/api/jsonrpc/sales_order.md create mode 100644 docs/content/api/jsonrpc/sales_order_creditmemo.md create mode 100644 docs/content/api/jsonrpc/sales_order_invoice.md create mode 100644 docs/content/api/jsonrpc/sales_order_shipment.md diff --git a/docs/content/api/jsonrpc/catalog_category.md b/docs/content/api/jsonrpc/catalog_category.md new file mode 100644 index 00000000000..32d4bbaf490 --- /dev/null +++ b/docs/content/api/jsonrpc/catalog_category.md @@ -0,0 +1,595 @@ +# Catalog Category API + +## Introduction + +The Catalog Category API allows you to manage product categories in your OpenMage store. You can retrieve category information, create new categories, update existing ones, move categories within the category tree, and manage product assignments to categories. + +## Available Methods + +### currentStore + +Sets the current store for category operations. + +**Method Name**: `catalog_category.currentStore` + +**Parameters**: +- `store` (string|int, required) - Store ID or code + +**Return**: +- (int) - Current store ID + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_category.currentStore", + "default" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": 1, + "id": 1 +} +``` + +### tree + +Retrieve category tree. + +**Method Name**: `catalog_category.tree` + +**Parameters**: +- `parentId` (int, optional) - Parent category ID (default: 1 - root category) +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (array) - Category tree with the following structure: + - `category_id` (int) - Category ID + - `parent_id` (int) - Parent category ID + - `name` (string) - Category name + - `is_active` (boolean) - Whether the category is active + - `position` (int) - Position + - `level` (int) - Level in the category tree + - `children` (array) - Array of child categories with the same structure + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_category.tree", + [1, "default"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "category_id": 1, + "parent_id": 0, + "name": "Root", + "is_active": true, + "position": 0, + "level": 0, + "children": [ + { + "category_id": 2, + "parent_id": 1, + "name": "Default Category", + "is_active": true, + "position": 1, + "level": 1, + "children": [] + } + ] + }, + "id": 1 +} +``` + +### level + +Retrieve level of categories for category/store view/website. + +**Method Name**: `catalog_category.level` + +**Parameters**: +- `website` (string|int, optional) - Website ID or code +- `store` (string|int, optional) - Store ID or code +- `categoryId` (int, optional) - Category ID + +**Return**: +- (array) - Array of categories with the following structure: + - `category_id` (int) - Category ID + - `parent_id` (int) - Parent category ID + - `name` (string) - Category name + - `is_active` (boolean) - Whether the category is active + - `position` (int) - Position + - `level` (int) - Level in the category tree + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_category.level", + [null, "default", 2] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "category_id": 3, + "parent_id": 2, + "name": "Furniture", + "is_active": true, + "position": 1, + "level": 2 + }, + { + "category_id": 4, + "parent_id": 2, + "name": "Electronics", + "is_active": true, + "position": 2, + "level": 2 + } + ], + "id": 1 +} +``` + +### info + +Retrieve category data. + +**Method Name**: `catalog_category.info` + +**Parameters**: +- `categoryId` (int, required) - Category ID +- `store` (string|int, optional) - Store ID or code +- `attributes` (array, optional) - Array of attributes to return + +**Return**: +- (array) - Category data with the following structure: + - `category_id` (int) - Category ID + - `is_active` (boolean) - Whether the category is active + - `position` (int) - Position + - `level` (int) - Level in the category tree + - Additional attributes as requested + - `parent_id` (int) - Parent category ID + - `children` (string) - Comma-separated list of child category IDs + - `all_children` (string) - Comma-separated list of all child category IDs + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_category.info", + [3, "default", ["name", "description", "url_key"]] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "category_id": 3, + "is_active": true, + "position": 1, + "level": 2, + "name": "Furniture", + "description": "Furniture category description", + "url_key": "furniture", + "parent_id": 2, + "children": "5,6,7", + "all_children": "5,6,7,8,9" + }, + "id": 1 +} +``` + +### create + +Create new category. + +**Method Name**: `catalog_category.create` + +**Parameters**: +- `parentId` (int, required) - Parent category ID +- `categoryData` (array, required) - Category data: + - `name` (string, required) - Category name + - `is_active` (boolean, optional) - Whether the category is active + - `position` (int, optional) - Position + - `available_sort_by` (array, optional) - Available sort by options + - `default_sort_by` (string, optional) - Default sort by option + - `include_in_menu` (boolean, optional) - Include in navigation menu + - `url_key` (string, optional) - URL key + - `description` (string, optional) - Description + - `meta_title` (string, optional) - Meta title + - `meta_keywords` (string, optional) - Meta keywords + - `meta_description` (string, optional) - Meta description + - `display_mode` (string, optional) - Display mode + - Other custom attributes +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (int) - ID of the created category + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_category.create", + [ + 2, + { + "name": "New Category", + "is_active": true, + "position": 3, + "description": "New category description", + "url_key": "new-category" + }, + "default" + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": 10, + "id": 1 +} +``` + +**Possible Errors**: +- `data_invalid` - Invalid data provided +- `not_exists` - Parent category does not exist + +### update + +Update category data. + +**Method Name**: `catalog_category.update` + +**Parameters**: +- `categoryId` (int, required) - Category ID +- `categoryData` (array, required) - Category data to update (same structure as in create method) +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_category.update", + [ + 3, + { + "name": "Updated Category Name", + "description": "Updated description" + }, + "default" + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `data_invalid` - Invalid data provided +- `not_exists` - Category does not exist + +### move + +Move category in tree. + +**Method Name**: `catalog_category.move` + +**Parameters**: +- `categoryId` (int, required) - Category ID to move +- `parentId` (int, required) - New parent category ID +- `afterId` (int, optional) - Category ID to place the moved category after (if null, the category will be placed at the end) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_category.move", + [3, 4, null] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `not_moved` - Category could not be moved +- `not_exists` - Category does not exist + +### delete + +Delete category. + +**Method Name**: `catalog_category.delete` + +**Parameters**: +- `categoryId` (int, required) - Category ID to delete + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_category.delete", + 3 + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `not_deleted` - Category could not be deleted +- `not_exists` - Category does not exist + +### assignedProducts + +Retrieve list of assigned products to category. + +**Method Name**: `catalog_category.assignedProducts` + +**Parameters**: +- `categoryId` (int, required) - Category ID +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (array) - Array of products with the following structure: + - `product_id` (int) - Product ID + - `type` (string) - Product type + - `set` (int) - Attribute set ID + - `sku` (string) - Product SKU + - `position` (int) - Position in category + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_category.assignedProducts", + [3, "default"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "product_id": 14, + "type": "simple", + "set": 4, + "sku": "product1", + "position": 1 + }, + { + "product_id": 15, + "type": "simple", + "set": 4, + "sku": "product2", + "position": 2 + } + ], + "id": 1 +} +``` + +### assignProduct + +Assign product to category. + +**Method Name**: `catalog_category.assignProduct` + +**Parameters**: +- `categoryId` (int, required) - Category ID +- `productId` (int|string, required) - Product ID or SKU +- `position` (int, optional) - Position in category +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_category.assignProduct", + [3, "product3", 3, "sku"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `data_invalid` - Invalid data provided +- `not_exists` - Category does not exist +- `product_not_exists` - Product does not exist + +### updateProduct + +Update product assignment. + +**Method Name**: `catalog_category.updateProduct` + +**Parameters**: +- `categoryId` (int, required) - Category ID +- `productId` (int|string, required) - Product ID or SKU +- `position` (int, optional) - New position in category +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_category.updateProduct", + [3, "product1", 5, "sku"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `data_invalid` - Invalid data provided +- `not_exists` - Category does not exist +- `product_not_exists` - Product does not exist +- `product_not_assigned` - Product is not assigned to the category + +### removeProduct + +Remove product assignment from category. + +**Method Name**: `catalog_category.removeProduct` + +**Parameters**: +- `categoryId` (int, required) - Category ID +- `productId` (int|string, required) - Product ID or SKU +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_category.removeProduct", + [3, "product1", "sku"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `not_exists` - Category does not exist +- `product_not_exists` - Product does not exist \ No newline at end of file diff --git a/docs/content/api/jsonrpc/catalog_product.md b/docs/content/api/jsonrpc/catalog_product.md new file mode 100644 index 00000000000..0b19bb5f1e3 --- /dev/null +++ b/docs/content/api/jsonrpc/catalog_product.md @@ -0,0 +1,548 @@ +# Catalog Product API + +## Introduction + +The Catalog Product API allows you to manage products in your OpenMage store. You can retrieve product information, create new products, update existing ones, delete products, and manage product special prices. + +## Available Methods + +### currentStore + +Sets the current store for product operations. + +**Method Name**: `catalog_product.currentStore` + +**Parameters**: +- `store` (string|int, required) - Store ID or code + +**Return**: +- (int) - Current store ID + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product.currentStore", + "default" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": 1, + "id": 1 +} +``` + +### list + +Retrieve list of products with basic info. + +**Method Name**: `catalog_product.list` + +**Parameters**: +- `filters` (object|array, optional) - Filters to apply to the list: + - `product_id` (int|array) - Filter by product ID(s) + - `set` (int|array) - Filter by attribute set ID(s) + - `type` (string|array) - Filter by product type(s) + - `sku` (string|array) - Filter by SKU(s) + - `name` (string|array) - Filter by name(s) + - `status` (int|array) - Filter by status(es) + - Other attributes can also be used as filters +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (array) - Array of products with the following structure: + - `product_id` (int) - Product ID + - `sku` (string) - Product SKU + - `name` (string) - Product name + - `set` (int) - Attribute set ID + - `type` (string) - Product type + - `category_ids` (array) - Array of category IDs + - `website_ids` (array) - Array of website IDs + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product.list", + [{"type": "simple"}, "default"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "product_id": 1, + "sku": "product1", + "name": "Product 1", + "set": 4, + "type": "simple", + "category_ids": [2, 3, 4], + "website_ids": [1] + }, + { + "product_id": 2, + "sku": "product2", + "name": "Product 2", + "set": 4, + "type": "simple", + "category_ids": [2, 3], + "website_ids": [1] + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- `filters_invalid` - Invalid filters provided + +### info + +Retrieve product info. + +**Method Name**: `catalog_product.info` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `store` (string|int, optional) - Store ID or code +- `attributes` (array, optional) - Array of attributes to return +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (array) - Product data with the following structure: + - `product_id` (int) - Product ID + - `sku` (string) - Product SKU + - `set` (int) - Attribute set ID + - `type` (string) - Product type + - `categories` (array) - Array of category IDs + - `websites` (array) - Array of website IDs + - Additional attributes as requested + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product.info", + ["product1", "default", ["name", "description", "price"], "sku"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "product_id": 1, + "sku": "product1", + "set": 4, + "type": "simple", + "categories": [2, 3, 4], + "websites": [1], + "name": "Product 1", + "description": "Product 1 description", + "price": 19.99 + }, + "id": 1 +} +``` + +**Possible Errors**: +- `product_not_exists` - Product does not exist + +### create + +Create new product. + +**Method Name**: `catalog_product.create` + +**Parameters**: +- `type` (string, required) - Product type (simple, configurable, grouped, virtual, bundle, downloadable) +- `set` (int, required) - Attribute set ID +- `sku` (string, required) - Product SKU +- `productData` (array, required) - Product data: + - `name` (string, required) - Product name + - `description` (string, optional) - Product description + - `short_description` (string, optional) - Product short description + - `weight` (float, optional) - Product weight + - `status` (int, optional) - Product status (1 - enabled, 2 - disabled) + - `url_key` (string, optional) - URL key + - `visibility` (int, optional) - Visibility (1 - Not Visible, 2 - Catalog, 3 - Search, 4 - Catalog, Search) + - `price` (float, optional) - Product price + - `tax_class_id` (int, optional) - Tax class ID + - `meta_title` (string, optional) - Meta title + - `meta_keyword` (string, optional) - Meta keywords + - `meta_description` (string, optional) - Meta description + - `stock_data` (array, optional) - Stock data: + - `qty` (float) - Quantity + - `is_in_stock` (int) - Is in stock (1 - yes, 0 - no) + - `manage_stock` (int) - Manage stock (1 - yes, 0 - no) + - `use_config_manage_stock` (int) - Use config settings for managing stock (1 - yes, 0 - no) + - `website_ids` (array, optional) - Array of website IDs + - `category_ids` (array, optional) - Array of category IDs + - Other custom attributes +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (int) - ID of the created product + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product.create", + [ + "simple", + 4, + "new-product", + { + "name": "New Product", + "description": "New product description", + "short_description": "Short description", + "weight": 1.0, + "status": 1, + "visibility": 4, + "price": 29.99, + "tax_class_id": 2, + "stock_data": { + "qty": 100, + "is_in_stock": 1 + }, + "website_ids": [1], + "category_ids": [2, 3] + }, + "default" + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": 10, + "id": 1 +} +``` + +**Possible Errors**: +- `data_invalid` - Invalid data provided +- `product_type_not_exists` - Product type does not exist +- `product_attribute_set_not_exists` - Attribute set does not exist +- `product_attribute_set_not_valid` - Attribute set is not valid for the product + +### update + +Update product data. + +**Method Name**: `catalog_product.update` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `productData` (array, required) - Product data to update (same structure as in create method) +- `store` (string|int, optional) - Store ID or code +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product.update", + [ + "product1", + { + "name": "Updated Product Name", + "description": "Updated description", + "price": 24.99 + }, + "default", + "sku" + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `data_invalid` - Invalid data provided +- `product_not_exists` - Product does not exist + +### multiUpdate + +Update multiple products in a single call. + +**Method Name**: `catalog_product.multiUpdate` + +**Parameters**: +- `productIds` (array, required) - Array of product IDs or SKUs +- `productData` (array, required) - Product data to update (same structure as in update method) +- `store` (string|int, optional) - Store ID or code +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product.multiUpdate", + [ + ["product1", "product2"], + { + "status": 1, + "price": 24.99 + }, + "default", + "sku" + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `data_invalid` - Invalid data provided +- `product_not_exists` - One or more products do not exist + +### delete + +Delete product. + +**Method Name**: `catalog_product.delete` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product.delete", + ["product1", "sku"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `not_deleted` - Product could not be deleted +- `product_not_exists` - Product does not exist + +### getSpecialPrice + +Retrieve product special price. + +**Method Name**: `catalog_product.getSpecialPrice` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (array) - Special price data with the following structure: + - `special_price` (float) - Special price + - `special_from_date` (string) - Special price from date + - `special_to_date` (string) - Special price to date + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product.getSpecialPrice", + ["product1", "default"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "special_price": 19.99, + "special_from_date": "2023-01-01 00:00:00", + "special_to_date": "2023-12-31 23:59:59" + }, + "id": 1 +} +``` + +**Possible Errors**: +- `product_not_exists` - Product does not exist + +### setSpecialPrice + +Update product special price. + +**Method Name**: `catalog_product.setSpecialPrice` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `specialPrice` (float, optional) - Special price +- `fromDate` (string, optional) - Special price from date (format: YYYY-MM-DD) +- `toDate` (string, optional) - Special price to date (format: YYYY-MM-DD) +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product.setSpecialPrice", + ["product1", 19.99, "2023-01-01", "2023-12-31", "default"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `data_invalid` - Invalid data provided +- `product_not_exists` - Product does not exist + +### listOfAdditionalAttributes + +Get list of additional attributes which are not in default create/update list. + +**Method Name**: `catalog_product.listOfAdditionalAttributes` + +**Parameters**: +- `productType` (string, required) - Product type +- `attributeSetId` (int, required) - Attribute set ID + +**Return**: +- (array) - Array of attributes with the following structure: + - `attribute_id` (int) - Attribute ID + - `code` (string) - Attribute code + - `type` (string) - Attribute type + - `required` (boolean) - Whether the attribute is required + - `scope` (string) - Attribute scope (global, website, store) + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product.listOfAdditionalAttributes", + ["simple", 4] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "attribute_id": 142, + "code": "manufacturer", + "type": "select", + "required": false, + "scope": "global" + }, + { + "attribute_id": 143, + "code": "color", + "type": "select", + "required": false, + "scope": "global" + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- `product_type_not_exists` - Product type does not exist +- `product_attribute_set_not_exists` - Attribute set does not exist \ No newline at end of file diff --git a/docs/content/api/jsonrpc/catalog_product_attribute.md b/docs/content/api/jsonrpc/catalog_product_attribute.md new file mode 100644 index 00000000000..63d0b2d1db9 --- /dev/null +++ b/docs/content/api/jsonrpc/catalog_product_attribute.md @@ -0,0 +1,1379 @@ +# Catalog Product Attribute API + +## Introduction + +The Catalog Product Attribute API allows you to manage product attributes, attribute sets, attribute options, product types, media, and tier prices in your OpenMage store. + +## Catalog Product Attribute + +### items + +Retrieve attributes from specified attribute set. + +**Method Name**: `catalog_product_attribute.items` + +**Parameters**: +- `setId` (int, required) - Attribute set ID + +**Return**: +- (array) - Array of attributes with the following structure: + - `attribute_id` (int) - Attribute ID + - `code` (string) - Attribute code + - `type` (string) - Attribute type + - `required` (boolean) - Whether the attribute is required + - `scope` (string) - Attribute scope (global, website, store) + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute.items", + 4 + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "attribute_id": 73, + "code": "name", + "type": "text", + "required": true, + "scope": "store" + }, + { + "attribute_id": 74, + "code": "description", + "type": "textarea", + "required": false, + "scope": "store" + } + ], + "id": 1 +} +``` + +### options + +Retrieve attribute options. + +**Method Name**: `catalog_product_attribute.options` + +**Parameters**: +- `attributeId` (int, required) - Attribute ID +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (array) - Array of attribute options with the following structure: + - `value` (string) - Option value + - `label` (string) - Option label + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute.options", + [142, "default"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "value": "", + "label": "" + }, + { + "value": "1", + "label": "Option 1" + }, + { + "value": "2", + "label": "Option 2" + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- `not_exists` - Attribute does not exist + +### types + +Retrieve list of possible attribute types. + +**Method Name**: `catalog_product_attribute.types` + +**Parameters**: None + +**Return**: +- (array) - Array of attribute types with the following structure: + - `value` (string) - Type value + - `label` (string) - Type label + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute.types", + [] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "value": "text", + "label": "Text Field" + }, + { + "value": "textarea", + "label": "Text Area" + }, + { + "value": "select", + "label": "Dropdown" + }, + { + "value": "multiselect", + "label": "Multiple Select" + }, + { + "value": "boolean", + "label": "Yes/No" + }, + { + "value": "date", + "label": "Date" + }, + { + "value": "price", + "label": "Price" + } + ], + "id": 1 +} +### create + +Create new product attribute. + +**Method Name**: `catalog_product_attribute.create` + +**Parameters**: +- `data` (array, required) - Attribute data: + - `attribute_code` (string, required) - Attribute code + - `frontend_input` (string, required) - Frontend input type + - `scope` (string, required) - Attribute scope (global, website, store) + - `default_value` (string, optional) - Default value + - `is_unique` (boolean, optional) - Whether the attribute is unique + - `is_required` (boolean, optional) - Whether the attribute is required + - `apply_to` (array, optional) - Product types to apply to + - `is_configurable` (boolean, optional) - Whether the attribute is configurable + - `is_searchable` (boolean, optional) - Whether the attribute is searchable + - `is_visible_in_advanced_search` (boolean, optional) - Whether the attribute is visible in advanced search + - `is_comparable` (boolean, optional) - Whether the attribute is comparable + - `is_used_for_promo_rules` (boolean, optional) - Whether the attribute is used for promo rules + - `is_visible_on_front` (boolean, optional) - Whether the attribute is visible on front + - `used_in_product_listing` (boolean, optional) - Whether the attribute is used in product listing + - `frontend_label` (array, required) - Array of frontend labels with the following structure: + - `store_id` (int) - Store ID + - `label` (string) - Label + - `additional_fields` (array, optional) - Additional fields based on frontend input type + +**Return**: +- (int) - ID of the created attribute + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute.create", + { + "attribute_code": "custom_attribute", + "frontend_input": "select", + "scope": "global", + "is_required": false, + "frontend_label": [ + { + "store_id": 0, + "label": "Custom Attribute" + } + ], + "is_searchable": true, + "is_visible_in_advanced_search": true, + "is_comparable": true, + "is_visible_on_front": true + } + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": 145, + "id": 1 +} +``` + +**Possible Errors**: +- `invalid_parameters` - Invalid parameters provided +- `invalid_code` - Invalid attribute code +- `invalid_frontend_input` - Invalid frontend input type +- `unable_to_save` - Unable to save attribute + +### update + +Update product attribute. + +**Method Name**: `catalog_product_attribute.update` + +**Parameters**: +- `attribute` (int|string, required) - Attribute ID or code +- `data` (array, required) - Attribute data to update (same structure as in create method) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute.update", + [ + "custom_attribute", + { + "frontend_label": [ + { + "store_id": 0, + "label": "Updated Custom Attribute" + } + ], + "is_searchable": false + } + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `can_not_edit` - Attribute cannot be edited +- `unable_to_save` - Unable to save attribute +### remove + +Remove attribute. + +**Method Name**: `catalog_product_attribute.remove` + +**Parameters**: +- `attribute` (int|string, required) - Attribute ID or code + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute.remove", + "custom_attribute" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `can_not_delete` - Attribute cannot be deleted + +### info + +Get full information about attribute with list of options. + +**Method Name**: `catalog_product_attribute.info` + +**Parameters**: +- `attribute` (int|string, required) - Attribute ID or code + +**Return**: +- (array) - Attribute data with the following structure: + - `attribute_id` (int) - Attribute ID + - `attribute_code` (string) - Attribute code + - `frontend_input` (string) - Frontend input type + - `default_value` (string) - Default value + - `is_unique` (boolean) - Whether the attribute is unique + - `is_required` (boolean) - Whether the attribute is required + - `apply_to` (array) - Product types to apply to + - `is_configurable` (boolean) - Whether the attribute is configurable + - `is_searchable` (boolean) - Whether the attribute is searchable + - `is_visible_in_advanced_search` (boolean) - Whether the attribute is visible in advanced search + - `is_comparable` (boolean) - Whether the attribute is comparable + - `is_used_for_promo_rules` (boolean) - Whether the attribute is used for promo rules + - `is_visible_on_front` (boolean) - Whether the attribute is visible on front + - `used_in_product_listing` (boolean) - Whether the attribute is used in product listing + - `frontend_label` (array) - Array of frontend labels + - `scope` (string) - Attribute scope (global, website, store) + - `additional_fields` (array) - Additional fields based on frontend input type + - `options` (array) - Array of attribute options + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute.info", + "color" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "attribute_id": 143, + "attribute_code": "color", + "frontend_input": "select", + "default_value": "", + "is_unique": false, + "is_required": false, + "apply_to": [], + "is_configurable": true, + "is_searchable": true, + "is_visible_in_advanced_search": true, + "is_comparable": true, + "is_used_for_promo_rules": false, + "is_visible_on_front": true, + "used_in_product_listing": false, + "frontend_label": [ + { + "store_id": 0, + "label": "Color" + } + ], + "scope": "global", + "additional_fields": { + "is_filterable": 1, + "is_filterable_in_search": 1, + "position": 0, + "used_for_sort_by": 0 + }, + "options": [ + { + "value": "1", + "label": "Red" + }, + { + "value": "2", + "label": "Blue" + }, + { + "value": "3", + "label": "Green" + } + ] + }, + "id": 1 +} +``` + +### addOption + +Add option to select or multiselect attribute. + +**Method Name**: `catalog_product_attribute.addOption` + +**Parameters**: +- `attribute` (int|string, required) - Attribute ID or code +- `data` (array, required) - Option data: + - `label` (array, required) - Array of option labels with the following structure: + - `store_id` (int|array) - Store ID or array of store IDs + - `value` (string) - Option label + - `order` (int, optional) - Option order + - `is_default` (boolean, optional) - Whether the option is default + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute.addOption", + [ + "color", + { + "label": [ + { + "store_id": 0, + "value": "Yellow" + } + ], + "order": 4, + "is_default": false + } + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `invalid_frontend_input` - Invalid frontend input type +- `unable_to_add_option` - Unable to add option + +### removeOption + +Remove option from select or multiselect attribute. + +**Method Name**: `catalog_product_attribute.removeOption` + +**Parameters**: +- `attribute` (int|string, required) - Attribute ID or code +- `optionId` (int, required) - Option ID to remove + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute.removeOption", + ["color", 4] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `invalid_frontend_input` - Invalid frontend input type +- `unable_to_remove_option` - Unable to remove option + +## Catalog Product Attribute Set + +### items + +Retrieve attribute set list. + +**Method Name**: `catalog_product_attribute_set.items` + +**Parameters**: None + +**Return**: +- (array) - Array of attribute sets with the following structure: + - `set_id` (int) - Attribute set ID + - `name` (string) - Attribute set name + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_set.items", + [] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "set_id": 4, + "name": "Default" + }, + { + "set_id": 5, + "name": "Custom" + } + ], + "id": 1 +} +``` +### create + +Create new attribute set based on another set. + +**Method Name**: `catalog_product_attribute_set.create` + +**Parameters**: +- `attributeSetName` (string, required) - Attribute set name +- `skeletonSetId` (int, required) - Skeleton attribute set ID + +**Return**: +- (int) - ID of the created attribute set + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_set.create", + ["New Attribute Set", 4] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": 6, + "id": 1 +} +``` + +**Possible Errors**: +- `invalid_skeleton_set_id` - Invalid skeleton attribute set ID +- `invalid_data` - Invalid data provided +- `create_attribute_set_error` - Error creating attribute set + +### remove + +Remove attribute set. + +**Method Name**: `catalog_product_attribute_set.remove` + +**Parameters**: +- `attributeSetId` (int, required) - Attribute set ID +- `forceProductsRemove` (boolean, optional) - Force removal of products with this attribute set + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_set.remove", + [6, false] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `invalid_attribute_set_id` - Invalid attribute set ID +- `attribute_set_has_related_products` - Attribute set has related products +- `remove_attribute_set_error` - Error removing attribute set + +### attributeAdd + +Add attribute to attribute set. + +**Method Name**: `catalog_product_attribute_set.attributeAdd` + +**Parameters**: +- `attributeId` (int, required) - Attribute ID +- `attributeSetId` (int, required) - Attribute set ID +- `attributeGroupId` (int, optional) - Attribute group ID +- `sortOrder` (int, optional) - Sort order + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_set.attributeAdd", + [145, 5, null, 0] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `invalid_attribute_id` - Invalid attribute ID +- `invalid_attribute_set_id` - Invalid attribute set ID +- `invalid_attribute_group_id` - Invalid attribute group ID +- `attribute_is_already_in_set` - Attribute is already in set +- `add_attribute_error` - Error adding attribute + +### attributeRemove + +Remove attribute from attribute set. + +**Method Name**: `catalog_product_attribute_set.attributeRemove` + +**Parameters**: +- `attributeId` (int, required) - Attribute ID +- `attributeSetId` (int, required) - Attribute set ID + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_set.attributeRemove", + [145, 5] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `invalid_attribute_id` - Invalid attribute ID +- `invalid_attribute_set_id` - Invalid attribute set ID +- `attribute_is_not_in_set` - Attribute is not in set +- `remove_attribute_error` - Error removing attribute + +### groupAdd + +Create group within existing attribute set. + +**Method Name**: `catalog_product_attribute_set.groupAdd` + +**Parameters**: +- `attributeSetId` (int, required) - Attribute set ID +- `groupName` (string, required) - Group name + +**Return**: +- (int) - ID of the created group + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_set.groupAdd", + [5, "New Group"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": 15, + "id": 1 +} +``` + +**Possible Errors**: +- `group_already_exists` - Group already exists +- `group_add_error` - Error adding group + +### groupRename + +Rename existing group. + +**Method Name**: `catalog_product_attribute_set.groupRename` + +**Parameters**: +- `groupId` (int, required) - Group ID +- `groupName` (string, required) - New group name + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_set.groupRename", + [15, "Renamed Group"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `invalid_attribute_group_id` - Invalid attribute group ID +- `group_rename_error` - Error renaming group + +### groupRemove + +Remove group from existing attribute set. + +**Method Name**: `catalog_product_attribute_set.groupRemove` + +**Parameters**: +- `attributeGroupId` (int, required) - Attribute group ID + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_set.groupRemove", + 15 + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `invalid_attribute_group_id` - Invalid attribute group ID +- `group_has_configurable_attributes` - Group has configurable attributes +- `group_has_system_attributes` - Group has system attributes +- `group_remove_error` - Error removing group + +## Catalog Product Type + +### items + +Retrieve product type list. + +**Method Name**: `catalog_product_type.items` + +**Parameters**: None + +**Return**: +- (array) - Array of product types with the following structure: + - `type` (string) - Product type code + - `label` (string) - Product type label + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_type.items", + [] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "type": "simple", + "label": "Simple Product" + }, + { + "type": "configurable", + "label": "Configurable Product" + }, + { + "type": "grouped", + "label": "Grouped Product" + }, + { + "type": "virtual", + "label": "Virtual Product" + }, + { + "type": "bundle", + "label": "Bundle Product" + }, + { + "type": "downloadable", + "label": "Downloadable Product" + } + ], + "id": 1 +} +``` + +## Catalog Product Attribute Media + +### items + +Retrieve images for product. + +**Method Name**: `catalog_product_attribute_media.items` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `store` (string|int, optional) - Store ID or code +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (array) - Array of product images with the following structure: + - `file` (string) - Image file path + - `label` (string) - Image label + - `position` (int) - Image position + - `exclude` (boolean) - Whether the image is excluded + - `url` (string) - Image URL + - `types` (array) - Array of image types (image, small_image, thumbnail) + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_media.items", + ["product1", "default", "sku"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "file": "/p/r/product1.jpg", + "label": "Product 1", + "position": 1, + "exclude": false, + "url": "http://example.com/media/catalog/product/p/r/product1.jpg", + "types": ["image", "small_image", "thumbnail"] + }, + { + "file": "/p/r/product1_2.jpg", + "label": "Product 1 - 2", + "position": 2, + "exclude": false, + "url": "http://example.com/media/catalog/product/p/r/product1_2.jpg", + "types": [] + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- `product_not_exists` - Product does not exist + +### info + +Retrieve image data. + +**Method Name**: `catalog_product_attribute_media.info` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `file` (string, required) - Image file path +- `store` (string|int, optional) - Store ID or code +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (array) - Image data with the same structure as in items method + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_media.info", + ["product1", "/p/r/product1.jpg", "default", "sku"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "file": "/p/r/product1.jpg", + "label": "Product 1", + "position": 1, + "exclude": false, + "url": "http://example.com/media/catalog/product/p/r/product1.jpg", + "types": ["image", "small_image", "thumbnail"] + }, + "id": 1 +} +``` + +**Possible Errors**: +- `product_not_exists` - Product does not exist +- `not_exists` - Image does not exist + +### create + +Create new image for product and return image filename. + +**Method Name**: `catalog_product_attribute_media.create` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `data` (array, required) - Image data: + - `file` (array, required) - Image file data: + - `content` (string, required) - Base64-encoded image content + - `mime` (string, required) - Image MIME type + - `name` (string, optional) - Image name + - `label` (string, optional) - Image label + - `position` (int, optional) - Image position + - `exclude` (boolean, optional) - Whether the image is excluded + - `types` (array, optional) - Array of image types (image, small_image, thumbnail) +- `store` (string|int, optional) - Store ID or code +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (string) - Image file path + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_media.create", + [ + "product1", + { + "file": { + "content": "base64-encoded-image-content", + "mime": "image/jpeg", + "name": "product1_3.jpg" + }, + "label": "Product 1 - 3", + "position": 3, + "types": ["image"] + }, + "default", + "sku" + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": "/p/r/product1_3.jpg", + "id": 1 +} +``` + +**Possible Errors**: +- `product_not_exists` - Product does not exist +- `data_invalid` - Invalid data provided +- `not_created` - Image could not be created + +### update + +Update image data. + +**Method Name**: `catalog_product_attribute_media.update` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `file` (string, required) - Image file path +- `data` (array, required) - Image data to update (same structure as in create method) +- `store` (string|int, optional) - Store ID or code +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_media.update", + [ + "product1", + "/p/r/product1_3.jpg", + { + "label": "Updated Product 1 - 3", + "position": 4, + "types": ["small_image"] + }, + "default", + "sku" + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `product_not_exists` - Product does not exist +- `not_exists` - Image does not exist +- `data_invalid` - Invalid data provided +- `not_updated` - Image could not be updated + +### remove + +Remove image from product. + +**Method Name**: `catalog_product_attribute_media.remove` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `file` (string, required) - Image file path +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_media.remove", + ["product1", "/p/r/product1_3.jpg", "sku"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `product_not_exists` - Product does not exist +- `not_exists` - Image does not exist +- `not_removed` - Image could not be removed + +### types + +Retrieve image types (image, small_image, thumbnail, etc...). + +**Method Name**: `catalog_product_attribute_media.types` + +**Parameters**: +- `setId` (int, required) - Attribute set ID + +**Return**: +- (array) - Array of image types with the following structure: + - `code` (string) - Image type code + - `scope` (string) - Image type scope (global, website, store) + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_media.types", + 4 + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "code": "image", + "scope": "store" + }, + { + "code": "small_image", + "scope": "store" + }, + { + "code": "thumbnail", + "scope": "store" + } + ], + "id": 1 +} +``` + +## Catalog Product Attribute Tier Price + +### info + +Retrieve tier prices for a product. + +**Method Name**: `catalog_product_attribute_tier_price.info` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (array) - Array of tier prices with the following structure: + - `customer_group_id` (string) - Customer group ID or 'all' for all groups + - `website` (string) - Website code or 'all' for all websites + - `qty` (float) - Quantity + - `price` (float) - Price + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_tier_price.info", + ["product1", "sku"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "customer_group_id": "all", + "website": "all", + "qty": 2, + "price": 19.99 + }, + { + "customer_group_id": "1", + "website": "base", + "qty": 5, + "price": 17.99 + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- `product_not_exists` - Product does not exist + +### update + +Update tier prices of product. + +**Method Name**: `catalog_product_attribute_tier_price.update` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `tierPrices` (array, required) - Array of tier prices with the following structure: + - `customer_group_id` (string, optional) - Customer group ID or 'all' for all groups (default: 'all') + - `website` (string, optional) - Website code or 'all' for all websites (default: 'all') + - `qty` (float, required) - Quantity + - `price` (float, required) - Price +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "catalog_product_attribute_tier_price.update", + [ + "product1", + [ + { + "customer_group_id": "all", + "website": "all", + "qty": 2, + "price": 19.99 + }, + { + "customer_group_id": "1", + "website": "base", + "qty": 5, + "price": 17.99 + } + ], + "sku" + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `product_not_exists` - Product does not exist +- `data_invalid` - Invalid data provided +- `not_updated` - Tier prices could not be updated \ No newline at end of file diff --git a/docs/content/api/jsonrpc/cataloginventory_stock_item.md b/docs/content/api/jsonrpc/cataloginventory_stock_item.md new file mode 100644 index 00000000000..55e7179cda9 --- /dev/null +++ b/docs/content/api/jsonrpc/cataloginventory_stock_item.md @@ -0,0 +1,219 @@ +# Catalog Inventory Stock Item API + +## Introduction + +The Catalog Inventory Stock Item API allows you to manage product inventory in your OpenMage store. You can retrieve stock information for products and update stock data for individual or multiple products. This API is also sometimes referred to as the product_stock API. + +## Available Methods + +### list + +Retrieve stock information for products. + +**Method Name**: `cataloginventory_stock_item.list` + +**Parameters**: +- `productIds` (array, required) - Array of product IDs or SKUs +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (array) - Array of stock items with the following structure: + - `product_id` (int) - Product ID + - `sku` (string) - Product SKU + - `qty` (float) - Quantity + - `is_in_stock` (int) - Is in stock (1 - yes, 0 - no) + - `manage_stock` (int) - Manage stock (1 - yes, 0 - no) + - `use_config_manage_stock` (int) - Use config settings for managing stock (1 - yes, 0 - no) + - `min_qty` (float) - Minimum quantity + - `use_config_min_qty` (int) - Use config settings for minimum quantity (1 - yes, 0 - no) + - `min_sale_qty` (float) - Minimum sale quantity + - `use_config_min_sale_qty` (int) - Use config settings for minimum sale quantity (1 - yes, 0 - no) + - `max_sale_qty` (float) - Maximum sale quantity + - `use_config_max_sale_qty` (int) - Use config settings for maximum sale quantity (1 - yes, 0 - no) + - `is_qty_decimal` (int) - Is quantity decimal (1 - yes, 0 - no) + - `backorders` (int) - Backorders status (0 - No Backorders, 1 - Allow Qty Below 0, 2 - Allow Qty Below 0 and Notify Customer) + - `use_config_backorders` (int) - Use config settings for backorders (1 - yes, 0 - no) + - `notify_stock_qty` (float) - Notify quantity below + - `use_config_notify_stock_qty` (int) - Use config settings for notify quantity below (1 - yes, 0 - no) + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "cataloginventory_stock_item.list", + [["product1", "product2"], "sku"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "product_id": 1, + "sku": "product1", + "qty": 100.0000, + "is_in_stock": 1, + "manage_stock": 1, + "use_config_manage_stock": 0, + "min_qty": 0.0000, + "use_config_min_qty": 1, + "min_sale_qty": 1.0000, + "use_config_min_sale_qty": 1, + "max_sale_qty": 10000.0000, + "use_config_max_sale_qty": 1, + "is_qty_decimal": 0, + "backorders": 0, + "use_config_backorders": 1, + "notify_stock_qty": 1.0000, + "use_config_notify_stock_qty": 1 + }, + { + "product_id": 2, + "sku": "product2", + "qty": 50.0000, + "is_in_stock": 1, + "manage_stock": 1, + "use_config_manage_stock": 0, + "min_qty": 0.0000, + "use_config_min_qty": 1, + "min_sale_qty": 1.0000, + "use_config_min_sale_qty": 1, + "max_sale_qty": 10000.0000, + "use_config_max_sale_qty": 1, + "is_qty_decimal": 0, + "backorders": 0, + "use_config_backorders": 1, + "notify_stock_qty": 1.0000, + "use_config_notify_stock_qty": 1 + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- `product_not_exists` - One or more products do not exist + +### update + +Update stock information for a product. + +**Method Name**: `cataloginventory_stock_item.update` + +**Parameters**: +- `productId` (int|string, required) - Product ID or SKU +- `stockData` (array, required) - Stock data: + - `qty` (float, optional) - Quantity + - `is_in_stock` (int, optional) - Is in stock (1 - yes, 0 - no) + - `manage_stock` (int, optional) - Manage stock (1 - yes, 0 - no) + - `use_config_manage_stock` (int, optional) - Use config settings for managing stock (1 - yes, 0 - no) + - `min_qty` (float, optional) - Minimum quantity + - `use_config_min_qty` (int, optional) - Use config settings for minimum quantity (1 - yes, 0 - no) + - `min_sale_qty` (float, optional) - Minimum sale quantity + - `use_config_min_sale_qty` (int, optional) - Use config settings for minimum sale quantity (1 - yes, 0 - no) + - `max_sale_qty` (float, optional) - Maximum sale quantity + - `use_config_max_sale_qty` (int, optional) - Use config settings for maximum sale quantity (1 - yes, 0 - no) + - `is_qty_decimal` (int, optional) - Is quantity decimal (1 - yes, 0 - no) + - `backorders` (int, optional) - Backorders status (0 - No Backorders, 1 - Allow Qty Below 0, 2 - Allow Qty Below 0 and Notify Customer) + - `use_config_backorders` (int, optional) - Use config settings for backorders (1 - yes, 0 - no) + - `notify_stock_qty` (float, optional) - Notify quantity below + - `use_config_notify_stock_qty` (int, optional) - Use config settings for notify quantity below (1 - yes, 0 - no) +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "cataloginventory_stock_item.update", + [ + "product1", + { + "qty": 75.0000, + "is_in_stock": 1, + "manage_stock": 1 + }, + "sku" + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `product_not_exists` - Product does not exist +- `data_invalid` - Invalid data provided + +### multiUpdate + +Update stock information for multiple products in a single call. + +**Method Name**: `cataloginventory_stock_item.multiUpdate` + +**Parameters**: +- `productIds` (array, required) - Array of product IDs or SKUs +- `stockData` (array, required) - Stock data (same structure as in update method) +- `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "cataloginventory_stock_item.multiUpdate", + [ + ["product1", "product2"], + { + "qty": 100.0000, + "is_in_stock": 1 + }, + "sku" + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `product_not_exists` - One or more products do not exist +- `data_invalid` - Invalid data provided + +**Notes**: +- When updating stock information, you only need to include the fields you want to change. Other fields will retain their current values. +- The `use_config_*` fields determine whether to use the system configuration value for the corresponding setting. When set to 1, the system configuration value is used regardless of the value specified for the setting. +- When managing inventory for configurable, grouped, or bundle products, you should update the stock for the associated simple products, as the parent product's stock is calculated based on its child products. \ No newline at end of file diff --git a/docs/content/api/jsonrpc/customer.md b/docs/content/api/jsonrpc/customer.md new file mode 100644 index 00000000000..5287e8913f1 --- /dev/null +++ b/docs/content/api/jsonrpc/customer.md @@ -0,0 +1,323 @@ +# Customer API + +## Introduction + +The Customer API allows you to manage customers in your OpenMage store. You can retrieve customer information, create new customers, update existing ones, and delete customers. + +## Available Methods + +### list + +Retrieve list of customers with basic info. + +**Method Name**: `customer.list` + +**Parameters**: +- `filters` (object|array, optional) - Filters to apply to the list: + - `customer_id` (int|array) - Filter by customer ID(s) + - `email` (string|array) - Filter by email(s) + - `firstname` (string|array) - Filter by first name(s) + - `lastname` (string|array) - Filter by last name(s) + - `created_at` (string|array) - Filter by creation date + - `updated_at` (string|array) - Filter by update date + - `website_id` (int|array) - Filter by website ID(s) + - `group_id` (int|array) - Filter by customer group ID(s) + - Other attributes can also be used as filters +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (array) - Array of customers with the following structure: + - `customer_id` (int) - Customer ID + - `email` (string) - Customer email + - `firstname` (string) - Customer first name + - `lastname` (string) - Customer last name + - `created_at` (string) - Creation date + - `updated_at` (string) - Update date + - `website_id` (int) - Website ID + - `group_id` (int) - Customer group ID + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "customer.list", + [{"group_id": 1}] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "customer_id": 1, + "email": "john.doe@example.com", + "firstname": "John", + "lastname": "Doe", + "created_at": "2023-01-15 14:30:12", + "updated_at": "2023-01-15 14:30:12", + "website_id": 1, + "group_id": 1 + }, + { + "customer_id": 2, + "email": "jane.smith@example.com", + "firstname": "Jane", + "lastname": "Smith", + "created_at": "2023-01-16 09:45:23", + "updated_at": "2023-01-16 09:45:23", + "website_id": 1, + "group_id": 1 + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- `filters_invalid` - Invalid filters provided +- `store_not_exists` - Requested store does not exist + +### info + +Retrieve detailed customer information. + +**Method Name**: `customer.info` + +**Parameters**: +- `customerId` (int, required) - Customer ID +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (object) - Customer information with the following structure: + - `customer_id` (int) - Customer ID + - `email` (string) - Customer email + - `firstname` (string) - Customer first name + - `lastname` (string) - Customer last name + - `middlename` (string) - Customer middle name + - `prefix` (string) - Name prefix + - `suffix` (string) - Name suffix + - `created_at` (string) - Creation date + - `updated_at` (string) - Update date + - `website_id` (int) - Website ID + - `group_id` (int) - Customer group ID + - `dob` (string) - Date of birth + - `taxvat` (string) - Tax/VAT number + - `confirmation` (string) - Confirmation code + - `created_in` (string) - Store where customer was created + - `default_billing` (string) - Default billing address ID + - `default_shipping` (string) - Default shipping address ID + - `is_active` (int) - Whether customer is active (1 - yes, 0 - no) + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "customer.info", + [1, "default"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "customer_id": 1, + "email": "john.doe@example.com", + "firstname": "John", + "lastname": "Doe", + "middlename": "", + "prefix": "Mr", + "suffix": "", + "created_at": "2023-01-15 14:30:12", + "updated_at": "2023-01-15 14:30:12", + "website_id": 1, + "group_id": 1, + "dob": "1980-01-01", + "taxvat": "123456789", + "confirmation": null, + "created_in": "Default Store View", + "default_billing": "1", + "default_shipping": "1", + "is_active": 1 + }, + "id": 1 +} +``` + +**Possible Errors**: +- `customer_not_exists` - Customer does not exist +- `store_not_exists` - Requested store does not exist + +### create + +Create new customer. + +**Method Name**: `customer.create` + +**Parameters**: +- `customerData` (array, required) - Customer data: + - `email` (string, required) - Customer email + - `firstname` (string, required) - Customer first name + - `lastname` (string, required) - Customer last name + - `password` (string, required) - Customer password + - `website_id` (int, required) - Website ID + - `group_id` (int, optional) - Customer group ID + - `middlename` (string, optional) - Customer middle name + - `prefix` (string, optional) - Name prefix + - `suffix` (string, optional) - Name suffix + - `dob` (string, optional) - Date of birth (format: YYYY-MM-DD) + - `taxvat` (string, optional) - Tax/VAT number + - `is_subscribed` (boolean, optional) - Whether customer is subscribed to newsletter + - `store_id` (int, optional) - Store ID +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (int) - ID of the created customer + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "customer.create", + [ + { + "email": "new.customer@example.com", + "firstname": "New", + "lastname": "Customer", + "password": "password123", + "website_id": 1, + "group_id": 1, + "dob": "1985-05-15", + "taxvat": "987654321", + "is_subscribed": true + }, + "default" + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": 3, + "id": 1 +} +``` + +**Possible Errors**: +- `data_invalid` - Invalid data provided +- `customer_data_invalid` - Invalid customer data +- `customer_exists` - Customer with the same email already exists +- `website_not_exists` - Website does not exist +- `group_not_exists` - Customer group does not exist + +### update + +Update customer data. + +**Method Name**: `customer.update` + +**Parameters**: +- `customerId` (int, required) - Customer ID +- `customerData` (array, required) - Customer data to update (same structure as in create method, except password is optional) +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "customer.update", + [ + 1, + { + "firstname": "Updated", + "lastname": "Name", + "email": "updated.email@example.com" + }, + "default" + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `data_invalid` - Invalid data provided +- `customer_not_exists` - Customer does not exist +- `customer_data_invalid` - Invalid customer data +- `customer_exists` - Another customer with the same email already exists +- `website_not_exists` - Website does not exist +- `group_not_exists` - Customer group does not exist + +### delete + +Delete customer. + +**Method Name**: `customer.delete` + +**Parameters**: +- `customerId` (int, required) - Customer ID + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "customer.delete", + 1 + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `customer_not_exists` - Customer does not exist +- `not_deleted` - Customer could not be deleted \ No newline at end of file diff --git a/docs/content/api/jsonrpc/customer_address.md b/docs/content/api/jsonrpc/customer_address.md new file mode 100644 index 00000000000..fc3be88378c --- /dev/null +++ b/docs/content/api/jsonrpc/customer_address.md @@ -0,0 +1,297 @@ +# Customer Address API + +## Introduction + +The Customer Address API allows you to manage customer addresses in your OpenMage store. You can retrieve address information, create new addresses, update existing ones, and delete addresses. + +## Available Methods + +### list + +Retrieve list of addresses for a customer. + +**Method Name**: `customer_address.list` + +**Parameters**: +- `customerId` (int, required) - Customer ID + +**Return**: +- (array) - Array of addresses with the following structure: + - `customer_address_id` (int) - Customer address ID + - `created_at` (string) - Creation date + - `updated_at` (string) - Update date + - `is_default_billing` (boolean) - Whether this is the default billing address + - `is_default_shipping` (boolean) - Whether this is the default shipping address + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "customer_address.list", + 1 + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "customer_address_id": 1, + "created_at": "2023-01-15 14:30:12", + "updated_at": "2023-01-15 14:30:12", + "is_default_billing": true, + "is_default_shipping": true + }, + { + "customer_address_id": 2, + "created_at": "2023-01-16 09:45:23", + "updated_at": "2023-01-16 09:45:23", + "is_default_billing": false, + "is_default_shipping": false + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- `customer_not_exists` - Customer does not exist + +### info + +Retrieve detailed address information. + +**Method Name**: `customer_address.info` + +**Parameters**: +- `addressId` (int, required) - Customer address ID + +**Return**: +- (object) - Address information with the following structure: + - `customer_address_id` (int) - Customer address ID + - `customer_id` (int) - Customer ID + - `firstname` (string) - First name + - `lastname` (string) - Last name + - `middlename` (string) - Middle name + - `prefix` (string) - Name prefix + - `suffix` (string) - Name suffix + - `company` (string) - Company + - `street` (string) - Street address (may contain multiple lines) + - `city` (string) - City + - `region` (string) - Region/state name + - `region_id` (int) - Region/state ID + - `postcode` (string) - Postal code + - `country_id` (string) - Country ID (2-letter code) + - `telephone` (string) - Telephone number + - `fax` (string) - Fax number + - `is_default_billing` (boolean) - Whether this is the default billing address + - `is_default_shipping` (boolean) - Whether this is the default shipping address + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "customer_address.info", + 1 + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "customer_address_id": 1, + "customer_id": 1, + "firstname": "John", + "lastname": "Doe", + "middlename": "", + "prefix": "Mr", + "suffix": "", + "company": "Example Company", + "street": "123 Main St\nApt 4B", + "city": "Anytown", + "region": "California", + "region_id": 12, + "postcode": "12345", + "country_id": "US", + "telephone": "555-123-4567", + "fax": "555-123-4568", + "is_default_billing": true, + "is_default_shipping": true + }, + "id": 1 +} +``` + +**Possible Errors**: +- `address_not_exists` - Address does not exist + +### create + +Create new address for a customer. + +**Method Name**: `customer_address.create` + +**Parameters**: +- `customerId` (int, required) - Customer ID +- `addressData` (array, required) - Address data: + - `firstname` (string, required) - First name + - `lastname` (string, required) - Last name + - `street` (string|array, required) - Street address (string or array of lines) + - `city` (string, required) - City + - `country_id` (string, required) - Country ID (2-letter code) + - `telephone` (string, required) - Telephone number + - `postcode` (string, required for most countries) - Postal code + - `middlename` (string, optional) - Middle name + - `prefix` (string, optional) - Name prefix + - `suffix` (string, optional) - Name suffix + - `company` (string, optional) - Company + - `region` (string, optional) - Region/state name + - `region_id` (int, optional) - Region/state ID + - `fax` (string, optional) - Fax number + - `is_default_billing` (boolean, optional) - Whether this is the default billing address + - `is_default_shipping` (boolean, optional) - Whether this is the default shipping address + +**Return**: +- (int) - ID of the created address + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "customer_address.create", + [ + 1, + { + "firstname": "John", + "lastname": "Doe", + "street": ["123 Main St", "Apt 4B"], + "city": "Anytown", + "country_id": "US", + "region_id": 12, + "postcode": "12345", + "telephone": "555-123-4567", + "company": "Example Company", + "is_default_billing": false, + "is_default_shipping": false + } + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": 3, + "id": 1 +} +``` + +**Possible Errors**: +- `customer_not_exists` - Customer does not exist +- `data_invalid` - Invalid data provided + +### update + +Update customer address data. + +**Method Name**: `customer_address.update` + +**Parameters**: +- `addressId` (int, required) - Customer address ID +- `addressData` (array, required) - Address data to update (same structure as in create method) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "customer_address.update", + [ + 1, + { + "firstname": "Updated", + "lastname": "Name", + "telephone": "555-987-6543" + } + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `address_not_exists` - Address does not exist +- `data_invalid` - Invalid data provided + +### delete + +Delete customer address. + +**Method Name**: `customer_address.delete` + +**Parameters**: +- `addressId` (int, required) - Customer address ID + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "customer_address.delete", + 1 + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `address_not_exists` - Address does not exist +- `not_deleted` - Address could not be deleted \ No newline at end of file diff --git a/docs/content/api/jsonrpc/customer_group.md b/docs/content/api/jsonrpc/customer_group.md new file mode 100644 index 00000000000..d1780b7f61e --- /dev/null +++ b/docs/content/api/jsonrpc/customer_group.md @@ -0,0 +1,68 @@ +# Customer Group API + +## Introduction + +The Customer Group API allows you to manage customer groups in your OpenMage store. Customer groups are used to categorize customers and apply specific pricing rules, tax classes, and discounts to different customer segments. + +## Available Methods + +### list + +Retrieve list of customer groups. + +**Method Name**: `customer_group.list` + +**Parameters**: +- None + +**Return**: +- (array) - Array of customer groups with the following structure: + - `customer_group_id` (int) - Customer group ID + - `customer_group_code` (string) - Customer group name/code + - `tax_class_id` (int) - Tax class ID assigned to the customer group + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "customer_group.list" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "customer_group_id": 0, + "customer_group_code": "NOT LOGGED IN", + "tax_class_id": 3 + }, + { + "customer_group_id": 1, + "customer_group_code": "General", + "tax_class_id": 3 + }, + { + "customer_group_id": 2, + "customer_group_code": "Wholesale", + "tax_class_id": 3 + }, + { + "customer_group_id": 3, + "customer_group_code": "Retailer", + "tax_class_id": 3 + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- None specific to this method \ No newline at end of file diff --git a/docs/content/api/jsonrpc/index.md b/docs/content/api/jsonrpc/index.md new file mode 100644 index 00000000000..94cb2c3af92 --- /dev/null +++ b/docs/content/api/jsonrpc/index.md @@ -0,0 +1,429 @@ +# OpenMage JSON-RPC API Overview + +## Introduction + +The OpenMage API provides a standardized interface for third-party applications to interact with your OpenMage store. Using the API, developers can create applications that can: + +- Manage products, categories, and inventory +- Process orders and shipments +- Handle customer data +- Access sales and catalog information +- And much more + +This document focuses on the JSON-RPC implementation of the OpenMage API, which provides a lightweight, language-agnostic way to interact with your OpenMage store programmatically. + +## API Architecture Overview + +The OpenMage API is built on a modular architecture that supports multiple protocols: + +- **JSON-RPC**: A lightweight protocol that uses JSON for data encoding +- **XML-RPC**: Similar to JSON-RPC but uses XML for data encoding +- **SOAP**: A comprehensive web service protocol with formal WSDL definitions +- **REST**: See [OpenMage REST API](../rest/) for more information + +The JSON-RPC adapter is implemented in `Mage_Api_Model_Server_Adapter_Jsonrpc` and uses the Zend_Json_Server component to handle requests and responses. The API follows a resource-based architecture where functionality is organized into logical resources (like catalog, customer, sales) with methods that operate on those resources. + +### Key Components + +1. **API Entry Point**: The `api.php` file serves as the entry point for all API requests +2. **Server Adapter**: Handles protocol-specific details (JSON-RPC, XML-RPC, SOAP) +3. **Handler**: Processes API requests and maps them to the appropriate resource models +4. **Resource Models**: Implement the actual business logic for API operations +5. **ACL (Access Control List)**: Controls access to resources based on user permissions + +## Authentication + +To use the OpenMage API, you must either authenticate with the login method to obtain a session ID and inlcude this session ID with all subsequent API calls (not recommended), or use the HTTP Basic Authentication method (recommended). + +### Login Authentication Process + +1. **Create an API User**: In the OpenMage admin panel, go to System > Web Services > SOAP/XML-RPC - Users to create a user with appropriate role permissions +2. **Login Request**: Send a login request with your username and API key +3. **Session ID**: Receive a session ID that will be used for all subsequent requests +4. **Session Expiration**: Sessions expire after a period of inactivity (configurable in OpenMage settings) + +#### Login Authentication Example + +```json +// Login Request +{ + "jsonrpc": "2.0", + "method": "login", + "params": ["apiuser", "apikey123"], + "id": 1 +} + +// Login Response +{ + "jsonrpc": "2.0", + "result": "8b98a77a37f50d3d472302981e86aab2", + "id": 1 +} +``` + +### HTTP Basic Authentication + +As an alternative to session-based authentication, OpenMage also supports HTTP Basic Authentication for API requests. This method simplifies the authentication process by eliminating the need for a separate login step. + +#### How HTTP Basic Auth Works + +1. **Use API Credentials**: The API username and API key (created in admin panel) are used as the username and password for HTTP Basic Auth +2. **Skip Login Call**: When using HTTP Basic Auth, the "login" call is not required +3. **Null Session ID**: The session ID parameter in the "call" method can be set to "null" +4. **Include Auth Header**: Include the Authorization header with each request + +#### HTTP Basic Auth Example + +```php + '2.0', + 'method' => 'call', + 'params' => [ + null, // Null session ID when using HTTP Basic Auth + 'catalog_product.info', + 'product_sku_123' + ], + 'id' => 1 +); + +$ch = curl_init($jsonRpcUrl); +curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); +curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json')); +curl_setopt($ch, CURLOPT_USERPWD, "$apiUser:$apiKey"); // HTTP Basic Auth +curl_setopt($ch, CURLOPT_POST, true); +curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestData)); + +$response = curl_exec($ch); +curl_close($ch); + +$result = json_decode($response, true); +print_r($result['result']); +?> +``` + +## JSON-RPC 2.0 Request/Response Format + +The OpenMage API implements the JSON-RPC 2.0 specification, which defines a stateless, light-weight remote procedure call (RPC) protocol using JSON as the data format. + +### Request Format + +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "resource.method", + [param1, param2, ...] + ], + "id": request_id +} +``` + +- **jsonrpc**: Must be exactly "2.0" +- **method**: For most API calls, this will be "call" +- **params**: An array containing: + 1. The session ID obtained from login or `null` for HTTP Basic Auth + 2. The resource and method name in the format "resource.method" + 3. An array of parameters for the method +- **id**: A unique identifier for the request (can be a string or number) + +### Response Format + +```json +{ + "jsonrpc": "2.0", + "result": response_data, + "id": request_id +} +``` + +- **jsonrpc**: Always "2.0" +- **result**: The data returned by the method call +- **id**: The same ID that was sent in the request + +### Error Response Format + +```json +{ + "jsonrpc": "2.0", + "error": { + "code": error_code, + "message": "Error message" + }, + "id": request_id +} +``` + +## Error Handling + +The OpenMage API uses standardized error codes and messages to communicate issues with API requests. + +### Common Error Codes + +| Code | Message | Description | +|------|---------|-------------| +| 0 | Unknown Error | A general error occurred | +| 1 | Internal Error | An internal server error occurred | +| 2 | Access denied | Authentication failed or insufficient permissions | +| 3 | Invalid API path | The requested resource or method doesn't exist | +| 4 | Resource path is not callable | The requested method cannot be called | +| 5 | Session expired | The session has expired, need to login again | +| 6 | Invalid request parameter | A required parameter is missing or invalid | + +### HTTP Status Codes + +The API also uses HTTP status codes to indicate the status of requests: + +- **200 OK**: Request successful +- **400 Bad Request**: Invalid request parameters +- **401 Unauthorized**: Authentication required +- **403 Forbidden**: Access denied +- **404 Not Found**: Resource not found +- **500 Internal Server Error**: Server-side error + +## Common Usage Patterns + +### Basic Workflow + +1. **Authentication**: Login to obtain a session ID +2. **API Calls**: Make one or more API calls using the session ID +3. **End Session**: Optionally end the session when finished + +### Batch Operations with multiCall + +For improved performance when making multiple API calls, use the `multiCall` method to batch requests: + +```json +{ + "jsonrpc": "2.0", + "method": "multiCall", + "params": [ + "session_id", + [ + ["catalog_product.list", [filter_parameters]], + ["catalog_product.info", [product_id]] + ] + ], + "id": 1 +} +``` + +### Error Handling Best Practices + +1. **Always check for errors** in API responses +2. **Implement retry logic** for transient errors +3. **Handle session expiration** by re-authenticating +4. **Log detailed error information** for troubleshooting + +## Code Examples + +### Authentication + +```php + '2.0', + 'method' => 'login', + 'params' => ['apiuser', 'apikey123'], + 'id' => 1 +); + +$ch = curl_init($jsonRpcUrl); +curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); +curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json')); +curl_setopt($ch, CURLOPT_POST, true); +curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($userData)); + +$response = curl_exec($ch); +curl_close($ch); + +$result = json_decode($response, true); +$sessionId = $result['result']; +echo "Session ID: " . $sessionId; +?> +``` + +### Retrieving Product Information + +```php + '2.0', + 'method' => 'call', + 'params' => [ + $sessionId, + 'catalog_product.info', + 'product_sku_123' + ], + 'id' => 2 +); + +$ch = curl_init($jsonRpcUrl); +curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); +curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json')); +curl_setopt($ch, CURLOPT_POST, true); +curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestData)); + +$response = curl_exec($ch); +curl_close($ch); + +$result = json_decode($response, true); +print_r($result['result']); +?> +``` + +### Creating a New Product + +```php + 'simple', + 'attribute_set_id' => 4, + 'sku' => 'new_product_123', + 'name' => 'New Test Product', + 'price' => 99.99, + 'status' => 1, + 'weight' => 1.0, + 'visibility' => 4, + 'description' => 'Product description here', + 'short_description' => 'Short description', + 'stock_data' => array( + 'qty' => 100, + 'is_in_stock' => 1 + ) +); + +$requestData = array( + 'jsonrpc' => '2.0', + 'method' => 'call', + 'params' => [ + $sessionId, + 'catalog_product.create', + ['simple', 4, 'new_product_123', $productData] + ], + 'id' => 3 +); + +$ch = curl_init($jsonRpcUrl); +curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); +curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json')); +curl_setopt($ch, CURLOPT_POST, true); +curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestData)); + +$response = curl_exec($ch); +curl_close($ch); + +$result = json_decode($response, true); +echo "Product ID: " . $result['result']; +?> +``` + +## Available Resources + +The OpenMage API provides access to numerous resources. Here are the main resource categories: + +### Catalog Resources + +- **catalog_category**: Manage product categories + - [catalog_category.create](catalog_category.md#create) + - [catalog_category.update](catalog_category.md#update) + - [catalog_category.move](catalog_category.md#move) + - [catalog_category.delete](catalog_category.md#delete) + - [catalog_category.tree](catalog_category.md#tree) + - [catalog_category.info](catalog_category.md#info) + - [catalog_category.level](catalog_category.md#level) + +- **catalog_product**: Manage products + - [catalog_product.create](catalog_product.md#create) + - [catalog_product.update](catalog_product.md#update) + - [catalog_product.delete](catalog_product.md#delete) + - [catalog_product.info](catalog_product.md#info) + - [catalog_product.list](catalog_product.md#list) + - [catalog_product.attributes](catalog_product.md#attributes) + +### Customer Resources + +- **customer**: Manage customers + - [customer.create](customer.md#create) + - [customer.update](customer.md#update) + - [customer.delete](customer.md#delete) + - [customer.info](customer.md#info) + - [customer.list](customer.md#list) + +- **customer_address**: Manage customer addresses + - [customer_address.create](customer_address.md#create) + - [customer_address.update](customer_address.md#update) + - [customer_address.delete](customer_address.md#delete) + - [customer_address.info](customer_address.md#info) + - [customer_address.list](customer_address.md#list) + +### Sales Resources + +- **sales_order**: Manage orders + - [sales_order.info](sales_order.md#info) + - [sales_order.list](sales_order.md#list) + - [sales_order.addComment](sales_order.md#addComment) + - [sales_order.hold](sales_order.md#hold) + - [sales_order.unhold](sales_order.md#unhold) + - [sales_order.cancel](sales_order.md#cancel) + +- **sales_order_invoice**: Manage invoices + - [sales_order_invoice.create](sales_order_invoice.md#create) + - [sales_order_invoice.info](sales_order_invoice.md#info) + - [sales_order_invoice.list](sales_order_invoice.md#list) + +- **sales_order_shipment**: Manage shipments + - [sales_order_shipment.create](sales_order_shipment.md#create) + - [sales_order_shipment.info](sales_order_shipment.md#info) + - [sales_order_shipment.list](sales_order_shipment.md#list) + +### Inventory Resources + +- **cataloginventory_stock_item**: Manage inventory + - [cataloginventory_stock_item.list](cataloginventory_stock_item.md#list) + - [cataloginventory_stock_item.update](cataloginventory_stock_item.md#update) + +### Other Resources + +- **directory**: Access region and country information + - [directory.countries](directory.md#countries) + - [directory.regions](directory.md#regions) + +- **core**: Core functionality + - [core.resources](core.md#resources) + - [core.globalFaults](core.md#globalFaults) + +## Best Practices + +1. **Use HTTPS**: Always use HTTPS for API calls to ensure secure communication +2. **Implement Rate Limiting**: Avoid overwhelming the server with too many requests +3. **Cache Responses**: Cache responses when appropriate to reduce API calls +4. **Handle Errors Gracefully**: Implement proper error handling in your applications +5. **Use Batch Operations**: Use multiCall for better performance when making multiple requests +6. **Validate Input**: Always validate input data before sending it to the API +7. **Monitor API Usage**: Keep track of API usage to identify potential issues +8. **Keep API Keys Secure**: Never expose API keys in client-side code + +## Conclusion + +The OpenMage JSON-RPC API provides a powerful and flexible way to interact with your OpenMage store programmatically. By following the guidelines and examples in this document, you can build robust integrations with your OpenMage store. + +For more detailed information about specific resources and methods, please refer to the individual resource documentation pages linked in the "Available Resources" section. \ No newline at end of file diff --git a/docs/content/api/jsonrpc/sales_order.md b/docs/content/api/jsonrpc/sales_order.md new file mode 100644 index 00000000000..97d02ac9f3d --- /dev/null +++ b/docs/content/api/jsonrpc/sales_order.md @@ -0,0 +1,375 @@ +# Sales Order API + +## Introduction + +The Sales Order API allows you to manage orders in your OpenMage store. You can retrieve order information, add comments to orders, and perform various order operations such as holding, unholding, and canceling orders. + +## Available Methods + +### list + +Retrieve list of orders with basic info. + +**Method Name**: `sales_order.list` + +**Parameters**: +- `filters` (object|array, optional) - Filters to apply to the list: + - `order_id` (int|array) - Filter by order ID(s) + - `status` (string|array) - Filter by order status(es) + - `state` (string|array) - Filter by order state(s) + - `customer_id` (int|array) - Filter by customer ID(s) + - `created_at` (string|array) - Filter by creation date + - `updated_at` (string|array) - Filter by update date + - Other attributes can also be used as filters +- `store` (string|int, optional) - Store ID or code + +**Return**: +- (array) - Array of orders with the following structure: + - `increment_id` (string) - Order increment ID + - `order_id` (int) - Order ID + - `created_at` (string) - Creation date + - `updated_at` (string) - Update date + - `status` (string) - Order status + - `state` (string) - Order state + - `customer_id` (int) - Customer ID + - `base_grand_total` (float) - Base grand total + - `grand_total` (float) - Grand total + - `store_id` (int) - Store ID + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order.list", + [{"status": "pending"}] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "increment_id": "100000001", + "order_id": 1, + "created_at": "2023-01-15 14:30:12", + "updated_at": "2023-01-15 14:30:12", + "status": "pending", + "state": "new", + "customer_id": 1, + "base_grand_total": 150.00, + "grand_total": 150.00, + "store_id": 1 + }, + { + "increment_id": "100000002", + "order_id": 2, + "created_at": "2023-01-16 09:45:23", + "updated_at": "2023-01-16 09:45:23", + "status": "pending", + "state": "new", + "customer_id": 2, + "base_grand_total": 75.50, + "grand_total": 75.50, + "store_id": 1 + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- `filters_invalid` - Invalid filters provided +- `store_not_exists` - Requested store does not exist + +### info + +Retrieve detailed order information. + +**Method Name**: `sales_order.info` + +**Parameters**: +- `orderIncrementId` (string, required) - Order increment ID + +**Return**: +- (object) - Order information with the following structure: + - `increment_id` (string) - Order increment ID + - `order_id` (int) - Order ID + - `created_at` (string) - Creation date + - `updated_at` (string) - Update date + - `status` (string) - Order status + - `state` (string) - Order state + - `customer_id` (int) - Customer ID + - `customer_firstname` (string) - Customer first name + - `customer_lastname` (string) - Customer last name + - `customer_email` (string) - Customer email + - `base_grand_total` (float) - Base grand total + - `grand_total` (float) - Grand total + - `base_subtotal` (float) - Base subtotal + - `subtotal` (float) - Subtotal + - `base_shipping_amount` (float) - Base shipping amount + - `shipping_amount` (float) - Shipping amount + - `base_tax_amount` (float) - Base tax amount + - `tax_amount` (float) - Tax amount + - `store_id` (int) - Store ID + - `shipping_address` (object) - Shipping address information + - `billing_address` (object) - Billing address information + - `items` (array) - Array of order items + - `payment` (object) - Payment information + - `status_history` (array) - Order status history + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order.info", + "100000001" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "increment_id": "100000001", + "order_id": 1, + "created_at": "2023-01-15 14:30:12", + "updated_at": "2023-01-15 14:30:12", + "status": "pending", + "state": "new", + "customer_id": 1, + "customer_firstname": "John", + "customer_lastname": "Doe", + "customer_email": "john.doe@example.com", + "base_grand_total": 150.00, + "grand_total": 150.00, + "base_subtotal": 140.00, + "subtotal": 140.00, + "base_shipping_amount": 10.00, + "shipping_amount": 10.00, + "base_tax_amount": 0.00, + "tax_amount": 0.00, + "store_id": 1, + "shipping_address": { + "firstname": "John", + "lastname": "Doe", + "street": "123 Main St", + "city": "Anytown", + "region": "California", + "postcode": "12345", + "country_id": "US", + "telephone": "555-123-4567" + }, + "billing_address": { + "firstname": "John", + "lastname": "Doe", + "street": "123 Main St", + "city": "Anytown", + "region": "California", + "postcode": "12345", + "country_id": "US", + "telephone": "555-123-4567" + }, + "items": [ + { + "item_id": 1, + "product_id": 123, + "sku": "product123", + "name": "Test Product", + "qty_ordered": 2, + "price": 70.00, + "base_price": 70.00, + "row_total": 140.00, + "base_row_total": 140.00 + } + ], + "payment": { + "method": "checkmo", + "amount_ordered": 150.00, + "base_amount_ordered": 150.00 + }, + "status_history": [ + { + "created_at": "2023-01-15 14:30:12", + "status": "pending", + "comment": "Order placed" + } + ] + }, + "id": 1 +} +``` + +**Possible Errors**: +- `order_not_exists` - Order does not exist + +### addComment + +Add a comment to an order. + +**Method Name**: `sales_order.addComment` + +**Parameters**: +- `orderIncrementId` (string, required) - Order increment ID +- `status` (string, required) - Order status +- `comment` (string, optional) - Comment text +- `notify` (boolean, optional) - Whether to notify customer (default: false) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order.addComment", + ["100000001", "processing", "Order is being processed", true] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `order_not_exists` - Order does not exist +- `status_not_exists` - Status does not exist + +### hold + +Place an order on hold. + +**Method Name**: `sales_order.hold` + +**Parameters**: +- `orderIncrementId` (string, required) - Order increment ID + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order.hold", + "100000001" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `order_not_exists` - Order does not exist +- `order_not_holdable` - Order cannot be put on hold + +### unhold + +Release an order from hold. + +**Method Name**: `sales_order.unhold` + +**Parameters**: +- `orderIncrementId` (string, required) - Order increment ID + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order.unhold", + "100000001" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `order_not_exists` - Order does not exist +- `order_not_unholdable` - Order is not on hold + +### cancel + +Cancel an order. + +**Method Name**: `sales_order.cancel` + +**Parameters**: +- `orderIncrementId` (string, required) - Order increment ID + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order.cancel", + "100000001" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `order_not_exists` - Order does not exist +- `order_not_cancelable` - Order cannot be canceled \ No newline at end of file diff --git a/docs/content/api/jsonrpc/sales_order_creditmemo.md b/docs/content/api/jsonrpc/sales_order_creditmemo.md new file mode 100644 index 00000000000..06377e91cf5 --- /dev/null +++ b/docs/content/api/jsonrpc/sales_order_creditmemo.md @@ -0,0 +1,323 @@ +# Sales Order Credit Memo API + +## Introduction + +The Sales Order Credit Memo API allows you to manage credit memos in your OpenMage store. You can retrieve credit memo information, create new credit memos, add comments, and cancel credit memos. + +## Available Methods + +### list + +Retrieve list of credit memos with basic info. + +**Method Name**: `sales_order_creditmemo.list` + +**Parameters**: +- `filters` (object|array, optional) - Filters to apply to the list: + - `creditmemo_id` (int|array) - Filter by credit memo ID(s) + - `order_id` (int|array) - Filter by order ID(s) + - `increment_id` (string|array) - Filter by increment ID(s) + - `created_at` (string|array) - Filter by creation date + - `order_increment_id` (string|array) - Filter by order increment ID(s) + - Other attributes can also be used as filters + +**Return**: +- (array) - Array of credit memos with the following structure: + - `increment_id` (string) - Credit memo increment ID + - `creditmemo_id` (int) - Credit memo ID + - `order_id` (int) - Order ID + - `order_increment_id` (string) - Order increment ID + - `created_at` (string) - Creation date + - `state` (int) - Credit memo state + - `grand_total` (float) - Grand total + - `store_id` (int) - Store ID + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_creditmemo.list", + [{"order_increment_id": "100000001"}] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "increment_id": "100000001", + "creditmemo_id": 1, + "order_id": 1, + "order_increment_id": "100000001", + "created_at": "2023-01-17 09:45:20", + "state": 2, + "grand_total": 150.00, + "store_id": 1 + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- `filters_invalid` - Invalid filters provided + +### info + +Retrieve detailed credit memo information. + +**Method Name**: `sales_order_creditmemo.info` + +**Parameters**: +- `creditmemoIncrementId` (string, required) - Credit memo increment ID + +**Return**: +- (object) - Credit memo information with the following structure: + - `increment_id` (string) - Credit memo increment ID + - `creditmemo_id` (int) - Credit memo ID + - `order_id` (int) - Order ID + - `order_increment_id` (string) - Order increment ID + - `created_at` (string) - Creation date + - `state` (int) - Credit memo state + - `grand_total` (float) - Grand total + - `subtotal` (float) - Subtotal + - `adjustment_positive` (float) - Positive adjustment + - `adjustment_negative` (float) - Negative adjustment + - `shipping_amount` (float) - Shipping amount + - `tax_amount` (float) - Tax amount + - `store_id` (int) - Store ID + - `billing_address` (object) - Billing address information + - `shipping_address` (object) - Shipping address information + - `items` (array) - Array of credit memo items + - `comments` (array) - Array of credit memo comments + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_creditmemo.info", + "100000001" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "increment_id": "100000001", + "creditmemo_id": 1, + "order_id": 1, + "order_increment_id": "100000001", + "created_at": "2023-01-17 09:45:20", + "state": 2, + "grand_total": 150.00, + "subtotal": 140.00, + "adjustment_positive": 0.00, + "adjustment_negative": 0.00, + "shipping_amount": 10.00, + "tax_amount": 0.00, + "store_id": 1, + "billing_address": { + "firstname": "John", + "lastname": "Doe", + "street": "123 Main St", + "city": "Anytown", + "region": "California", + "postcode": "12345", + "country_id": "US", + "telephone": "555-123-4567" + }, + "shipping_address": { + "firstname": "John", + "lastname": "Doe", + "street": "123 Main St", + "city": "Anytown", + "region": "California", + "postcode": "12345", + "country_id": "US", + "telephone": "555-123-4567" + }, + "items": [ + { + "item_id": 1, + "parent_id": 1, + "sku": "product123", + "name": "Test Product", + "qty": 2.0000, + "price": 70.00, + "tax_amount": 0.00, + "row_total": 140.00, + "order_item_id": 1 + } + ], + "comments": [ + { + "comment_id": 1, + "parent_id": 1, + "created_at": "2023-01-17 09:45:20", + "comment": "Credit memo created" + } + ] + }, + "id": 1 +} +``` + +**Possible Errors**: +- `creditmemo_not_exists` - Credit memo does not exist + +### create + +Create a new credit memo for an order. + +**Method Name**: `sales_order_creditmemo.create` + +**Parameters**: +- `orderIncrementId` (string, required) - Order increment ID +- `creditmemoData` (object, optional) - Credit memo data: + - `items` (array, optional) - Array of items to refund: + - `order_item_id` (int) - Order item ID + - `qty` (float) - Quantity to refund + - `comment` (string, optional) - Credit memo comment + - `adjustment_positive` (float, optional) - Positive adjustment amount + - `adjustment_negative` (float, optional) - Negative adjustment amount + - `shipping_amount` (float, optional) - Shipping amount to refund + - `refund_to_store_credit` (boolean, optional) - Whether to refund to store credit +- `comment` (string, optional) - Credit memo comment +- `email` (boolean, optional) - Whether to send email notification (default: false) +- `includeComment` (boolean, optional) - Whether to include comment in email (default: false) + +**Return**: +- (string) - Credit memo increment ID + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_creditmemo.create", + [ + "100000001", + { + "items": { + "1": {"qty": 2} + }, + "shipping_amount": 10.00 + }, + "Credit memo created", + true, + true + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": "100000001", + "id": 1 +} +``` + +**Possible Errors**: +- `order_not_exists` - Order does not exist +- `order_not_refundable` - Order cannot be refunded +- `data_invalid` - Invalid data provided + +### addComment + +Add a comment to a credit memo. + +**Method Name**: `sales_order_creditmemo.addComment` + +**Parameters**: +- `creditmemoIncrementId` (string, required) - Credit memo increment ID +- `comment` (string, required) - Comment text +- `email` (boolean, optional) - Whether to send email notification (default: false) +- `includeInEmail` (boolean, optional) - Whether to include comment in email (default: false) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_creditmemo.addComment", + ["100000001", "Refund processed", true, true] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `creditmemo_not_exists` - Credit memo does not exist + +### cancel + +Cancel a credit memo. + +**Method Name**: `sales_order_creditmemo.cancel` + +**Parameters**: +- `creditmemoIncrementId` (string, required) - Credit memo increment ID + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_creditmemo.cancel", + "100000001" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `creditmemo_not_exists` - Credit memo does not exist +- `creditmemo_not_cancelable` - Credit memo cannot be canceled \ No newline at end of file diff --git a/docs/content/api/jsonrpc/sales_order_invoice.md b/docs/content/api/jsonrpc/sales_order_invoice.md new file mode 100644 index 00000000000..c22a1412a92 --- /dev/null +++ b/docs/content/api/jsonrpc/sales_order_invoice.md @@ -0,0 +1,389 @@ +# Sales Order Invoice API + +## Introduction + +The Sales Order Invoice API allows you to manage invoices in your OpenMage store. You can retrieve invoice information, create new invoices, add comments, and perform various invoice operations such as capturing payment, voiding, and canceling invoices. + +## Available Methods + +### list + +Retrieve list of invoices with basic info. + +**Method Name**: `sales_order_invoice.list` + +**Parameters**: +- `filters` (object|array, optional) - Filters to apply to the list: + - `invoice_id` (int|array) - Filter by invoice ID(s) + - `order_id` (int|array) - Filter by order ID(s) + - `increment_id` (string|array) - Filter by increment ID(s) + - `created_at` (string|array) - Filter by creation date + - `order_increment_id` (string|array) - Filter by order increment ID(s) + - `state` (int|array) - Filter by state(s) + - Other attributes can also be used as filters + +**Return**: +- (array) - Array of invoices with the following structure: + - `increment_id` (string) - Invoice increment ID + - `invoice_id` (int) - Invoice ID + - `order_id` (int) - Order ID + - `order_increment_id` (string) - Order increment ID + - `created_at` (string) - Creation date + - `state` (int) - Invoice state + - `grand_total` (float) - Grand total + - `store_id` (int) - Store ID + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_invoice.list", + [{"order_increment_id": "100000001"}] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "increment_id": "100000001", + "invoice_id": 1, + "order_id": 1, + "order_increment_id": "100000001", + "created_at": "2023-01-16 11:15:30", + "state": 2, + "grand_total": 150.00, + "store_id": 1 + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- `filters_invalid` - Invalid filters provided + +### info + +Retrieve detailed invoice information. + +**Method Name**: `sales_order_invoice.info` + +**Parameters**: +- `invoiceIncrementId` (string, required) - Invoice increment ID + +**Return**: +- (object) - Invoice information with the following structure: + - `increment_id` (string) - Invoice increment ID + - `invoice_id` (int) - Invoice ID + - `order_id` (int) - Order ID + - `order_increment_id` (string) - Order increment ID + - `created_at` (string) - Creation date + - `state` (int) - Invoice state + - `grand_total` (float) - Grand total + - `subtotal` (float) - Subtotal + - `tax_amount` (float) - Tax amount + - `shipping_amount` (float) - Shipping amount + - `discount_amount` (float) - Discount amount + - `store_id` (int) - Store ID + - `billing_address` (object) - Billing address information + - `shipping_address` (object) - Shipping address information + - `items` (array) - Array of invoice items + - `comments` (array) - Array of invoice comments + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_invoice.info", + "100000001" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "increment_id": "100000001", + "invoice_id": 1, + "order_id": 1, + "order_increment_id": "100000001", + "created_at": "2023-01-16 11:15:30", + "state": 2, + "grand_total": 150.00, + "subtotal": 140.00, + "tax_amount": 0.00, + "shipping_amount": 10.00, + "discount_amount": 0.00, + "store_id": 1, + "billing_address": { + "firstname": "John", + "lastname": "Doe", + "street": "123 Main St", + "city": "Anytown", + "region": "California", + "postcode": "12345", + "country_id": "US", + "telephone": "555-123-4567" + }, + "shipping_address": { + "firstname": "John", + "lastname": "Doe", + "street": "123 Main St", + "city": "Anytown", + "region": "California", + "postcode": "12345", + "country_id": "US", + "telephone": "555-123-4567" + }, + "items": [ + { + "item_id": 1, + "parent_id": 1, + "sku": "product123", + "name": "Test Product", + "qty": 2.0000, + "price": 70.00, + "tax_amount": 0.00, + "row_total": 140.00, + "order_item_id": 1 + } + ], + "comments": [ + { + "comment_id": 1, + "parent_id": 1, + "created_at": "2023-01-16 11:15:30", + "comment": "Invoice created" + } + ] + }, + "id": 1 +} +``` + +**Possible Errors**: +- `invoice_not_exists` - Invoice does not exist + +### create + +Create a new invoice for an order. + +**Method Name**: `sales_order_invoice.create` + +**Parameters**: +- `orderIncrementId` (string, required) - Order increment ID +- `itemsQty` (array, optional) - Array of items to invoice with quantities: + - `order_item_id` (int) - Order item ID + - `qty` (float) - Quantity to invoice +- `comment` (string, optional) - Invoice comment +- `email` (boolean, optional) - Whether to send email notification (default: false) +- `includeComment` (boolean, optional) - Whether to include comment in email (default: false) + +**Return**: +- (string) - Invoice increment ID + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_invoice.create", + [ + "100000001", + {"1": 2}, + "Invoice created", + true, + true + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": "100000001", + "id": 1 +} +``` + +**Possible Errors**: +- `order_not_exists` - Order does not exist +- `order_not_invoiceable` - Order cannot be invoiced +- `data_invalid` - Invalid data provided + +### addComment + +Add a comment to an invoice. + +**Method Name**: `sales_order_invoice.addComment` + +**Parameters**: +- `invoiceIncrementId` (string, required) - Invoice increment ID +- `comment` (string, required) - Comment text +- `email` (boolean, optional) - Whether to send email notification (default: false) +- `includeInEmail` (boolean, optional) - Whether to include comment in email (default: false) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_invoice.addComment", + ["100000001", "Payment received", true, true] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `invoice_not_exists` - Invoice does not exist + +### capture + +Capture an invoice. + +**Method Name**: `sales_order_invoice.capture` + +**Parameters**: +- `invoiceIncrementId` (string, required) - Invoice increment ID + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_invoice.capture", + "100000001" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `invoice_not_exists` - Invoice does not exist +- `invoice_not_capturable` - Invoice cannot be captured + +### void + +Void an invoice. + +**Method Name**: `sales_order_invoice.void` + +**Parameters**: +- `invoiceIncrementId` (string, required) - Invoice increment ID + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_invoice.void", + "100000001" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `invoice_not_exists` - Invoice does not exist +- `invoice_not_voidable` - Invoice cannot be voided + +### cancel + +Cancel an invoice. + +**Method Name**: `sales_order_invoice.cancel` + +**Parameters**: +- `invoiceIncrementId` (string, required) - Invoice increment ID + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_invoice.cancel", + "100000001" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `invoice_not_exists` - Invoice does not exist +- `invoice_not_cancelable` - Invoice cannot be canceled \ No newline at end of file diff --git a/docs/content/api/jsonrpc/sales_order_shipment.md b/docs/content/api/jsonrpc/sales_order_shipment.md new file mode 100644 index 00000000000..5f37d109978 --- /dev/null +++ b/docs/content/api/jsonrpc/sales_order_shipment.md @@ -0,0 +1,433 @@ +# Sales Order Shipment API + +## Introduction + +The Sales Order Shipment API allows you to manage shipments in your OpenMage store. You can retrieve shipment information, create new shipments, add comments, and manage tracking information. + +## Available Methods + +### list + +Retrieve list of shipments with basic info. + +**Method Name**: `sales_order_shipment.list` + +**Parameters**: +- `filters` (object|array, optional) - Filters to apply to the list: + - `shipment_id` (int|array) - Filter by shipment ID(s) + - `order_id` (int|array) - Filter by order ID(s) + - `increment_id` (string|array) - Filter by increment ID(s) + - `created_at` (string|array) - Filter by creation date + - `order_increment_id` (string|array) - Filter by order increment ID(s) + - Other attributes can also be used as filters + +**Return**: +- (array) - Array of shipments with the following structure: + - `increment_id` (string) - Shipment increment ID + - `shipment_id` (int) - Shipment ID + - `order_id` (int) - Order ID + - `order_increment_id` (string) - Order increment ID + - `created_at` (string) - Creation date + - `total_qty` (float) - Total quantity + - `store_id` (int) - Store ID + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_shipment.list", + [{"order_increment_id": "100000001"}] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "increment_id": "100000001", + "shipment_id": 1, + "order_id": 1, + "order_increment_id": "100000001", + "created_at": "2023-01-16 10:30:45", + "total_qty": 2.0000, + "store_id": 1 + } + ], + "id": 1 +} +``` + +**Possible Errors**: +- `filters_invalid` - Invalid filters provided + +### info + +Retrieve detailed shipment information. + +**Method Name**: `sales_order_shipment.info` + +**Parameters**: +- `shipmentIncrementId` (string, required) - Shipment increment ID + +**Return**: +- (object) - Shipment information with the following structure: + - `increment_id` (string) - Shipment increment ID + - `shipment_id` (int) - Shipment ID + - `order_id` (int) - Order ID + - `order_increment_id` (string) - Order increment ID + - `created_at` (string) - Creation date + - `total_qty` (float) - Total quantity + - `store_id` (int) - Store ID + - `shipping_address` (object) - Shipping address information + - `billing_address` (object) - Billing address information + - `items` (array) - Array of shipped items + - `tracks` (array) - Array of tracking information + - `comments` (array) - Array of shipment comments + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_shipment.info", + "100000001" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "increment_id": "100000001", + "shipment_id": 1, + "order_id": 1, + "order_increment_id": "100000001", + "created_at": "2023-01-16 10:30:45", + "total_qty": 2.0000, + "store_id": 1, + "shipping_address": { + "firstname": "John", + "lastname": "Doe", + "street": "123 Main St", + "city": "Anytown", + "region": "California", + "postcode": "12345", + "country_id": "US", + "telephone": "555-123-4567" + }, + "billing_address": { + "firstname": "John", + "lastname": "Doe", + "street": "123 Main St", + "city": "Anytown", + "region": "California", + "postcode": "12345", + "country_id": "US", + "telephone": "555-123-4567" + }, + "items": [ + { + "item_id": 1, + "parent_id": 1, + "sku": "product123", + "name": "Test Product", + "qty": 2.0000, + "price": 70.00, + "weight": 1.00, + "order_item_id": 1 + } + ], + "tracks": [ + { + "track_id": 1, + "parent_id": 1, + "track_number": "1Z12345E0291980793", + "title": "UPS", + "carrier_code": "ups", + "created_at": "2023-01-16 10:35:12" + } + ], + "comments": [ + { + "comment_id": 1, + "parent_id": 1, + "created_at": "2023-01-16 10:30:45", + "comment": "Shipment created" + } + ] + }, + "id": 1 +} +``` + +**Possible Errors**: +- `shipment_not_exists` - Shipment does not exist + +### create + +Create a new shipment for an order. + +**Method Name**: `sales_order_shipment.create` + +**Parameters**: +- `orderIncrementId` (string, required) - Order increment ID +- `itemsQty` (array, optional) - Array of items to ship with quantities: + - `order_item_id` (int) - Order item ID + - `qty` (float) - Quantity to ship +- `comment` (string, optional) - Shipment comment +- `email` (boolean, optional) - Whether to send email notification (default: false) +- `includeComment` (boolean, optional) - Whether to include comment in email (default: false) + +**Return**: +- (string) - Shipment increment ID + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_shipment.create", + [ + "100000001", + {"1": 2}, + "Shipment created", + true, + true + ] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": "100000001", + "id": 1 +} +``` + +**Possible Errors**: +- `order_not_exists` - Order does not exist +- `order_not_shippable` - Order cannot be shipped +- `data_invalid` - Invalid data provided + +### addComment + +Add a comment to a shipment. + +**Method Name**: `sales_order_shipment.addComment` + +**Parameters**: +- `shipmentIncrementId` (string, required) - Shipment increment ID +- `comment` (string, required) - Comment text +- `email` (boolean, optional) - Whether to send email notification (default: false) +- `includeInEmail` (boolean, optional) - Whether to include comment in email (default: false) + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_shipment.addComment", + ["100000001", "Package has been shipped", true, true] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `shipment_not_exists` - Shipment does not exist + +### addTrack + +Add tracking information to a shipment. + +**Method Name**: `sales_order_shipment.addTrack` + +**Parameters**: +- `shipmentIncrementId` (string, required) - Shipment increment ID +- `carrier` (string, required) - Carrier code +- `title` (string, required) - Carrier title +- `trackNumber` (string, required) - Tracking number + +**Return**: +- (int) - Tracking ID + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_shipment.addTrack", + ["100000001", "ups", "UPS", "1Z12345E0291980793"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": 1, + "id": 1 +} +``` + +**Possible Errors**: +- `shipment_not_exists` - Shipment does not exist +- `data_invalid` - Invalid data provided + +### removeTrack + +Remove tracking information from a shipment. + +**Method Name**: `sales_order_shipment.removeTrack` + +**Parameters**: +- `shipmentIncrementId` (string, required) - Shipment increment ID +- `trackId` (int, required) - Tracking ID + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_shipment.removeTrack", + ["100000001", 1] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `shipment_not_exists` - Shipment does not exist +- `track_not_exists` - Tracking information does not exist + +### sendInfo + +Send shipment information to the customer. + +**Method Name**: `sales_order_shipment.sendInfo` + +**Parameters**: +- `shipmentIncrementId` (string, required) - Shipment increment ID +- `comment` (string, optional) - Comment to include in the email + +**Return**: +- (boolean) - True on success + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_shipment.sendInfo", + ["100000001", "Your order has been shipped"] + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": true, + "id": 1 +} +``` + +**Possible Errors**: +- `shipment_not_exists` - Shipment does not exist + +### getCarriers + +Get list of available shipping carriers. + +**Method Name**: `sales_order_shipment.getCarriers` + +**Parameters**: +- `orderIncrementId` (string, required) - Order increment ID + +**Return**: +- (object) - Object with carrier codes as keys and carrier titles as values + +**Example Request**: +```json +{ + "jsonrpc": "2.0", + "method": "call", + "params": [ + "session_id", + "sales_order_shipment.getCarriers", + "100000001" + ], + "id": 1 +} +``` + +**Example Response**: +```json +{ + "jsonrpc": "2.0", + "result": { + "ups": "United Parcel Service", + "usps": "United States Postal Service", + "fedex": "Federal Express", + "dhl": "DHL" + }, + "id": 1 +} +``` + +**Possible Errors**: +- `order_not_exists` - Order does not exist \ No newline at end of file From 909cb59b905348ef7952c5f570f34953c527ddce Mon Sep 17 00:00:00 2001 From: Colin Mollenhour Date: Tue, 13 May 2025 10:43:00 -0400 Subject: [PATCH 2/7] Some manual improvements --- docs/content/api/jsonrpc/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/content/api/jsonrpc/index.md b/docs/content/api/jsonrpc/index.md index 94cb2c3af92..992f36aacdc 100644 --- a/docs/content/api/jsonrpc/index.md +++ b/docs/content/api/jsonrpc/index.md @@ -19,13 +19,13 @@ The OpenMage API is built on a modular architecture that supports multiple proto - **JSON-RPC**: A lightweight protocol that uses JSON for data encoding - **XML-RPC**: Similar to JSON-RPC but uses XML for data encoding - **SOAP**: A comprehensive web service protocol with formal WSDL definitions -- **REST**: See [OpenMage REST API](../rest/) for more information +- **REST**: See [OpenMage REST API](../rest/common_http_status_codes/) for more information -The JSON-RPC adapter is implemented in `Mage_Api_Model_Server_Adapter_Jsonrpc` and uses the Zend_Json_Server component to handle requests and responses. The API follows a resource-based architecture where functionality is organized into logical resources (like catalog, customer, sales) with methods that operate on those resources. +The JSON-RPC adapter is implemented in `Mage_Api_Model_Server_Adapter_Jsonrpc` and uses the `Zend_Json_Server` component to handle requests and responses. The API follows a resource-based architecture where functionality is organized into logical resources (like catalog, customer, sales) with methods that operate on those resources. ### Key Components -1. **API Entry Point**: The `api.php` file serves as the entry point for all API requests +1. **API Entry Point**: The `api.php` file serves as the entry point for all API requests, routed to by the web server using the `/api/jsonrpc` URL 2. **Server Adapter**: Handles protocol-specific details (JSON-RPC, XML-RPC, SOAP) 3. **Handler**: Processes API requests and maps them to the appropriate resource models 4. **Resource Models**: Implement the actual business logic for API operations @@ -33,7 +33,7 @@ The JSON-RPC adapter is implemented in `Mage_Api_Model_Server_Adapter_Jsonrpc` a ## Authentication -To use the OpenMage API, you must either authenticate with the login method to obtain a session ID and inlcude this session ID with all subsequent API calls (not recommended), or use the HTTP Basic Authentication method (recommended). +To use the OpenMage API, you must either authenticate with the login method to obtain a session ID and inlcude this session ID with all subsequent API calls, or use the HTTP Basic Authentication method. The HTTP Basic Authentication method allows you to skip the login step and use your API credentials directly in the request which is simpler for many use cases, but does expose your credentials in each request whereas the session ID expires and needs to be refreshed periodically. ### Login Authentication Process @@ -110,7 +110,7 @@ print_r($result['result']); ## JSON-RPC 2.0 Request/Response Format -The OpenMage API implements the JSON-RPC 2.0 specification, which defines a stateless, light-weight remote procedure call (RPC) protocol using JSON as the data format. +The OpenMage API implements the JSON-RPC 2.0 specification, which defines a stateless (aside from the session id), light-weight remote procedure call (RPC) protocol using JSON as the data format. ### Request Format From f8e698cfca1a758119e36053d98b014bf7451418 Mon Sep 17 00:00:00 2001 From: Colin Mollenhour Date: Wed, 14 May 2025 17:44:45 -0400 Subject: [PATCH 3/7] Add to menu and clean up organization and formatting errors. --- docs/content/api/jsonrpc/index.md | 81 +------------------ .../{ => resources}/catalog_category.md | 31 +++++++ .../{ => resources}/catalog_product.md | 29 +++++++ .../catalog_product_attribute.md | 72 +++++++++++++++++ .../cataloginventory_stock_item.md | 10 +++ .../api/jsonrpc/{ => resources}/customer.md | 15 ++++ .../{ => resources}/customer_address.md | 15 ++++ .../jsonrpc/{ => resources}/customer_group.md | 3 + .../jsonrpc/{ => resources}/sales_order.md | 18 +++++ .../{ => resources}/sales_order_creditmemo.md | 15 ++++ .../{ => resources}/sales_order_invoice.md | 21 +++++ .../{ => resources}/sales_order_shipment.md | 24 ++++++ mkdocs.yml | 18 +++++ 13 files changed, 273 insertions(+), 79 deletions(-) rename docs/content/api/jsonrpc/{ => resources}/catalog_category.md (99%) rename docs/content/api/jsonrpc/{ => resources}/catalog_product.md (99%) rename docs/content/api/jsonrpc/{ => resources}/catalog_product_attribute.md (99%) rename docs/content/api/jsonrpc/{ => resources}/cataloginventory_stock_item.md (99%) rename docs/content/api/jsonrpc/{ => resources}/customer.md (99%) rename docs/content/api/jsonrpc/{ => resources}/customer_address.md (99%) rename docs/content/api/jsonrpc/{ => resources}/customer_group.md (99%) rename docs/content/api/jsonrpc/{ => resources}/sales_order.md (99%) rename docs/content/api/jsonrpc/{ => resources}/sales_order_creditmemo.md (99%) rename docs/content/api/jsonrpc/{ => resources}/sales_order_invoice.md (99%) rename docs/content/api/jsonrpc/{ => resources}/sales_order_shipment.md (99%) diff --git a/docs/content/api/jsonrpc/index.md b/docs/content/api/jsonrpc/index.md index 992f36aacdc..04ec4d8f67f 100644 --- a/docs/content/api/jsonrpc/index.md +++ b/docs/content/api/jsonrpc/index.md @@ -338,78 +338,7 @@ echo "Product ID: " . $result['result']; ## Available Resources -The OpenMage API provides access to numerous resources. Here are the main resource categories: - -### Catalog Resources - -- **catalog_category**: Manage product categories - - [catalog_category.create](catalog_category.md#create) - - [catalog_category.update](catalog_category.md#update) - - [catalog_category.move](catalog_category.md#move) - - [catalog_category.delete](catalog_category.md#delete) - - [catalog_category.tree](catalog_category.md#tree) - - [catalog_category.info](catalog_category.md#info) - - [catalog_category.level](catalog_category.md#level) - -- **catalog_product**: Manage products - - [catalog_product.create](catalog_product.md#create) - - [catalog_product.update](catalog_product.md#update) - - [catalog_product.delete](catalog_product.md#delete) - - [catalog_product.info](catalog_product.md#info) - - [catalog_product.list](catalog_product.md#list) - - [catalog_product.attributes](catalog_product.md#attributes) - -### Customer Resources - -- **customer**: Manage customers - - [customer.create](customer.md#create) - - [customer.update](customer.md#update) - - [customer.delete](customer.md#delete) - - [customer.info](customer.md#info) - - [customer.list](customer.md#list) - -- **customer_address**: Manage customer addresses - - [customer_address.create](customer_address.md#create) - - [customer_address.update](customer_address.md#update) - - [customer_address.delete](customer_address.md#delete) - - [customer_address.info](customer_address.md#info) - - [customer_address.list](customer_address.md#list) - -### Sales Resources - -- **sales_order**: Manage orders - - [sales_order.info](sales_order.md#info) - - [sales_order.list](sales_order.md#list) - - [sales_order.addComment](sales_order.md#addComment) - - [sales_order.hold](sales_order.md#hold) - - [sales_order.unhold](sales_order.md#unhold) - - [sales_order.cancel](sales_order.md#cancel) - -- **sales_order_invoice**: Manage invoices - - [sales_order_invoice.create](sales_order_invoice.md#create) - - [sales_order_invoice.info](sales_order_invoice.md#info) - - [sales_order_invoice.list](sales_order_invoice.md#list) - -- **sales_order_shipment**: Manage shipments - - [sales_order_shipment.create](sales_order_shipment.md#create) - - [sales_order_shipment.info](sales_order_shipment.md#info) - - [sales_order_shipment.list](sales_order_shipment.md#list) - -### Inventory Resources - -- **cataloginventory_stock_item**: Manage inventory - - [cataloginventory_stock_item.list](cataloginventory_stock_item.md#list) - - [cataloginventory_stock_item.update](cataloginventory_stock_item.md#update) - -### Other Resources - -- **directory**: Access region and country information - - [directory.countries](directory.md#countries) - - [directory.regions](directory.md#regions) - -- **core**: Core functionality - - [core.resources](core.md#resources) - - [core.globalFaults](core.md#globalFaults) +The OpenMage API provides access to numerous resources and third-party extensions may also provide additional resources. Please refer to the individual resource documentation pages in the left sidebar for more information on available methods and parameters. ## Best Practices @@ -417,13 +346,7 @@ The OpenMage API provides access to numerous resources. Here are the main resour 2. **Implement Rate Limiting**: Avoid overwhelming the server with too many requests 3. **Cache Responses**: Cache responses when appropriate to reduce API calls 4. **Handle Errors Gracefully**: Implement proper error handling in your applications -5. **Use Batch Operations**: Use multiCall for better performance when making multiple requests +5. **Use Batch Operations**: Use `multiCall` for better performance when making multiple requests 6. **Validate Input**: Always validate input data before sending it to the API 7. **Monitor API Usage**: Keep track of API usage to identify potential issues 8. **Keep API Keys Secure**: Never expose API keys in client-side code - -## Conclusion - -The OpenMage JSON-RPC API provides a powerful and flexible way to interact with your OpenMage store programmatically. By following the guidelines and examples in this document, you can build robust integrations with your OpenMage store. - -For more detailed information about specific resources and methods, please refer to the individual resource documentation pages linked in the "Available Resources" section. \ No newline at end of file diff --git a/docs/content/api/jsonrpc/catalog_category.md b/docs/content/api/jsonrpc/resources/catalog_category.md similarity index 99% rename from docs/content/api/jsonrpc/catalog_category.md rename to docs/content/api/jsonrpc/resources/catalog_category.md index 32d4bbaf490..d4abd237913 100644 --- a/docs/content/api/jsonrpc/catalog_category.md +++ b/docs/content/api/jsonrpc/resources/catalog_category.md @@ -13,9 +13,11 @@ Sets the current store for category operations. **Method Name**: `catalog_category.currentStore` **Parameters**: + - `store` (string|int, required) - Store ID or code **Return**: + - (int) - Current store ID **Example Request**: @@ -48,10 +50,12 @@ Retrieve category tree. **Method Name**: `catalog_category.tree` **Parameters**: + - `parentId` (int, optional) - Parent category ID (default: 1 - root category) - `store` (string|int, optional) - Store ID or code **Return**: + - (array) - Category tree with the following structure: - `category_id` (int) - Category ID - `parent_id` (int) - Parent category ID @@ -109,11 +113,13 @@ Retrieve level of categories for category/store view/website. **Method Name**: `catalog_category.level` **Parameters**: + - `website` (string|int, optional) - Website ID or code - `store` (string|int, optional) - Store ID or code - `categoryId` (int, optional) - Category ID **Return**: + - (array) - Array of categories with the following structure: - `category_id` (int) - Category ID - `parent_id` (int) - Parent category ID @@ -169,11 +175,13 @@ Retrieve category data. **Method Name**: `catalog_category.info` **Parameters**: + - `categoryId` (int, required) - Category ID - `store` (string|int, optional) - Store ID or code - `attributes` (array, optional) - Array of attributes to return **Return**: + - (array) - Category data with the following structure: - `category_id` (int) - Category ID - `is_active` (boolean) - Whether the category is active @@ -225,6 +233,7 @@ Create new category. **Method Name**: `catalog_category.create` **Parameters**: + - `parentId` (int, required) - Parent category ID - `categoryData` (array, required) - Category data: - `name` (string, required) - Category name @@ -243,6 +252,7 @@ Create new category. - `store` (string|int, optional) - Store ID or code **Return**: + - (int) - ID of the created category **Example Request**: @@ -279,6 +289,7 @@ Create new category. ``` **Possible Errors**: + - `data_invalid` - Invalid data provided - `not_exists` - Parent category does not exist @@ -289,11 +300,13 @@ Update category data. **Method Name**: `catalog_category.update` **Parameters**: + - `categoryId` (int, required) - Category ID - `categoryData` (array, required) - Category data to update (same structure as in create method) - `store` (string|int, optional) - Store ID or code **Return**: + - (boolean) - True on success **Example Request**: @@ -327,6 +340,7 @@ Update category data. ``` **Possible Errors**: + - `data_invalid` - Invalid data provided - `not_exists` - Category does not exist @@ -337,11 +351,13 @@ Move category in tree. **Method Name**: `catalog_category.move` **Parameters**: + - `categoryId` (int, required) - Category ID to move - `parentId` (int, required) - New parent category ID - `afterId` (int, optional) - Category ID to place the moved category after (if null, the category will be placed at the end) **Return**: + - (boolean) - True on success **Example Request**: @@ -368,6 +384,7 @@ Move category in tree. ``` **Possible Errors**: + - `not_moved` - Category could not be moved - `not_exists` - Category does not exist @@ -378,9 +395,11 @@ Delete category. **Method Name**: `catalog_category.delete` **Parameters**: + - `categoryId` (int, required) - Category ID to delete **Return**: + - (boolean) - True on success **Example Request**: @@ -407,6 +426,7 @@ Delete category. ``` **Possible Errors**: + - `not_deleted` - Category could not be deleted - `not_exists` - Category does not exist @@ -417,10 +437,12 @@ Retrieve list of assigned products to category. **Method Name**: `catalog_category.assignedProducts` **Parameters**: + - `categoryId` (int, required) - Category ID - `store` (string|int, optional) - Store ID or code **Return**: + - (array) - Array of products with the following structure: - `product_id` (int) - Product ID - `type` (string) - Product type @@ -473,12 +495,14 @@ Assign product to category. **Method Name**: `catalog_category.assignProduct` **Parameters**: + - `categoryId` (int, required) - Category ID - `productId` (int|string, required) - Product ID or SKU - `position` (int, optional) - Position in category - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (boolean) - True on success **Example Request**: @@ -505,6 +529,7 @@ Assign product to category. ``` **Possible Errors**: + - `data_invalid` - Invalid data provided - `not_exists` - Category does not exist - `product_not_exists` - Product does not exist @@ -516,12 +541,14 @@ Update product assignment. **Method Name**: `catalog_category.updateProduct` **Parameters**: + - `categoryId` (int, required) - Category ID - `productId` (int|string, required) - Product ID or SKU - `position` (int, optional) - New position in category - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (boolean) - True on success **Example Request**: @@ -548,6 +575,7 @@ Update product assignment. ``` **Possible Errors**: + - `data_invalid` - Invalid data provided - `not_exists` - Category does not exist - `product_not_exists` - Product does not exist @@ -560,11 +588,13 @@ Remove product assignment from category. **Method Name**: `catalog_category.removeProduct` **Parameters**: + - `categoryId` (int, required) - Category ID - `productId` (int|string, required) - Product ID or SKU - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (boolean) - True on success **Example Request**: @@ -591,5 +621,6 @@ Remove product assignment from category. ``` **Possible Errors**: + - `not_exists` - Category does not exist - `product_not_exists` - Product does not exist \ No newline at end of file diff --git a/docs/content/api/jsonrpc/catalog_product.md b/docs/content/api/jsonrpc/resources/catalog_product.md similarity index 99% rename from docs/content/api/jsonrpc/catalog_product.md rename to docs/content/api/jsonrpc/resources/catalog_product.md index 0b19bb5f1e3..d601cb19a66 100644 --- a/docs/content/api/jsonrpc/catalog_product.md +++ b/docs/content/api/jsonrpc/resources/catalog_product.md @@ -13,9 +13,11 @@ Sets the current store for product operations. **Method Name**: `catalog_product.currentStore` **Parameters**: + - `store` (string|int, required) - Store ID or code **Return**: + - (int) - Current store ID **Example Request**: @@ -48,6 +50,7 @@ Retrieve list of products with basic info. **Method Name**: `catalog_product.list` **Parameters**: + - `filters` (object|array, optional) - Filters to apply to the list: - `product_id` (int|array) - Filter by product ID(s) - `set` (int|array) - Filter by attribute set ID(s) @@ -59,6 +62,7 @@ Retrieve list of products with basic info. - `store` (string|int, optional) - Store ID or code **Return**: + - (array) - Array of products with the following structure: - `product_id` (int) - Product ID - `sku` (string) - Product SKU @@ -111,6 +115,7 @@ Retrieve list of products with basic info. ``` **Possible Errors**: + - `filters_invalid` - Invalid filters provided ### info @@ -120,12 +125,14 @@ Retrieve product info. **Method Name**: `catalog_product.info` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `store` (string|int, optional) - Store ID or code - `attributes` (array, optional) - Array of attributes to return - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (array) - Product data with the following structure: - `product_id` (int) - Product ID - `sku` (string) - Product SKU @@ -169,6 +176,7 @@ Retrieve product info. ``` **Possible Errors**: + - `product_not_exists` - Product does not exist ### create @@ -178,6 +186,7 @@ Create new product. **Method Name**: `catalog_product.create` **Parameters**: + - `type` (string, required) - Product type (simple, configurable, grouped, virtual, bundle, downloadable) - `set` (int, required) - Attribute set ID - `sku` (string, required) - Product SKU @@ -205,6 +214,7 @@ Create new product. - `store` (string|int, optional) - Store ID or code **Return**: + - (int) - ID of the created product **Example Request**: @@ -252,6 +262,7 @@ Create new product. ``` **Possible Errors**: + - `data_invalid` - Invalid data provided - `product_type_not_exists` - Product type does not exist - `product_attribute_set_not_exists` - Attribute set does not exist @@ -264,12 +275,14 @@ Update product data. **Method Name**: `catalog_product.update` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `productData` (array, required) - Product data to update (same structure as in create method) - `store` (string|int, optional) - Store ID or code - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (boolean) - True on success **Example Request**: @@ -305,6 +318,7 @@ Update product data. ``` **Possible Errors**: + - `data_invalid` - Invalid data provided - `product_not_exists` - Product does not exist @@ -315,12 +329,14 @@ Update multiple products in a single call. **Method Name**: `catalog_product.multiUpdate` **Parameters**: + - `productIds` (array, required) - Array of product IDs or SKUs - `productData` (array, required) - Product data to update (same structure as in update method) - `store` (string|int, optional) - Store ID or code - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (boolean) - True on success **Example Request**: @@ -355,6 +371,7 @@ Update multiple products in a single call. ``` **Possible Errors**: + - `data_invalid` - Invalid data provided - `product_not_exists` - One or more products do not exist @@ -365,10 +382,12 @@ Delete product. **Method Name**: `catalog_product.delete` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (boolean) - True on success **Example Request**: @@ -395,6 +414,7 @@ Delete product. ``` **Possible Errors**: + - `not_deleted` - Product could not be deleted - `product_not_exists` - Product does not exist @@ -405,10 +425,12 @@ Retrieve product special price. **Method Name**: `catalog_product.getSpecialPrice` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `store` (string|int, optional) - Store ID or code **Return**: + - (array) - Special price data with the following structure: - `special_price` (float) - Special price - `special_from_date` (string) - Special price from date @@ -442,6 +464,7 @@ Retrieve product special price. ``` **Possible Errors**: + - `product_not_exists` - Product does not exist ### setSpecialPrice @@ -451,6 +474,7 @@ Update product special price. **Method Name**: `catalog_product.setSpecialPrice` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `specialPrice` (float, optional) - Special price - `fromDate` (string, optional) - Special price from date (format: YYYY-MM-DD) @@ -458,6 +482,7 @@ Update product special price. - `store` (string|int, optional) - Store ID or code **Return**: + - (boolean) - True on success **Example Request**: @@ -484,6 +509,7 @@ Update product special price. ``` **Possible Errors**: + - `data_invalid` - Invalid data provided - `product_not_exists` - Product does not exist @@ -494,10 +520,12 @@ Get list of additional attributes which are not in default create/update list. **Method Name**: `catalog_product.listOfAdditionalAttributes` **Parameters**: + - `productType` (string, required) - Product type - `attributeSetId` (int, required) - Attribute set ID **Return**: + - (array) - Array of attributes with the following structure: - `attribute_id` (int) - Attribute ID - `code` (string) - Attribute code @@ -544,5 +572,6 @@ Get list of additional attributes which are not in default create/update list. ``` **Possible Errors**: + - `product_type_not_exists` - Product type does not exist - `product_attribute_set_not_exists` - Attribute set does not exist \ No newline at end of file diff --git a/docs/content/api/jsonrpc/catalog_product_attribute.md b/docs/content/api/jsonrpc/resources/catalog_product_attribute.md similarity index 99% rename from docs/content/api/jsonrpc/catalog_product_attribute.md rename to docs/content/api/jsonrpc/resources/catalog_product_attribute.md index 63d0b2d1db9..ad133bf6ac4 100644 --- a/docs/content/api/jsonrpc/catalog_product_attribute.md +++ b/docs/content/api/jsonrpc/resources/catalog_product_attribute.md @@ -13,9 +13,11 @@ Retrieve attributes from specified attribute set. **Method Name**: `catalog_product_attribute.items` **Parameters**: + - `setId` (int, required) - Attribute set ID **Return**: + - (array) - Array of attributes with the following structure: - `attribute_id` (int) - Attribute ID - `code` (string) - Attribute code @@ -68,10 +70,12 @@ Retrieve attribute options. **Method Name**: `catalog_product_attribute.options` **Parameters**: + - `attributeId` (int, required) - Attribute ID - `store` (string|int, optional) - Store ID or code **Return**: + - (array) - Array of attribute options with the following structure: - `value` (string) - Option value - `label` (string) - Option label @@ -113,6 +117,7 @@ Retrieve attribute options. ``` **Possible Errors**: + - `not_exists` - Attribute does not exist ### types @@ -124,6 +129,7 @@ Retrieve list of possible attribute types. **Parameters**: None **Return**: + - (array) - Array of attribute types with the following structure: - `value` (string) - Type value - `label` (string) - Type label @@ -178,6 +184,8 @@ Retrieve list of possible attribute types. ], "id": 1 } +``` + ### create Create new product attribute. @@ -185,6 +193,7 @@ Create new product attribute. **Method Name**: `catalog_product_attribute.create` **Parameters**: + - `data` (array, required) - Attribute data: - `attribute_code` (string, required) - Attribute code - `frontend_input` (string, required) - Frontend input type @@ -206,6 +215,7 @@ Create new product attribute. - `additional_fields` (array, optional) - Additional fields based on frontend input type **Return**: + - (int) - ID of the created attribute **Example Request**: @@ -247,6 +257,7 @@ Create new product attribute. ``` **Possible Errors**: + - `invalid_parameters` - Invalid parameters provided - `invalid_code` - Invalid attribute code - `invalid_frontend_input` - Invalid frontend input type @@ -259,10 +270,12 @@ Update product attribute. **Method Name**: `catalog_product_attribute.update` **Parameters**: + - `attribute` (int|string, required) - Attribute ID or code - `data` (array, required) - Attribute data to update (same structure as in create method) **Return**: + - (boolean) - True on success **Example Request**: @@ -300,6 +313,7 @@ Update product attribute. ``` **Possible Errors**: + - `can_not_edit` - Attribute cannot be edited - `unable_to_save` - Unable to save attribute ### remove @@ -309,9 +323,11 @@ Remove attribute. **Method Name**: `catalog_product_attribute.remove` **Parameters**: + - `attribute` (int|string, required) - Attribute ID or code **Return**: + - (boolean) - True on success **Example Request**: @@ -338,6 +354,7 @@ Remove attribute. ``` **Possible Errors**: + - `can_not_delete` - Attribute cannot be deleted ### info @@ -347,9 +364,11 @@ Get full information about attribute with list of options. **Method Name**: `catalog_product_attribute.info` **Parameters**: + - `attribute` (int|string, required) - Attribute ID or code **Return**: + - (array) - Attribute data with the following structure: - `attribute_id` (int) - Attribute ID - `attribute_code` (string) - Attribute code @@ -442,6 +461,7 @@ Add option to select or multiselect attribute. **Method Name**: `catalog_product_attribute.addOption` **Parameters**: + - `attribute` (int|string, required) - Attribute ID or code - `data` (array, required) - Option data: - `label` (array, required) - Array of option labels with the following structure: @@ -451,6 +471,7 @@ Add option to select or multiselect attribute. - `is_default` (boolean, optional) - Whether the option is default **Return**: + - (boolean) - True on success **Example Request**: @@ -489,6 +510,7 @@ Add option to select or multiselect attribute. ``` **Possible Errors**: + - `invalid_frontend_input` - Invalid frontend input type - `unable_to_add_option` - Unable to add option @@ -499,10 +521,12 @@ Remove option from select or multiselect attribute. **Method Name**: `catalog_product_attribute.removeOption` **Parameters**: + - `attribute` (int|string, required) - Attribute ID or code - `optionId` (int, required) - Option ID to remove **Return**: + - (boolean) - True on success **Example Request**: @@ -529,6 +553,7 @@ Remove option from select or multiselect attribute. ``` **Possible Errors**: + - `invalid_frontend_input` - Invalid frontend input type - `unable_to_remove_option` - Unable to remove option @@ -543,6 +568,7 @@ Retrieve attribute set list. **Parameters**: None **Return**: + - (array) - Array of attribute sets with the following structure: - `set_id` (int) - Attribute set ID - `name` (string) - Attribute set name @@ -578,6 +604,7 @@ Retrieve attribute set list. "id": 1 } ``` + ### create Create new attribute set based on another set. @@ -585,10 +612,12 @@ Create new attribute set based on another set. **Method Name**: `catalog_product_attribute_set.create` **Parameters**: + - `attributeSetName` (string, required) - Attribute set name - `skeletonSetId` (int, required) - Skeleton attribute set ID **Return**: + - (int) - ID of the created attribute set **Example Request**: @@ -615,6 +644,7 @@ Create new attribute set based on another set. ``` **Possible Errors**: + - `invalid_skeleton_set_id` - Invalid skeleton attribute set ID - `invalid_data` - Invalid data provided - `create_attribute_set_error` - Error creating attribute set @@ -626,10 +656,12 @@ Remove attribute set. **Method Name**: `catalog_product_attribute_set.remove` **Parameters**: + - `attributeSetId` (int, required) - Attribute set ID - `forceProductsRemove` (boolean, optional) - Force removal of products with this attribute set **Return**: + - (boolean) - True on success **Example Request**: @@ -656,6 +688,7 @@ Remove attribute set. ``` **Possible Errors**: + - `invalid_attribute_set_id` - Invalid attribute set ID - `attribute_set_has_related_products` - Attribute set has related products - `remove_attribute_set_error` - Error removing attribute set @@ -667,12 +700,14 @@ Add attribute to attribute set. **Method Name**: `catalog_product_attribute_set.attributeAdd` **Parameters**: + - `attributeId` (int, required) - Attribute ID - `attributeSetId` (int, required) - Attribute set ID - `attributeGroupId` (int, optional) - Attribute group ID - `sortOrder` (int, optional) - Sort order **Return**: + - (boolean) - True on success **Example Request**: @@ -699,6 +734,7 @@ Add attribute to attribute set. ``` **Possible Errors**: + - `invalid_attribute_id` - Invalid attribute ID - `invalid_attribute_set_id` - Invalid attribute set ID - `invalid_attribute_group_id` - Invalid attribute group ID @@ -712,10 +748,12 @@ Remove attribute from attribute set. **Method Name**: `catalog_product_attribute_set.attributeRemove` **Parameters**: + - `attributeId` (int, required) - Attribute ID - `attributeSetId` (int, required) - Attribute set ID **Return**: + - (boolean) - True on success **Example Request**: @@ -742,6 +780,7 @@ Remove attribute from attribute set. ``` **Possible Errors**: + - `invalid_attribute_id` - Invalid attribute ID - `invalid_attribute_set_id` - Invalid attribute set ID - `attribute_is_not_in_set` - Attribute is not in set @@ -754,10 +793,12 @@ Create group within existing attribute set. **Method Name**: `catalog_product_attribute_set.groupAdd` **Parameters**: + - `attributeSetId` (int, required) - Attribute set ID - `groupName` (string, required) - Group name **Return**: + - (int) - ID of the created group **Example Request**: @@ -784,6 +825,7 @@ Create group within existing attribute set. ``` **Possible Errors**: + - `group_already_exists` - Group already exists - `group_add_error` - Error adding group @@ -794,10 +836,12 @@ Rename existing group. **Method Name**: `catalog_product_attribute_set.groupRename` **Parameters**: + - `groupId` (int, required) - Group ID - `groupName` (string, required) - New group name **Return**: + - (boolean) - True on success **Example Request**: @@ -824,6 +868,7 @@ Rename existing group. ``` **Possible Errors**: + - `invalid_attribute_group_id` - Invalid attribute group ID - `group_rename_error` - Error renaming group @@ -834,9 +879,11 @@ Remove group from existing attribute set. **Method Name**: `catalog_product_attribute_set.groupRemove` **Parameters**: + - `attributeGroupId` (int, required) - Attribute group ID **Return**: + - (boolean) - True on success **Example Request**: @@ -863,6 +910,7 @@ Remove group from existing attribute set. ``` **Possible Errors**: + - `invalid_attribute_group_id` - Invalid attribute group ID - `group_has_configurable_attributes` - Group has configurable attributes - `group_has_system_attributes` - Group has system attributes @@ -879,6 +927,7 @@ Retrieve product type list. **Parameters**: None **Return**: + - (array) - Array of product types with the following structure: - `type` (string) - Product type code - `label` (string) - Product type label @@ -940,11 +989,13 @@ Retrieve images for product. **Method Name**: `catalog_product_attribute_media.items` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `store` (string|int, optional) - Store ID or code - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (array) - Array of product images with the following structure: - `file` (string) - Image file path - `label` (string) - Image label @@ -994,6 +1045,7 @@ Retrieve images for product. ``` **Possible Errors**: + - `product_not_exists` - Product does not exist ### info @@ -1003,12 +1055,14 @@ Retrieve image data. **Method Name**: `catalog_product_attribute_media.info` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `file` (string, required) - Image file path - `store` (string|int, optional) - Store ID or code - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (array) - Image data with the same structure as in items method **Example Request**: @@ -1042,6 +1096,7 @@ Retrieve image data. ``` **Possible Errors**: + - `product_not_exists` - Product does not exist - `not_exists` - Image does not exist @@ -1052,6 +1107,7 @@ Create new image for product and return image filename. **Method Name**: `catalog_product_attribute_media.create` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `data` (array, required) - Image data: - `file` (array, required) - Image file data: @@ -1066,6 +1122,7 @@ Create new image for product and return image filename. - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (string) - Image file path **Example Request**: @@ -1106,6 +1163,7 @@ Create new image for product and return image filename. ``` **Possible Errors**: + - `product_not_exists` - Product does not exist - `data_invalid` - Invalid data provided - `not_created` - Image could not be created @@ -1117,6 +1175,7 @@ Update image data. **Method Name**: `catalog_product_attribute_media.update` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `file` (string, required) - Image file path - `data` (array, required) - Image data to update (same structure as in create method) @@ -1124,6 +1183,7 @@ Update image data. - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (boolean) - True on success **Example Request**: @@ -1160,6 +1220,7 @@ Update image data. ``` **Possible Errors**: + - `product_not_exists` - Product does not exist - `not_exists` - Image does not exist - `data_invalid` - Invalid data provided @@ -1172,11 +1233,13 @@ Remove image from product. **Method Name**: `catalog_product_attribute_media.remove` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `file` (string, required) - Image file path - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (boolean) - True on success **Example Request**: @@ -1203,6 +1266,7 @@ Remove image from product. ``` **Possible Errors**: + - `product_not_exists` - Product does not exist - `not_exists` - Image does not exist - `not_removed` - Image could not be removed @@ -1214,9 +1278,11 @@ Retrieve image types (image, small_image, thumbnail, etc...). **Method Name**: `catalog_product_attribute_media.types` **Parameters**: + - `setId` (int, required) - Attribute set ID **Return**: + - (array) - Array of image types with the following structure: - `code` (string) - Image type code - `scope` (string) - Image type scope (global, website, store) @@ -1266,10 +1332,12 @@ Retrieve tier prices for a product. **Method Name**: `catalog_product_attribute_tier_price.info` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (array) - Array of tier prices with the following structure: - `customer_group_id` (string) - Customer group ID or 'all' for all groups - `website` (string) - Website code or 'all' for all websites @@ -1313,6 +1381,7 @@ Retrieve tier prices for a product. ``` **Possible Errors**: + - `product_not_exists` - Product does not exist ### update @@ -1322,6 +1391,7 @@ Update tier prices of product. **Method Name**: `catalog_product_attribute_tier_price.update` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `tierPrices` (array, required) - Array of tier prices with the following structure: - `customer_group_id` (string, optional) - Customer group ID or 'all' for all groups (default: 'all') @@ -1331,6 +1401,7 @@ Update tier prices of product. - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (boolean) - True on success **Example Request**: @@ -1374,6 +1445,7 @@ Update tier prices of product. ``` **Possible Errors**: + - `product_not_exists` - Product does not exist - `data_invalid` - Invalid data provided - `not_updated` - Tier prices could not be updated \ No newline at end of file diff --git a/docs/content/api/jsonrpc/cataloginventory_stock_item.md b/docs/content/api/jsonrpc/resources/cataloginventory_stock_item.md similarity index 99% rename from docs/content/api/jsonrpc/cataloginventory_stock_item.md rename to docs/content/api/jsonrpc/resources/cataloginventory_stock_item.md index 55e7179cda9..8043e9c7a87 100644 --- a/docs/content/api/jsonrpc/cataloginventory_stock_item.md +++ b/docs/content/api/jsonrpc/resources/cataloginventory_stock_item.md @@ -13,10 +13,12 @@ Retrieve stock information for products. **Method Name**: `cataloginventory_stock_item.list` **Parameters**: + - `productIds` (array, required) - Array of product IDs or SKUs - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (array) - Array of stock items with the following structure: - `product_id` (int) - Product ID - `sku` (string) - Product SKU @@ -99,6 +101,7 @@ Retrieve stock information for products. ``` **Possible Errors**: + - `product_not_exists` - One or more products do not exist ### update @@ -108,6 +111,7 @@ Update stock information for a product. **Method Name**: `cataloginventory_stock_item.update` **Parameters**: + - `productId` (int|string, required) - Product ID or SKU - `stockData` (array, required) - Stock data: - `qty` (float, optional) - Quantity @@ -128,6 +132,7 @@ Update stock information for a product. - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (boolean) - True on success **Example Request**: @@ -162,6 +167,7 @@ Update stock information for a product. ``` **Possible Errors**: + - `product_not_exists` - Product does not exist - `data_invalid` - Invalid data provided @@ -172,11 +178,13 @@ Update stock information for multiple products in a single call. **Method Name**: `cataloginventory_stock_item.multiUpdate` **Parameters**: + - `productIds` (array, required) - Array of product IDs or SKUs - `stockData` (array, required) - Stock data (same structure as in update method) - `identifierType` (string, optional) - Type of product identifier ('sku' or null for ID) **Return**: + - (boolean) - True on success **Example Request**: @@ -210,10 +218,12 @@ Update stock information for multiple products in a single call. ``` **Possible Errors**: + - `product_not_exists` - One or more products do not exist - `data_invalid` - Invalid data provided **Notes**: + - When updating stock information, you only need to include the fields you want to change. Other fields will retain their current values. - The `use_config_*` fields determine whether to use the system configuration value for the corresponding setting. When set to 1, the system configuration value is used regardless of the value specified for the setting. - When managing inventory for configurable, grouped, or bundle products, you should update the stock for the associated simple products, as the parent product's stock is calculated based on its child products. \ No newline at end of file diff --git a/docs/content/api/jsonrpc/customer.md b/docs/content/api/jsonrpc/resources/customer.md similarity index 99% rename from docs/content/api/jsonrpc/customer.md rename to docs/content/api/jsonrpc/resources/customer.md index 5287e8913f1..b00d371b714 100644 --- a/docs/content/api/jsonrpc/customer.md +++ b/docs/content/api/jsonrpc/resources/customer.md @@ -13,6 +13,7 @@ Retrieve list of customers with basic info. **Method Name**: `customer.list` **Parameters**: + - `filters` (object|array, optional) - Filters to apply to the list: - `customer_id` (int|array) - Filter by customer ID(s) - `email` (string|array) - Filter by email(s) @@ -26,6 +27,7 @@ Retrieve list of customers with basic info. - `store` (string|int, optional) - Store ID or code **Return**: + - (array) - Array of customers with the following structure: - `customer_id` (int) - Customer ID - `email` (string) - Customer email @@ -81,6 +83,7 @@ Retrieve list of customers with basic info. ``` **Possible Errors**: + - `filters_invalid` - Invalid filters provided - `store_not_exists` - Requested store does not exist @@ -91,10 +94,12 @@ Retrieve detailed customer information. **Method Name**: `customer.info` **Parameters**: + - `customerId` (int, required) - Customer ID - `store` (string|int, optional) - Store ID or code **Return**: + - (object) - Customer information with the following structure: - `customer_id` (int) - Customer ID - `email` (string) - Customer email @@ -158,6 +163,7 @@ Retrieve detailed customer information. ``` **Possible Errors**: + - `customer_not_exists` - Customer does not exist - `store_not_exists` - Requested store does not exist @@ -168,6 +174,7 @@ Create new customer. **Method Name**: `customer.create` **Parameters**: + - `customerData` (array, required) - Customer data: - `email` (string, required) - Customer email - `firstname` (string, required) - Customer first name @@ -185,6 +192,7 @@ Create new customer. - `store` (string|int, optional) - Store ID or code **Return**: + - (int) - ID of the created customer **Example Request**: @@ -224,6 +232,7 @@ Create new customer. ``` **Possible Errors**: + - `data_invalid` - Invalid data provided - `customer_data_invalid` - Invalid customer data - `customer_exists` - Customer with the same email already exists @@ -237,11 +246,13 @@ Update customer data. **Method Name**: `customer.update` **Parameters**: + - `customerId` (int, required) - Customer ID - `customerData` (array, required) - Customer data to update (same structure as in create method, except password is optional) - `store` (string|int, optional) - Store ID or code **Return**: + - (boolean) - True on success **Example Request**: @@ -276,6 +287,7 @@ Update customer data. ``` **Possible Errors**: + - `data_invalid` - Invalid data provided - `customer_not_exists` - Customer does not exist - `customer_data_invalid` - Invalid customer data @@ -290,9 +302,11 @@ Delete customer. **Method Name**: `customer.delete` **Parameters**: + - `customerId` (int, required) - Customer ID **Return**: + - (boolean) - True on success **Example Request**: @@ -319,5 +333,6 @@ Delete customer. ``` **Possible Errors**: + - `customer_not_exists` - Customer does not exist - `not_deleted` - Customer could not be deleted \ No newline at end of file diff --git a/docs/content/api/jsonrpc/customer_address.md b/docs/content/api/jsonrpc/resources/customer_address.md similarity index 99% rename from docs/content/api/jsonrpc/customer_address.md rename to docs/content/api/jsonrpc/resources/customer_address.md index fc3be88378c..70ba2e967e4 100644 --- a/docs/content/api/jsonrpc/customer_address.md +++ b/docs/content/api/jsonrpc/resources/customer_address.md @@ -13,9 +13,11 @@ Retrieve list of addresses for a customer. **Method Name**: `customer_address.list` **Parameters**: + - `customerId` (int, required) - Customer ID **Return**: + - (array) - Array of addresses with the following structure: - `customer_address_id` (int) - Customer address ID - `created_at` (string) - Creation date @@ -62,6 +64,7 @@ Retrieve list of addresses for a customer. ``` **Possible Errors**: + - `customer_not_exists` - Customer does not exist ### info @@ -71,9 +74,11 @@ Retrieve detailed address information. **Method Name**: `customer_address.info` **Parameters**: + - `addressId` (int, required) - Customer address ID **Return**: + - (object) - Address information with the following structure: - `customer_address_id` (int) - Customer address ID - `customer_id` (int) - Customer ID @@ -137,6 +142,7 @@ Retrieve detailed address information. ``` **Possible Errors**: + - `address_not_exists` - Address does not exist ### create @@ -146,6 +152,7 @@ Create new address for a customer. **Method Name**: `customer_address.create` **Parameters**: + - `customerId` (int, required) - Customer ID - `addressData` (array, required) - Address data: - `firstname` (string, required) - First name @@ -166,6 +173,7 @@ Create new address for a customer. - `is_default_shipping` (boolean, optional) - Whether this is the default shipping address **Return**: + - (int) - ID of the created address **Example Request**: @@ -207,6 +215,7 @@ Create new address for a customer. ``` **Possible Errors**: + - `customer_not_exists` - Customer does not exist - `data_invalid` - Invalid data provided @@ -217,10 +226,12 @@ Update customer address data. **Method Name**: `customer_address.update` **Parameters**: + - `addressId` (int, required) - Customer address ID - `addressData` (array, required) - Address data to update (same structure as in create method) **Return**: + - (boolean) - True on success **Example Request**: @@ -254,6 +265,7 @@ Update customer address data. ``` **Possible Errors**: + - `address_not_exists` - Address does not exist - `data_invalid` - Invalid data provided @@ -264,9 +276,11 @@ Delete customer address. **Method Name**: `customer_address.delete` **Parameters**: + - `addressId` (int, required) - Customer address ID **Return**: + - (boolean) - True on success **Example Request**: @@ -293,5 +307,6 @@ Delete customer address. ``` **Possible Errors**: + - `address_not_exists` - Address does not exist - `not_deleted` - Address could not be deleted \ No newline at end of file diff --git a/docs/content/api/jsonrpc/customer_group.md b/docs/content/api/jsonrpc/resources/customer_group.md similarity index 99% rename from docs/content/api/jsonrpc/customer_group.md rename to docs/content/api/jsonrpc/resources/customer_group.md index d1780b7f61e..f183f26688c 100644 --- a/docs/content/api/jsonrpc/customer_group.md +++ b/docs/content/api/jsonrpc/resources/customer_group.md @@ -13,9 +13,11 @@ Retrieve list of customer groups. **Method Name**: `customer_group.list` **Parameters**: + - None **Return**: + - (array) - Array of customer groups with the following structure: - `customer_group_id` (int) - Customer group ID - `customer_group_code` (string) - Customer group name/code @@ -65,4 +67,5 @@ Retrieve list of customer groups. ``` **Possible Errors**: + - None specific to this method \ No newline at end of file diff --git a/docs/content/api/jsonrpc/sales_order.md b/docs/content/api/jsonrpc/resources/sales_order.md similarity index 99% rename from docs/content/api/jsonrpc/sales_order.md rename to docs/content/api/jsonrpc/resources/sales_order.md index 97d02ac9f3d..d138075e30d 100644 --- a/docs/content/api/jsonrpc/sales_order.md +++ b/docs/content/api/jsonrpc/resources/sales_order.md @@ -13,6 +13,7 @@ Retrieve list of orders with basic info. **Method Name**: `sales_order.list` **Parameters**: + - `filters` (object|array, optional) - Filters to apply to the list: - `order_id` (int|array) - Filter by order ID(s) - `status` (string|array) - Filter by order status(es) @@ -24,6 +25,7 @@ Retrieve list of orders with basic info. - `store` (string|int, optional) - Store ID or code **Return**: + - (array) - Array of orders with the following structure: - `increment_id` (string) - Order increment ID - `order_id` (int) - Order ID @@ -85,6 +87,7 @@ Retrieve list of orders with basic info. ``` **Possible Errors**: + - `filters_invalid` - Invalid filters provided - `store_not_exists` - Requested store does not exist @@ -95,9 +98,11 @@ Retrieve detailed order information. **Method Name**: `sales_order.info` **Parameters**: + - `orderIncrementId` (string, required) - Order increment ID **Return**: + - (object) - Order information with the following structure: - `increment_id` (string) - Order increment ID - `order_id` (int) - Order ID @@ -213,6 +218,7 @@ Retrieve detailed order information. ``` **Possible Errors**: + - `order_not_exists` - Order does not exist ### addComment @@ -222,12 +228,14 @@ Add a comment to an order. **Method Name**: `sales_order.addComment` **Parameters**: + - `orderIncrementId` (string, required) - Order increment ID - `status` (string, required) - Order status - `comment` (string, optional) - Comment text - `notify` (boolean, optional) - Whether to notify customer (default: false) **Return**: + - (boolean) - True on success **Example Request**: @@ -254,6 +262,7 @@ Add a comment to an order. ``` **Possible Errors**: + - `order_not_exists` - Order does not exist - `status_not_exists` - Status does not exist @@ -264,9 +273,11 @@ Place an order on hold. **Method Name**: `sales_order.hold` **Parameters**: + - `orderIncrementId` (string, required) - Order increment ID **Return**: + - (boolean) - True on success **Example Request**: @@ -293,6 +304,7 @@ Place an order on hold. ``` **Possible Errors**: + - `order_not_exists` - Order does not exist - `order_not_holdable` - Order cannot be put on hold @@ -303,9 +315,11 @@ Release an order from hold. **Method Name**: `sales_order.unhold` **Parameters**: + - `orderIncrementId` (string, required) - Order increment ID **Return**: + - (boolean) - True on success **Example Request**: @@ -332,6 +346,7 @@ Release an order from hold. ``` **Possible Errors**: + - `order_not_exists` - Order does not exist - `order_not_unholdable` - Order is not on hold @@ -342,9 +357,11 @@ Cancel an order. **Method Name**: `sales_order.cancel` **Parameters**: + - `orderIncrementId` (string, required) - Order increment ID **Return**: + - (boolean) - True on success **Example Request**: @@ -371,5 +388,6 @@ Cancel an order. ``` **Possible Errors**: + - `order_not_exists` - Order does not exist - `order_not_cancelable` - Order cannot be canceled \ No newline at end of file diff --git a/docs/content/api/jsonrpc/sales_order_creditmemo.md b/docs/content/api/jsonrpc/resources/sales_order_creditmemo.md similarity index 99% rename from docs/content/api/jsonrpc/sales_order_creditmemo.md rename to docs/content/api/jsonrpc/resources/sales_order_creditmemo.md index 06377e91cf5..e557655d37a 100644 --- a/docs/content/api/jsonrpc/sales_order_creditmemo.md +++ b/docs/content/api/jsonrpc/resources/sales_order_creditmemo.md @@ -13,6 +13,7 @@ Retrieve list of credit memos with basic info. **Method Name**: `sales_order_creditmemo.list` **Parameters**: + - `filters` (object|array, optional) - Filters to apply to the list: - `creditmemo_id` (int|array) - Filter by credit memo ID(s) - `order_id` (int|array) - Filter by order ID(s) @@ -22,6 +23,7 @@ Retrieve list of credit memos with basic info. - Other attributes can also be used as filters **Return**: + - (array) - Array of credit memos with the following structure: - `increment_id` (string) - Credit memo increment ID - `creditmemo_id` (int) - Credit memo ID @@ -67,6 +69,7 @@ Retrieve list of credit memos with basic info. ``` **Possible Errors**: + - `filters_invalid` - Invalid filters provided ### info @@ -76,9 +79,11 @@ Retrieve detailed credit memo information. **Method Name**: `sales_order_creditmemo.info` **Parameters**: + - `creditmemoIncrementId` (string, required) - Credit memo increment ID **Return**: + - (object) - Credit memo information with the following structure: - `increment_id` (string) - Credit memo increment ID - `creditmemo_id` (int) - Credit memo ID @@ -177,6 +182,7 @@ Retrieve detailed credit memo information. ``` **Possible Errors**: + - `creditmemo_not_exists` - Credit memo does not exist ### create @@ -186,6 +192,7 @@ Create a new credit memo for an order. **Method Name**: `sales_order_creditmemo.create` **Parameters**: + - `orderIncrementId` (string, required) - Order increment ID - `creditmemoData` (object, optional) - Credit memo data: - `items` (array, optional) - Array of items to refund: @@ -201,6 +208,7 @@ Create a new credit memo for an order. - `includeComment` (boolean, optional) - Whether to include comment in email (default: false) **Return**: + - (string) - Credit memo increment ID **Example Request**: @@ -238,6 +246,7 @@ Create a new credit memo for an order. ``` **Possible Errors**: + - `order_not_exists` - Order does not exist - `order_not_refundable` - Order cannot be refunded - `data_invalid` - Invalid data provided @@ -249,12 +258,14 @@ Add a comment to a credit memo. **Method Name**: `sales_order_creditmemo.addComment` **Parameters**: + - `creditmemoIncrementId` (string, required) - Credit memo increment ID - `comment` (string, required) - Comment text - `email` (boolean, optional) - Whether to send email notification (default: false) - `includeInEmail` (boolean, optional) - Whether to include comment in email (default: false) **Return**: + - (boolean) - True on success **Example Request**: @@ -281,6 +292,7 @@ Add a comment to a credit memo. ``` **Possible Errors**: + - `creditmemo_not_exists` - Credit memo does not exist ### cancel @@ -290,9 +302,11 @@ Cancel a credit memo. **Method Name**: `sales_order_creditmemo.cancel` **Parameters**: + - `creditmemoIncrementId` (string, required) - Credit memo increment ID **Return**: + - (boolean) - True on success **Example Request**: @@ -319,5 +333,6 @@ Cancel a credit memo. ``` **Possible Errors**: + - `creditmemo_not_exists` - Credit memo does not exist - `creditmemo_not_cancelable` - Credit memo cannot be canceled \ No newline at end of file diff --git a/docs/content/api/jsonrpc/sales_order_invoice.md b/docs/content/api/jsonrpc/resources/sales_order_invoice.md similarity index 99% rename from docs/content/api/jsonrpc/sales_order_invoice.md rename to docs/content/api/jsonrpc/resources/sales_order_invoice.md index c22a1412a92..6b0688157d2 100644 --- a/docs/content/api/jsonrpc/sales_order_invoice.md +++ b/docs/content/api/jsonrpc/resources/sales_order_invoice.md @@ -13,6 +13,7 @@ Retrieve list of invoices with basic info. **Method Name**: `sales_order_invoice.list` **Parameters**: + - `filters` (object|array, optional) - Filters to apply to the list: - `invoice_id` (int|array) - Filter by invoice ID(s) - `order_id` (int|array) - Filter by order ID(s) @@ -23,6 +24,7 @@ Retrieve list of invoices with basic info. - Other attributes can also be used as filters **Return**: + - (array) - Array of invoices with the following structure: - `increment_id` (string) - Invoice increment ID - `invoice_id` (int) - Invoice ID @@ -68,6 +70,7 @@ Retrieve list of invoices with basic info. ``` **Possible Errors**: + - `filters_invalid` - Invalid filters provided ### info @@ -77,9 +80,11 @@ Retrieve detailed invoice information. **Method Name**: `sales_order_invoice.info` **Parameters**: + - `invoiceIncrementId` (string, required) - Invoice increment ID **Return**: + - (object) - Invoice information with the following structure: - `increment_id` (string) - Invoice increment ID - `invoice_id` (int) - Invoice ID @@ -176,6 +181,7 @@ Retrieve detailed invoice information. ``` **Possible Errors**: + - `invoice_not_exists` - Invoice does not exist ### create @@ -185,6 +191,7 @@ Create a new invoice for an order. **Method Name**: `sales_order_invoice.create` **Parameters**: + - `orderIncrementId` (string, required) - Order increment ID - `itemsQty` (array, optional) - Array of items to invoice with quantities: - `order_item_id` (int) - Order item ID @@ -194,6 +201,7 @@ Create a new invoice for an order. - `includeComment` (boolean, optional) - Whether to include comment in email (default: false) **Return**: + - (string) - Invoice increment ID **Example Request**: @@ -226,6 +234,7 @@ Create a new invoice for an order. ``` **Possible Errors**: + - `order_not_exists` - Order does not exist - `order_not_invoiceable` - Order cannot be invoiced - `data_invalid` - Invalid data provided @@ -237,12 +246,14 @@ Add a comment to an invoice. **Method Name**: `sales_order_invoice.addComment` **Parameters**: + - `invoiceIncrementId` (string, required) - Invoice increment ID - `comment` (string, required) - Comment text - `email` (boolean, optional) - Whether to send email notification (default: false) - `includeInEmail` (boolean, optional) - Whether to include comment in email (default: false) **Return**: + - (boolean) - True on success **Example Request**: @@ -269,6 +280,7 @@ Add a comment to an invoice. ``` **Possible Errors**: + - `invoice_not_exists` - Invoice does not exist ### capture @@ -278,9 +290,11 @@ Capture an invoice. **Method Name**: `sales_order_invoice.capture` **Parameters**: + - `invoiceIncrementId` (string, required) - Invoice increment ID **Return**: + - (boolean) - True on success **Example Request**: @@ -307,6 +321,7 @@ Capture an invoice. ``` **Possible Errors**: + - `invoice_not_exists` - Invoice does not exist - `invoice_not_capturable` - Invoice cannot be captured @@ -317,9 +332,11 @@ Void an invoice. **Method Name**: `sales_order_invoice.void` **Parameters**: + - `invoiceIncrementId` (string, required) - Invoice increment ID **Return**: + - (boolean) - True on success **Example Request**: @@ -346,6 +363,7 @@ Void an invoice. ``` **Possible Errors**: + - `invoice_not_exists` - Invoice does not exist - `invoice_not_voidable` - Invoice cannot be voided @@ -356,9 +374,11 @@ Cancel an invoice. **Method Name**: `sales_order_invoice.cancel` **Parameters**: + - `invoiceIncrementId` (string, required) - Invoice increment ID **Return**: + - (boolean) - True on success **Example Request**: @@ -385,5 +405,6 @@ Cancel an invoice. ``` **Possible Errors**: + - `invoice_not_exists` - Invoice does not exist - `invoice_not_cancelable` - Invoice cannot be canceled \ No newline at end of file diff --git a/docs/content/api/jsonrpc/sales_order_shipment.md b/docs/content/api/jsonrpc/resources/sales_order_shipment.md similarity index 99% rename from docs/content/api/jsonrpc/sales_order_shipment.md rename to docs/content/api/jsonrpc/resources/sales_order_shipment.md index 5f37d109978..c2a18ba11b7 100644 --- a/docs/content/api/jsonrpc/sales_order_shipment.md +++ b/docs/content/api/jsonrpc/resources/sales_order_shipment.md @@ -13,6 +13,7 @@ Retrieve list of shipments with basic info. **Method Name**: `sales_order_shipment.list` **Parameters**: + - `filters` (object|array, optional) - Filters to apply to the list: - `shipment_id` (int|array) - Filter by shipment ID(s) - `order_id` (int|array) - Filter by order ID(s) @@ -22,6 +23,7 @@ Retrieve list of shipments with basic info. - Other attributes can also be used as filters **Return**: + - (array) - Array of shipments with the following structure: - `increment_id` (string) - Shipment increment ID - `shipment_id` (int) - Shipment ID @@ -65,6 +67,7 @@ Retrieve list of shipments with basic info. ``` **Possible Errors**: + - `filters_invalid` - Invalid filters provided ### info @@ -74,9 +77,11 @@ Retrieve detailed shipment information. **Method Name**: `sales_order_shipment.info` **Parameters**: + - `shipmentIncrementId` (string, required) - Shipment increment ID **Return**: + - (object) - Shipment information with the following structure: - `increment_id` (string) - Shipment increment ID - `shipment_id` (int) - Shipment ID @@ -173,6 +178,7 @@ Retrieve detailed shipment information. ``` **Possible Errors**: + - `shipment_not_exists` - Shipment does not exist ### create @@ -182,6 +188,7 @@ Create a new shipment for an order. **Method Name**: `sales_order_shipment.create` **Parameters**: + - `orderIncrementId` (string, required) - Order increment ID - `itemsQty` (array, optional) - Array of items to ship with quantities: - `order_item_id` (int) - Order item ID @@ -191,6 +198,7 @@ Create a new shipment for an order. - `includeComment` (boolean, optional) - Whether to include comment in email (default: false) **Return**: + - (string) - Shipment increment ID **Example Request**: @@ -223,6 +231,7 @@ Create a new shipment for an order. ``` **Possible Errors**: + - `order_not_exists` - Order does not exist - `order_not_shippable` - Order cannot be shipped - `data_invalid` - Invalid data provided @@ -234,12 +243,14 @@ Add a comment to a shipment. **Method Name**: `sales_order_shipment.addComment` **Parameters**: + - `shipmentIncrementId` (string, required) - Shipment increment ID - `comment` (string, required) - Comment text - `email` (boolean, optional) - Whether to send email notification (default: false) - `includeInEmail` (boolean, optional) - Whether to include comment in email (default: false) **Return**: + - (boolean) - True on success **Example Request**: @@ -266,6 +277,7 @@ Add a comment to a shipment. ``` **Possible Errors**: + - `shipment_not_exists` - Shipment does not exist ### addTrack @@ -275,12 +287,14 @@ Add tracking information to a shipment. **Method Name**: `sales_order_shipment.addTrack` **Parameters**: + - `shipmentIncrementId` (string, required) - Shipment increment ID - `carrier` (string, required) - Carrier code - `title` (string, required) - Carrier title - `trackNumber` (string, required) - Tracking number **Return**: + - (int) - Tracking ID **Example Request**: @@ -307,6 +321,7 @@ Add tracking information to a shipment. ``` **Possible Errors**: + - `shipment_not_exists` - Shipment does not exist - `data_invalid` - Invalid data provided @@ -317,10 +332,12 @@ Remove tracking information from a shipment. **Method Name**: `sales_order_shipment.removeTrack` **Parameters**: + - `shipmentIncrementId` (string, required) - Shipment increment ID - `trackId` (int, required) - Tracking ID **Return**: + - (boolean) - True on success **Example Request**: @@ -347,6 +364,7 @@ Remove tracking information from a shipment. ``` **Possible Errors**: + - `shipment_not_exists` - Shipment does not exist - `track_not_exists` - Tracking information does not exist @@ -357,10 +375,12 @@ Send shipment information to the customer. **Method Name**: `sales_order_shipment.sendInfo` **Parameters**: + - `shipmentIncrementId` (string, required) - Shipment increment ID - `comment` (string, optional) - Comment to include in the email **Return**: + - (boolean) - True on success **Example Request**: @@ -387,6 +407,7 @@ Send shipment information to the customer. ``` **Possible Errors**: + - `shipment_not_exists` - Shipment does not exist ### getCarriers @@ -396,9 +417,11 @@ Get list of available shipping carriers. **Method Name**: `sales_order_shipment.getCarriers` **Parameters**: + - `orderIncrementId` (string, required) - Order increment ID **Return**: + - (object) - Object with carrier codes as keys and carrier titles as values **Example Request**: @@ -430,4 +453,5 @@ Get list of available shipping carriers. ``` **Possible Errors**: + - `order_not_exists` - Order does not exist \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 5a96bf0af81..91ce8c67e7d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -184,6 +184,24 @@ nav: - api/rest/resources/customers.md - api/rest/response_formats.md - api/rest/testing_rest_resources.md + - 'JSON-RPC': + - api/jsonrpc/index.md + - 'Resources': + - 'Products': + - api/jsonrpc/resources/catalog_category.md + - api/jsonrpc/resources/catalog_product.md + - api/jsonrpc/resources/catalog_product_attribute.md + - 'Inventory': + - api/jsonrpc/resources/cataloginventory_stock_item.md + - 'Customers': + - api/jsonrpc/resources/customer.md + - api/jsonrpc/resources/customer_group.md + - api/jsonrpc/resources/customer_address.md + - 'Sales': + - api/jsonrpc/resources/sales_order.md + - api/jsonrpc/resources/sales_order_shipment.md + - api/jsonrpc/resources/sales_order_creditmemo.md + - api/jsonrpc/resources/sales_order_invoice.md - 'Development': - 'Installation': - developers/tools/ddev.md From 6466088651ccbdf62b65e33df7a87d7aa2d88cfc Mon Sep 17 00:00:00 2001 From: Sven Reichel Date: Thu, 15 May 2025 02:17:57 +0200 Subject: [PATCH 4/7] fixed some links --- docs/content/api/jsonrpc/index.md | 2 +- docs/content/blog/posts/guides/2024-02-17-ddev-windows-10.md | 2 +- docs/content/developers/tools/ddev.md | 2 +- docs/content/developers/tools/oneline.md | 2 +- docs/content/users/install/use-git.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/content/api/jsonrpc/index.md b/docs/content/api/jsonrpc/index.md index 04ec4d8f67f..e401b567679 100644 --- a/docs/content/api/jsonrpc/index.md +++ b/docs/content/api/jsonrpc/index.md @@ -19,7 +19,7 @@ The OpenMage API is built on a modular architecture that supports multiple proto - **JSON-RPC**: A lightweight protocol that uses JSON for data encoding - **XML-RPC**: Similar to JSON-RPC but uses XML for data encoding - **SOAP**: A comprehensive web service protocol with formal WSDL definitions -- **REST**: See [OpenMage REST API](../rest/common_http_status_codes/) for more information +- **REST**: See [OpenMage REST API](../rest/common_http_status_codes.md) for more information The JSON-RPC adapter is implemented in `Mage_Api_Model_Server_Adapter_Jsonrpc` and uses the `Zend_Json_Server` component to handle requests and responses. The API follows a resource-based architecture where functionality is organized into logical resources (like catalog, customer, sales) with methods that operate on those resources. diff --git a/docs/content/blog/posts/guides/2024-02-17-ddev-windows-10.md b/docs/content/blog/posts/guides/2024-02-17-ddev-windows-10.md index 39b535f28c0..860745d98d2 100644 --- a/docs/content/blog/posts/guides/2024-02-17-ddev-windows-10.md +++ b/docs/content/blog/posts/guides/2024-02-17-ddev-windows-10.md @@ -162,7 +162,7 @@ ddev start ddev launch ``` -For more information about using DDEV please visit [help](/developers/tools/ddev) page. It is a fantastic tool! +For more information about using DDEV please visit [help](../../../developers/tools/ddev.md) page. It is a fantastic tool! ### CONCLUSION As you can see, the more complicated part is the initial configuration of WSL, Docker, DDEV. Once done, it doesn't take more than 3-5 minutes to get an instance of OpenMage ready for testing. Forget about XAMPP, WAMP in Windows. diff --git a/docs/content/developers/tools/ddev.md b/docs/content/developers/tools/ddev.md index d751c1b808b..f3970989600 100644 --- a/docs/content/developers/tools/ddev.md +++ b/docs/content/developers/tools/ddev.md @@ -12,7 +12,7 @@ To install OpenMage in seconds, follow the DDEV [installation guide](https://dde !!! info "Docker only" For development environment without dependencies aside from Docker, see the - [Docker Compose](/developers/tools/oneline) guide. + [Docker Compose](oneline.md) guide. !!! info "Test Environment for OpenMage in Windows 10 Based on DDEV" For development environment with Windows 10, see this [guide](/blog/2024/08/17/test-environment-for-openmage-in-windows-10-based-on-ddev/). diff --git a/docs/content/developers/tools/oneline.md b/docs/content/developers/tools/oneline.md index dc97aab7d5f..3e7937170df 100644 --- a/docs/content/developers/tools/oneline.md +++ b/docs/content/developers/tools/oneline.md @@ -10,7 +10,7 @@ For a quick and easy way to get started developing on OpenMage, you can use the command to install OpenMage with Docker Compose. !!! info - If you prefer a more robust development environment, consider using [DDEV](/developers/tools/ddev). + If you prefer a more robust development environment, consider using [DDEV](ddev.md). ```bash git clone https://github.com/OpenMage/magento-lts.git && cd magento-lts && dev/openmage/install.sh diff --git a/docs/content/users/install/use-git.md b/docs/content/users/install/use-git.md index 7584cad09ad..8ee83f91e5e 100644 --- a/docs/content/users/install/use-git.md +++ b/docs/content/users/install/use-git.md @@ -10,6 +10,6 @@ If you want to hack at the core and contribute to the project with a Pull Reques 1. [Fork](https://github.com/OpenMage/magento-lts/fork) the project so you can push your commits later. 2. Clone your fork to your development host with `git clone https://github.com//magento-lts` -3. Use either the [DDEV](/developers/tools/ddev/) or the [Docker Compose](/developers/tools/oneline/) development environment to hack away. +3. Use either the [DDEV](../../developers/tools/ddev.md) or the [Docker Compose](../../developers/tools/oneline.md) development environment to hack away. 4. Commit and push your code up to your own fork from step 1. 5. Create a [Pull Request](https://github.com/OpenMage/magento-lts/compare)! From a3f3d444aa8d46dac1970cbbbd0938329024e3f1 Mon Sep 17 00:00:00 2001 From: Sven Reichel Date: Thu, 15 May 2025 02:30:23 +0200 Subject: [PATCH 5/7] some formatting --- .github/spellcheck-wordlist.txt | 3 ++ docs/content/api/jsonrpc/index.md | 34 +++++++++---------- .../api/jsonrpc/resources/sales_order.md | 2 +- 3 files changed, 21 insertions(+), 18 deletions(-) diff --git a/.github/spellcheck-wordlist.txt b/.github/spellcheck-wordlist.txt index 61162ba1126..f2b7d541044 100644 --- a/.github/spellcheck-wordlist.txt +++ b/.github/spellcheck-wordlist.txt @@ -22,6 +22,8 @@ Gitpod HiPay Homebrew HMAC +HTTP +HTTPS ImageMagick IntelliSense jQuery @@ -58,6 +60,7 @@ RSS RWD SCSS SHA +SKU SMTP SSL TinyMCE diff --git a/docs/content/api/jsonrpc/index.md b/docs/content/api/jsonrpc/index.md index e401b567679..215d3038dca 100644 --- a/docs/content/api/jsonrpc/index.md +++ b/docs/content/api/jsonrpc/index.md @@ -65,18 +65,18 @@ To use the OpenMage API, you must either authenticate with the login method to o As an alternative to session-based authentication, OpenMage also supports HTTP Basic Authentication for API requests. This method simplifies the authentication process by eliminating the need for a separate login step. -#### How HTTP Basic Auth Works +#### How HTTP Basic Authorization Works -1. **Use API Credentials**: The API username and API key (created in admin panel) are used as the username and password for HTTP Basic Auth -2. **Skip Login Call**: When using HTTP Basic Auth, the "login" call is not required +1. **Use API Credentials**: The API username and API key (created in admin panel) are used as the username and password for HTTP Basic Authorization +2. **Skip Login Call**: When using HTTP Basic Authorization, the "login" call is not required 3. **Null Session ID**: The session ID parameter in the "call" method can be set to "null" -4. **Include Auth Header**: Include the Authorization header with each request +4. **Include Authorization Header**: Include the Authorization header with each request -#### HTTP Basic Auth Example +#### HTTP Basic Authorization Example ```php '2.0', 'method' => 'call', 'params' => [ - null, // Null session ID when using HTTP Basic Auth + null, // Null session ID when using HTTP Basic Authorization 'catalog_product.info', 'product_sku_123' ], @@ -96,7 +96,7 @@ $requestData = array( $ch = curl_init($jsonRpcUrl); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json')); -curl_setopt($ch, CURLOPT_USERPWD, "$apiUser:$apiKey"); // HTTP Basic Auth +curl_setopt($ch, CURLOPT_USERPWD, "$apiUser:$apiKey"); // HTTP Basic Authorization curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestData)); @@ -127,13 +127,13 @@ The OpenMage API implements the JSON-RPC 2.0 specification, which defines a stat } ``` -- **jsonrpc**: Must be exactly "2.0" -- **method**: For most API calls, this will be "call" -- **params**: An array containing: - 1. The session ID obtained from login or `null` for HTTP Basic Auth +- `jsonrpc`: Must be exactly "2.0" +- `method`: For most API calls, this will be "call" +- `params`: An array containing: + 1. The session ID obtained from login or `null` for HTTP Basic Authorization 2. The resource and method name in the format "resource.method" 3. An array of parameters for the method -- **id**: A unique identifier for the request (can be a string or number) +- `id`: A unique identifier for the request (can be a string or number) ### Response Format @@ -145,9 +145,9 @@ The OpenMage API implements the JSON-RPC 2.0 specification, which defines a stat } ``` -- **jsonrpc**: Always "2.0" -- **result**: The data returned by the method call -- **id**: The same ID that was sent in the request +- `jsonrpc`: Always "2.0" +- `result`: The data returned by the method call +- `id`: The same ID that was sent in the request ### Error Response Format @@ -197,7 +197,7 @@ The API also uses HTTP status codes to indicate the status of requests: 2. **API Calls**: Make one or more API calls using the session ID 3. **End Session**: Optionally end the session when finished -### Batch Operations with multiCall +### Batch Operations with `multiCall` For improved performance when making multiple API calls, use the `multiCall` method to batch requests: diff --git a/docs/content/api/jsonrpc/resources/sales_order.md b/docs/content/api/jsonrpc/resources/sales_order.md index d138075e30d..e27a591396e 100644 --- a/docs/content/api/jsonrpc/resources/sales_order.md +++ b/docs/content/api/jsonrpc/resources/sales_order.md @@ -2,7 +2,7 @@ ## Introduction -The Sales Order API allows you to manage orders in your OpenMage store. You can retrieve order information, add comments to orders, and perform various order operations such as holding, unholding, and canceling orders. +The Sales Order API allows you to manage orders in your OpenMage store. You can retrieve order information, add comments to orders, and perform various order operations such as holding, un-holding, and canceling orders. ## Available Methods From 8e6573f80d9f46f07d7456727cc91584d57a0860 Mon Sep 17 00:00:00 2001 From: Sven Reichel Date: Thu, 15 May 2025 02:41:58 +0200 Subject: [PATCH 6/7] some formatting --- .../api/jsonrpc/resources/catalog_product.md | 20 +++++++++---------- .../api/jsonrpc/resources/sales_order.md | 6 +++--- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/content/api/jsonrpc/resources/catalog_product.md b/docs/content/api/jsonrpc/resources/catalog_product.md index d601cb19a66..ba40b76cf28 100644 --- a/docs/content/api/jsonrpc/resources/catalog_product.md +++ b/docs/content/api/jsonrpc/resources/catalog_product.md @@ -6,7 +6,7 @@ The Catalog Product API allows you to manage products in your OpenMage store. Yo ## Available Methods -### currentStore +### `currentStore` Sets the current store for product operations. @@ -43,7 +43,7 @@ Sets the current store for product operations. } ``` -### list +### `list` Retrieve list of products with basic info. @@ -118,7 +118,7 @@ Retrieve list of products with basic info. - `filters_invalid` - Invalid filters provided -### info +### `info` Retrieve product info. @@ -179,7 +179,7 @@ Retrieve product info. - `product_not_exists` - Product does not exist -### create +### `create` Create new product. @@ -268,7 +268,7 @@ Create new product. - `product_attribute_set_not_exists` - Attribute set does not exist - `product_attribute_set_not_valid` - Attribute set is not valid for the product -### update +### `update` Update product data. @@ -322,7 +322,7 @@ Update product data. - `data_invalid` - Invalid data provided - `product_not_exists` - Product does not exist -### multiUpdate +### `multiUpdate` Update multiple products in a single call. @@ -375,7 +375,7 @@ Update multiple products in a single call. - `data_invalid` - Invalid data provided - `product_not_exists` - One or more products do not exist -### delete +### `delete` Delete product. @@ -418,7 +418,7 @@ Delete product. - `not_deleted` - Product could not be deleted - `product_not_exists` - Product does not exist -### getSpecialPrice +### `getSpecialPrice` Retrieve product special price. @@ -467,7 +467,7 @@ Retrieve product special price. - `product_not_exists` - Product does not exist -### setSpecialPrice +### `setSpecialPrice` Update product special price. @@ -513,7 +513,7 @@ Update product special price. - `data_invalid` - Invalid data provided - `product_not_exists` - Product does not exist -### listOfAdditionalAttributes +### `listOfAdditionalAttributes` Get list of additional attributes which are not in default create/update list. diff --git a/docs/content/api/jsonrpc/resources/sales_order.md b/docs/content/api/jsonrpc/resources/sales_order.md index e27a591396e..6aa63af892b 100644 --- a/docs/content/api/jsonrpc/resources/sales_order.md +++ b/docs/content/api/jsonrpc/resources/sales_order.md @@ -221,7 +221,7 @@ Retrieve detailed order information. - `order_not_exists` - Order does not exist -### addComment +### `addComment` Add a comment to an order. @@ -308,7 +308,7 @@ Place an order on hold. - `order_not_exists` - Order does not exist - `order_not_holdable` - Order cannot be put on hold -### unhold +### `unhold` Release an order from hold. @@ -350,7 +350,7 @@ Release an order from hold. - `order_not_exists` - Order does not exist - `order_not_unholdable` - Order is not on hold -### cancel +### `cancel` Cancel an order. From cde305d4aa1a449f8d5d73986b5a9aa2d4eba2b1 Mon Sep 17 00:00:00 2001 From: Colin Mollenhour Date: Fri, 16 May 2025 10:21:04 -0400 Subject: [PATCH 7/7] Fix spelling errors --- .github/spellcheck-wordlist.txt | 10 ++++++++++ docs/content/api/jsonrpc/index.md | 2 +- .../api/jsonrpc/resources/catalog_category.md | 10 +++++----- .../api/jsonrpc/resources/catalog_product.md | 4 ++-- .../resources/catalog_product_attribute.md | 18 +++++++++--------- .../resources/cataloginventory_stock_item.md | 2 +- docs/content/api/jsonrpc/resources/customer.md | 2 +- .../resources/sales_order_creditmemo.md | 2 +- .../jsonrpc/resources/sales_order_invoice.md | 2 +- .../jsonrpc/resources/sales_order_shipment.md | 10 +++++----- 10 files changed, 36 insertions(+), 26 deletions(-) diff --git a/.github/spellcheck-wordlist.txt b/.github/spellcheck-wordlist.txt index f2b7d541044..2b6c1b9fd65 100644 --- a/.github/spellcheck-wordlist.txt +++ b/.github/spellcheck-wordlist.txt @@ -1,6 +1,9 @@ ACL ActionScript +analytics bool +boolean +backorders Braintree Browsersync Captcha @@ -10,6 +13,7 @@ CMS Cron CVE CodeQL +config DevOps DDEV DNS @@ -18,6 +22,7 @@ EAV Emmet FireGento FPC +frontend Gitpod HiPay Homebrew @@ -52,20 +57,25 @@ PHPStan PhpStorm PHPUnit PLAINTEXT +programmatically RCE reCaptcha Redis RPC RSS RWD +runtime SCSS SHA +sku SKU +SKUs SMTP SSL TinyMCE toc URI +un Varien VMware WAMP diff --git a/docs/content/api/jsonrpc/index.md b/docs/content/api/jsonrpc/index.md index 215d3038dca..37c31bbd81d 100644 --- a/docs/content/api/jsonrpc/index.md +++ b/docs/content/api/jsonrpc/index.md @@ -33,7 +33,7 @@ The JSON-RPC adapter is implemented in `Mage_Api_Model_Server_Adapter_Jsonrpc` a ## Authentication -To use the OpenMage API, you must either authenticate with the login method to obtain a session ID and inlcude this session ID with all subsequent API calls, or use the HTTP Basic Authentication method. The HTTP Basic Authentication method allows you to skip the login step and use your API credentials directly in the request which is simpler for many use cases, but does expose your credentials in each request whereas the session ID expires and needs to be refreshed periodically. +To use the OpenMage API, you must either authenticate with the login method to obtain a session ID and include this session ID with all subsequent API calls, or use the HTTP Basic Authentication method. The HTTP Basic Authentication method allows you to skip the login step and use your API credentials directly in the request which is simpler for many use cases, but does expose your credentials in each request whereas the session ID expires and needs to be refreshed periodically. ### Login Authentication Process diff --git a/docs/content/api/jsonrpc/resources/catalog_category.md b/docs/content/api/jsonrpc/resources/catalog_category.md index d4abd237913..fb05cb6b78e 100644 --- a/docs/content/api/jsonrpc/resources/catalog_category.md +++ b/docs/content/api/jsonrpc/resources/catalog_category.md @@ -6,7 +6,7 @@ The Catalog Category API allows you to manage product categories in your OpenMag ## Available Methods -### currentStore +### `currentStore` Sets the current store for category operations. @@ -430,7 +430,7 @@ Delete category. - `not_deleted` - Category could not be deleted - `not_exists` - Category does not exist -### assignedProducts +### `assignedProducts` Retrieve list of assigned products to category. @@ -488,7 +488,7 @@ Retrieve list of assigned products to category. } ``` -### assignProduct +### `assignProduct` Assign product to category. @@ -534,7 +534,7 @@ Assign product to category. - `not_exists` - Category does not exist - `product_not_exists` - Product does not exist -### updateProduct +### `updateProduct` Update product assignment. @@ -581,7 +581,7 @@ Update product assignment. - `product_not_exists` - Product does not exist - `product_not_assigned` - Product is not assigned to the category -### removeProduct +### `removeProduct` Remove product assignment from category. diff --git a/docs/content/api/jsonrpc/resources/catalog_product.md b/docs/content/api/jsonrpc/resources/catalog_product.md index ba40b76cf28..57f8d6de4e7 100644 --- a/docs/content/api/jsonrpc/resources/catalog_product.md +++ b/docs/content/api/jsonrpc/resources/catalog_product.md @@ -477,8 +477,8 @@ Update product special price. - `productId` (int|string, required) - Product ID or SKU - `specialPrice` (float, optional) - Special price -- `fromDate` (string, optional) - Special price from date (format: YYYY-MM-DD) -- `toDate` (string, optional) - Special price to date (format: YYYY-MM-DD) +- `fromDate` (string, optional) - Special price from date (format: `YYYY-MM-DD`) +- `toDate` (string, optional) - Special price to date (format: `YYYY-MM-DD`) - `store` (string|int, optional) - Store ID or code **Return**: diff --git a/docs/content/api/jsonrpc/resources/catalog_product_attribute.md b/docs/content/api/jsonrpc/resources/catalog_product_attribute.md index ad133bf6ac4..ca9fe2be684 100644 --- a/docs/content/api/jsonrpc/resources/catalog_product_attribute.md +++ b/docs/content/api/jsonrpc/resources/catalog_product_attribute.md @@ -454,9 +454,9 @@ Get full information about attribute with list of options. } ``` -### addOption +### `addOption` -Add option to select or multiselect attribute. +Add option to select or multi-select attribute. **Method Name**: `catalog_product_attribute.addOption` @@ -514,9 +514,9 @@ Add option to select or multiselect attribute. - `invalid_frontend_input` - Invalid frontend input type - `unable_to_add_option` - Unable to add option -### removeOption +### `removeOption` -Remove option from select or multiselect attribute. +Remove option from select or multi-select attribute. **Method Name**: `catalog_product_attribute.removeOption` @@ -693,7 +693,7 @@ Remove attribute set. - `attribute_set_has_related_products` - Attribute set has related products - `remove_attribute_set_error` - Error removing attribute set -### attributeAdd +### `attributeAdd` Add attribute to attribute set. @@ -741,7 +741,7 @@ Add attribute to attribute set. - `attribute_is_already_in_set` - Attribute is already in set - `add_attribute_error` - Error adding attribute -### attributeRemove +### `attributeRemove` Remove attribute from attribute set. @@ -786,7 +786,7 @@ Remove attribute from attribute set. - `attribute_is_not_in_set` - Attribute is not in set - `remove_attribute_error` - Error removing attribute -### groupAdd +### `groupAdd` Create group within existing attribute set. @@ -829,7 +829,7 @@ Create group within existing attribute set. - `group_already_exists` - Group already exists - `group_add_error` - Error adding group -### groupRename +### `groupRename` Rename existing group. @@ -872,7 +872,7 @@ Rename existing group. - `invalid_attribute_group_id` - Invalid attribute group ID - `group_rename_error` - Error renaming group -### groupRemove +### `groupRemove` Remove group from existing attribute set. diff --git a/docs/content/api/jsonrpc/resources/cataloginventory_stock_item.md b/docs/content/api/jsonrpc/resources/cataloginventory_stock_item.md index 8043e9c7a87..b37c57924dd 100644 --- a/docs/content/api/jsonrpc/resources/cataloginventory_stock_item.md +++ b/docs/content/api/jsonrpc/resources/cataloginventory_stock_item.md @@ -171,7 +171,7 @@ Update stock information for a product. - `product_not_exists` - Product does not exist - `data_invalid` - Invalid data provided -### multiUpdate +### `multiUpdate` Update stock information for multiple products in a single call. diff --git a/docs/content/api/jsonrpc/resources/customer.md b/docs/content/api/jsonrpc/resources/customer.md index b00d371b714..5d4c7a4eb60 100644 --- a/docs/content/api/jsonrpc/resources/customer.md +++ b/docs/content/api/jsonrpc/resources/customer.md @@ -185,7 +185,7 @@ Create new customer. - `middlename` (string, optional) - Customer middle name - `prefix` (string, optional) - Name prefix - `suffix` (string, optional) - Name suffix - - `dob` (string, optional) - Date of birth (format: YYYY-MM-DD) + - `dob` (string, optional) - Date of birth (format: `YYYY-MM-DD`) - `taxvat` (string, optional) - Tax/VAT number - `is_subscribed` (boolean, optional) - Whether customer is subscribed to newsletter - `store_id` (int, optional) - Store ID diff --git a/docs/content/api/jsonrpc/resources/sales_order_creditmemo.md b/docs/content/api/jsonrpc/resources/sales_order_creditmemo.md index e557655d37a..2d88037ff35 100644 --- a/docs/content/api/jsonrpc/resources/sales_order_creditmemo.md +++ b/docs/content/api/jsonrpc/resources/sales_order_creditmemo.md @@ -251,7 +251,7 @@ Create a new credit memo for an order. - `order_not_refundable` - Order cannot be refunded - `data_invalid` - Invalid data provided -### addComment +### `addComment` Add a comment to a credit memo. diff --git a/docs/content/api/jsonrpc/resources/sales_order_invoice.md b/docs/content/api/jsonrpc/resources/sales_order_invoice.md index 6b0688157d2..36952fd32c8 100644 --- a/docs/content/api/jsonrpc/resources/sales_order_invoice.md +++ b/docs/content/api/jsonrpc/resources/sales_order_invoice.md @@ -239,7 +239,7 @@ Create a new invoice for an order. - `order_not_invoiceable` - Order cannot be invoiced - `data_invalid` - Invalid data provided -### addComment +### `addComment` Add a comment to an invoice. diff --git a/docs/content/api/jsonrpc/resources/sales_order_shipment.md b/docs/content/api/jsonrpc/resources/sales_order_shipment.md index c2a18ba11b7..5ad17c365e5 100644 --- a/docs/content/api/jsonrpc/resources/sales_order_shipment.md +++ b/docs/content/api/jsonrpc/resources/sales_order_shipment.md @@ -236,7 +236,7 @@ Create a new shipment for an order. - `order_not_shippable` - Order cannot be shipped - `data_invalid` - Invalid data provided -### addComment +### `addComment` Add a comment to a shipment. @@ -280,7 +280,7 @@ Add a comment to a shipment. - `shipment_not_exists` - Shipment does not exist -### addTrack +### `addTrack` Add tracking information to a shipment. @@ -325,7 +325,7 @@ Add tracking information to a shipment. - `shipment_not_exists` - Shipment does not exist - `data_invalid` - Invalid data provided -### removeTrack +### `removeTrack` Remove tracking information from a shipment. @@ -368,7 +368,7 @@ Remove tracking information from a shipment. - `shipment_not_exists` - Shipment does not exist - `track_not_exists` - Tracking information does not exist -### sendInfo +### `sendInfo` Send shipment information to the customer. @@ -410,7 +410,7 @@ Send shipment information to the customer. - `shipment_not_exists` - Shipment does not exist -### getCarriers +### `getCarriers` Get list of available shipping carriers.