> For the complete documentation index, see [llms.txt](https://docs.archisketch.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.archisketch.com/guide/dev-en/api-sdk/api-integration/3d-product-integration/product.md). # Register Product This guide explains how to create and manage products (Sales) based on components. A product is a commercial unit configured using components. Use the component ID created in the previous step to generate a selling product. You must include the `X-API-KEY` in the header of all API requests. Refer to the ["How to Use the API"](/guide/dev-en/api-sdk/how-to-use.md) guide for instructions on how to issue it. ```http X-API-KEY: {x-api-key} ``` ## Create Product **POST** `/api/v1/sales` {% stepper %} {% step %} ### Prepare Required Information To create a product, you need the basic product details and the component ID generated in the previous step. **Main Request Fields**: | Field | Type | Required | Description | | ------------ | ------- | -------- | ------------------------------------------------------- | | info | object | ✅ | Basic product details ([see table below](#undefined-8)) | | isPersonal | boolean | ✅ | Personal library flag | | images | array | ✅ | List of image IDs (can be an empty array `[]`) | | previewImage | string | | Representative/Thumbnail image ID | | category | object | | Category information | | components | object | | Constituent components (including component ID) | **Product Basic Info** (`info`): | Field | Type | Required | Description | | --------------- | ------ | -------- | -------------------- | | name | string | ✅ | Product name | | translatedNames | array | ✅ | Multilingual names | | description | array | ✅ | Product descriptions | | tags | array | ✅ | Tag keywords | | brandCode | string | | Brand code | | code | string | | Product code | | website | string | | Website URL | | {% endstep %} | | | | {% step %} ### Send Request ```json POST /api/v1/sales X-API-KEY: {x-api-key} { "info": { "name": "Sofa", "translatedNames": [ { "code": "en", "value": "Sofa" }, { "code": "ko", "value": "소파" } ], "description": [ { "code": "en", "value": "A comfortable 3-seater sofa." }, { "code": "ko", "value": "편안한 3인용 소파입니다." } ], "tags": ["sofa", "livingroom"], "brandCode": "BRAND_001" }, "images": ["img_001"], "isPersonal": false, "components": { "options": [ { "componentId": "cmp_def456", "optionValue1": "Default", "price": { "value": 350000, "unit": "KRW" } } ] } } ``` {% endstep %} {% step %} ### Check Response ```json { "result": "SUCCESS", "data": { "id": "sale_ghi789", "enterpriseId": "ENT_ABC123", "userId": "usr_xyz", "name": "Sofa", "translatedNames": [ { "code": "en", "value": "Sofa" }, { "code": "ko", "value": "소파" } ], "description": [ { "code": "ko", "value": "편안한 3인용 소파입니다." } ], "tags": ["sofa", "livingroom"], "brandCode": null, "code": null, "website": null, "minPrice": { "value": 0, "unit": "KRW" }, "categories": [], "previewImage": { "id": "img_001", "name": "sofa_preview", "url": "https://..." }, "images": [], "components": { "optionKeys": ["Option"], "records": [ { "id": "rec_001", "order": 0, "price": { "value": 0, "unit": "KRW" }, "options": [{ "key": "Option", "value": "Default" }], "previewImage": null } ] }, "createdAt": "2026-04-04T10:02:00Z", "updatedAt": "2026-04-04T10:02:00Z" } } ``` {% endstep %} {% endstepper %} ## Get Product List **GET** `/api/v1/sales` | Parameter | Type | Required | Description | | ----------- | ------- | -------- | --------------------------- | | offset | integer | ✅ | Page number (starts from 0) | | limit | integer | ✅ | Page size (1–100) | | userId | string | | User ID filter | | name | string | | Name search keyword | | code | string | | Product code | | sku | string | | SKU | | brandCode | string | | Brand code | | categoryIds | array | | List of category IDs | | sortType | string | | Sorting criteria | ```http GET /api/v1/sales?offset=0&limit=20&name=소파 X-API-KEY: {x-api-key} ``` ## Get Single Product **GET** `/api/v1/sales/{id}` ```http GET /api/v1/sales/sale_ghi789 X-API-KEY: {x-api-key} ``` ## Update Product ### Full Update **PUT** `/api/v1/sales/{id}` The Request Body structure is identical to that of the product creation endpoint. #### Update Basic Info Only **PATCH** `/api/v1/sales/{id}/info` ```json PATCH /api/v1/sales/sale_ghi789/info X-API-KEY: {x-api-key} { "name": "Sofa (Updated)", "translatedNames": [{ "code": "en", "value": "Sofa (Updated)" }], "description": [{ "code": "en", "value": "This is an updated description." }], "tags": ["sofa", "livingroom", "3-seater"] } ``` ## Manage Product Options You can configure multiple components into a single product by adding options such as colors and sizes. #### Add Options **POST** `/api/v1/sales/{id}/options` ```json { "optionKey1": "Color", "options": [ { "componentId": "cmp_def456", "optionValue1": "Beige" }, { "componentId": "cmp_def789", "optionValue1": "Gray" } ] } ``` ### Update Options **PATCH** `/api/v1/sales/{id}/options` The Request Body structure is identical to that of the Add Options endpoint. #### Update Option Price **PATCH** `/api/v1/sales/{id}/options/{componentId}/price` ```json { "price": { "value": 350000, "unit": "KRW" } } ``` ### Delete Option **DELETE** `/api/v1/sales/{id}/options` ```json { "ids": ["rec_001"], "deleteSaleIfEmpty": false } ``` Setting `deleteSaleIfEmpty` to `true` will completely delete the product (Sale) once all of its options are deleted. ## Decompose / Merge Products ### Decompose Product **POST** `/api/v1/sales/decompose` Separates a single combined product into its individual component units. ```json { "saleIds": ["sale_ghi789"] } ``` ### Merge Products **POST** `/api/v1/sales/merge` Combines multiple individual products into a single consolidated product. ```json { "name": "Unified Sofa Product", "optionKey": "Color", "salesToMerge": [ { "saleId": "sale_ghi789" }, { "saleId": "sale_jkl012" } ] } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.archisketch.com/guide/dev-en/api-sdk/api-integration/3d-product-integration/product.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.