{"files":{"SKILL.md":"---\nname: suggestions\ndescription: \"Suggestions API skill. Use when working with Suggestions for suggestions. Covers 17 endpoints.\"\nversion: 1.0.0\ngenerator: lapsh\n---\n\n# Suggestions\nAPI version: 1.0\n\n## Auth\nApiKey X-VTEX-API-AppKey in header | ApiKey X-VTEX-API-AppToken in header | ApiKey VtexIdclientAutCookie in header\n\n## Base URL\nhttps://api.vtex.com/apiexamples\n\n## Setup\n1. Set your API key in the appropriate header\n2. GET /suggestions/configuration/autoapproval/toggle -- verify access\n\n## Endpoints\n\n17 endpoints across 1 groups. See references/api-spec.lap for full details.\n\n### suggestions\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /suggestions/configuration/autoapproval/toggle | Get autoApprove status in account settings |\n| PUT | /suggestions/configuration/autoapproval/toggle | Activate autoApprove in marketplace's account |\n| GET | /suggestions/configuration | Get account's approval settings |\n| PUT | /suggestions/configuration | Save account's approval settings |\n| GET | /suggestions/configuration/account/config | Get account's matcher settings |\n| GET | /suggestions/configuration/seller/{sellerId} | Get seller's approval settings |\n| PUT | /suggestions/configuration/seller/{sellerId} | Save seller's approval settings |\n| PUT | /suggestions/configuration/autoapproval/toggle/seller/{sellerId} | Activate autoApprove setting for a seller |\n| GET | /suggestions | Get all SKU suggestions |\n| PUT | /suggestions/{sellerId}/{sellerSkuId} | Send SKU suggestion |\n| GET | /suggestions/{sellerId}/{sellerSkuId} | Get SKU suggestion by ID |\n| DELETE | /suggestions/{sellerId}/{sellerSkuId} | Delete SKU suggestion |\n| GET | /suggestions/{sellerId}/{sellerskuid}/versions | Get all versions |\n| GET | /suggestions/{sellerId}/{sellerskuid}/versions/{version} | Get version by ID |\n| PUT | /suggestions/{sellerId}/{sellerskuid}/versions/{version}/matches/{matchid} | Match received SKUs individually |\n| PUT | /suggestions/matches/action/{actionName} | Match multiple received SKUs |\n| PUT | /suggestions/configuration/{sellerID}/specifications | Map seller specifications to marketplace catalog |\n\n## Common Questions\n\nMatch user requests to endpoints in references/api-spec.lap. Key patterns:\n- \"List all toggle?\" -> GET /suggestions/configuration/autoapproval/toggle\n- \"List all configuration?\" -> GET /suggestions/configuration\n- \"List all config?\" -> GET /suggestions/configuration/account/config\n- \"Get seller details?\" -> GET /suggestions/configuration/seller/{sellerId}\n- \"Update a seller?\" -> PUT /suggestions/configuration/seller/{sellerId}\n- \"Update a seller?\" -> PUT /suggestions/configuration/autoapproval/toggle/seller/{sellerId}\n- \"Search suggestions?\" -> GET /suggestions\n- \"Update a suggestion?\" -> PUT /suggestions/{sellerId}/{sellerSkuId}\n- \"Get suggestion details?\" -> GET /suggestions/{sellerId}/{sellerSkuId}\n- \"Delete a suggestion?\" -> DELETE /suggestions/{sellerId}/{sellerSkuId}\n- \"List all versions?\" -> GET /suggestions/{sellerId}/{sellerskuid}/versions\n- \"Get version details?\" -> GET /suggestions/{sellerId}/{sellerskuid}/versions/{version}\n- \"Update a matche?\" -> PUT /suggestions/{sellerId}/{sellerskuid}/versions/{version}/matches/{matchid}\n- \"Update a action?\" -> PUT /suggestions/matches/action/{actionName}\n- \"How to authenticate?\" -> See Auth section\n\n## Response Tips\n- Check response schemas in references/api-spec.lap for field details\n- Create/update endpoints typically return the created/updated object\n\n## CLI\n\n```bash\n# Update this spec to the latest version\nnpx @lap-platform/lapsh get suggestions -o references/api-spec.lap\n\n# Search for related APIs\nnpx @lap-platform/lapsh search suggestions\n```\n\n## References\n- Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas\n\n> Generated from the official API spec by [LAP](https://lap.sh)\n","references/api-spec.lap":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Suggestions\n@base https://api.vtex.com/apiexamples\n@version 1.0\n@auth ApiKey X-VTEX-API-AppKey in header | ApiKey X-VTEX-API-AppToken in header | ApiKey VtexIdclientAutCookie in header\n@common_fields {accountName: str # Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account., Content-Type: str=application/json # Describes the type of the content being sent., Accept: str=application/json # HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand}\n@endpoints 17\n@toc suggestions(17)\n\n@endpoint GET /suggestions/configuration/autoapproval/toggle\n@desc Get autoApprove status in account settings\n@required {sellerId: str # A string that identifies the seller in the marketplace. This ID must be created by the marketplace.}\n@returns(200) {Enabled: bool} # OK\n\n@endpoint PUT /suggestions/configuration/autoapproval/toggle\n@desc Activate autoApprove in marketplace's account\n@required {Enabled: bool # Insert `true` if you wish to activate the autoapprove rule for an entire marketplace account. Insert `false` if you wish to deactivate it. Be aware that once enabling the setting through this request, all received SKUs will be automatically approved on your store, regardless of the seller, or the Matcher Score.}\n@returns(200) {Enabled: bool} # OK\n@example_request {\"Enabled\":true}\n\n@endpoint GET /suggestions/configuration\n@desc Get account's approval settings\n@returns(200) {Score: map, Matchers: [map], Rules: map, SpecificationsMapping: [map], MatchFlux: str} # OK\n\n@endpoint PUT /suggestions/configuration\n@desc Save account's approval settings\n@required {Score: map{Approve!: int(int32), Reject!: int(int32)} # Matcher rates received SKUs by comparing the data sent by sellers to existing fields in the marketplace. The calculation of these scores determines whether the product has been: `Approved` or `Denied`., Matchers: [map{MatcherId!: str, hook-base-address!: str, IsActive!: bool, UpdatesNotificationEndpoint!: str, Description: str}] # Matchers for approving and rejecting SKUs received from sellers., SpecificationsMapping: [str] # This attribute maps product and SKU specifications., MatchFlux: str=autoApprove # This field determines the type of approval configuration applied to SKUs received  from a seller. The possible values include:   - `default` where the Matcher reviews the SKU, and approves it based on its score   - `manual` for manual approvals through the Received SKU UI or Match API   - `autoApprove` for every SKU received from a given seller to be approved automatically, regardless of the Matcher Score.}\n@returns(200) {Score: map{Approve: int, Reject: int}, Matchers: [map], Rules: map{Item: [int], Product: [str]}, SpecificationsMapping: [map], MatchFlux: str} # OK\n@example_request {\"Score\":{\"Approve\":80,\"Reject\":30},\"Matchers\":[{\"MatcherId\":\"vtex-matcher\",\"hook-base-address\":\"http://simple-suggestion-matcher.vtex.com.br\",\"IsActive\":true,\"UpdatesNotificationEndpoint\":null,\"Description\":null}],\"SpecificationsMapping\":[\"color=red\",\"size=L\"],\"MatchFlux\":\"autoApprove\"}\n\n@endpoint GET /suggestions/configuration/account/config\n@desc Get account's matcher settings\n@returns(200) {score: map{approve: int, pending: int, reject: int}, matchers: [map], rules: map{item: [map], product: [map]}, SpecificationsMapping: [map], matchFlux: str} # OK\n\n@endpoint GET /suggestions/configuration/seller/{sellerId}\n@desc Get seller's approval settings\n@required {sellerId: str # A string that identifies the seller in the marketplace. This ID must be created by the marketplace.}\n@returns(200) {sellerId: str, accountId: str, accountName: str, mapping: map{defaultColor: str, searchColor: str, color1: str, color2: str, color: str, size: str}, matchFlux: str} # OK\n\n@endpoint PUT /suggestions/configuration/seller/{sellerId}\n@desc Save seller's approval settings\n@required {sellerId: str # A string that identifies the seller in the marketplace. This ID must be created by the marketplace., sellerId: str # A string that identifies the seller in the marketplace. This ID must be created by the marketplace., mapping: map # Mapping of SKU and product Specifications. This object should be sent in the following format for all fields you wish to map:  {specificationName}:{specificationValue}, Example: Choose voltage: Voltage,  Choose size: Size., matchFlux: str=autoApprove # This field determines the type of approval configuration applied to SKUs received  from a seller. The possible values include:   - `default` where the Matcher reviews the SKU, and approves it based on its score   - `manual` for manual approvals through the Received SKU UI or Match API   - `autoApprove` for every SKU received from a given seller to be approved automatically, regardless of the Matcher Score.}\n@returns(200) OK\n@example_request {\"sellerId\":\"1a\",\"mapping\":null,\"matchFlux\":\"Default\"}\n\n@endpoint PUT /suggestions/configuration/autoapproval/toggle/seller/{sellerId}\n@desc Activate autoApprove setting for a seller\n@required {sellerId: str # A string that identifies the seller in the marketplace. This ID must be created by the marketplace., Enabled: bool=true # Insert `true` if you wish to activate the autoapprove rule for that specific seller account. Insert `false` if you wish to deactivate it. Be aware that once enabling the setting through this request, all SKUs received from this seller will be automatically approved on your store regardless of the Matcher Score.}\n@returns(200) OK\n@example_request {\"Enabled\":true}\n\n@endpoint GET /suggestions\n@desc Get all SKU suggestions\n@optional {q: str # This field allows you to customize your search. You can fill in this query param if you want to narrow down your search using the available filters on Received SKU modules., type: str # This field allows users to filter SKU suggestions, by searching only the new suggestions that were just sent, and suggestions that have already been sent, but were updated. Possible values for this field include `new` and `update`., seller: str # A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller so it can call this endpoint., status: str # Narrow down you search, filtering by status. Values allowed on this field include: `accepted`, `pending` and `denied.`, hasmapping: str # This field allows you to filter SKUs that have mapping or not. Insert `true` to filter SKUs that have mapping, or `false` to retrieve SKUs that aren't mapped., matcherid: str=vtex-matcher # Identifies the matching entity. It can be either VTEX's matcher, or an external matcher developed by partners, for example. The `matcherId`'s value can be obtained through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion) endpoint., _from: int(int32) # Define your pagination range, by adding the pagination starting value. Values should be bigger than 0, with a maximum of 50 records per page., _to: int(int32) # Define your pagination range, by adding the pagination ending value. Values should be bigger than 0, with a maximum of 50 records per page.}\n@returns(200) OK\n\n@endpoint PUT /suggestions/{sellerId}/{sellerSkuId}\n@desc Send SKU suggestion\n@required {sellerId: str # A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built., sellerSkuId: str # A string that identifies the SKU in the seller. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications., ProductName: str # Name of the suggested product. This field has a limit of 150 characters., ProductId: str # Product ID in seller's account., ProductDescription: str # Product description containing the main information about the product (not the SKU)., BrandName: str # Name of the brand to which this SKU belongs. It must match the brand created in the marketplace., SkuName: str # Name of the suggested SKU., SellerId: str # ID of the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built., Height: int(decimal) # Height of the SKU., Width: int(decimal) # Width of the SKU., Length: int(decimal) # Length of the SKU., Weight: int(decimal) # Weight of the SKU in grams., RefId: str=REF10 # SKU reference code. Mandotory if the EAN is not informed., EAN: str # SKU reference code. Mandatory if the RefId is not informed., CategoryFullPath: str # Full path to the SKU's category. It should be written as {department}/{category}. For example: if the department is **Appliances** and the category is **Oven**, the full path should be 'Appliances/Oven'., Images: [map{imageName!: str, imageUrl!: str}] # Array containing the URLs and names the SKU images., AvailableQuantity: int(int32) # The number of items currently available for sales., Pricing: map{Currency: str, SalePrice: int, CurrencySymbol: str} # Object containing pricing details, including the currency, sales price, and currency symbol.}\n@optional {SellerStockKeepingUnitId: int(int32) # ID of the SKU registered in the seller., SkuSpecifications: [map{fieldName: str, fieldValues: [str]}] # Array containing the names and values of the SKU specifications., ProductSpecifications: [map{fieldName: str, fieldValues: [str]}] # Array containing the names and values of the product specifications., MeasurementUnit: str # Measurement unit that should be used for this SKU. If this information doesn't apply, you should use the default value `un`., UnitMultiplier: int(int32) # Unit multiplier for this SKU. If this information doesn't apply, you should use the default value `1`.}\n@returns(200) OK\n@example_request {\"ProductId\":\"321\",\"ProductName\":\"Product sample\",\"NameComplete\":\"Complete product name\",\"ProductDescription\":\"sample\",\"BrandName\":\"Brand 1\",\"SkuName\":\"Sku sample\",\"SellerId\":\"string\",\"Height\":1,\"Width\":1,\"Length\":1,\"Weight\":1,\"Updated\":null,\"RefId\":\"REFID123\",\"SellerStockKeepingUnitId\":567,\"CategoryFullPath\":\"Category 1\",\"Images\":[{\"imageName\":\"Principal\",\"imageUrl\":\"https://i.pinimg.com/originals/2d/96/4a/2d964a6bf37d9224d0615dc85fccdd62.jpg\"}],\"ProductSpecifications\":[{\"fieldName\":\"Fabric\",\"fieldValues\":[\"Cotton\",\"Velvet\"]}],\"SkuSpecifications\":[{\"fieldName\":\"Color\",\"fieldValues\":[\"Red\",\"Blue\"]}],\"EAN\":\"EAN123\",\"MeasurementUnit\":\"un\",\"UnitMultiplier\":1,\"AvailableQuantity\":111,\"Pricing\":{\"Currency\":\"BRL\",\"SalePrice\":399,\"CurrencySymbol\":\"R$\"}}\n\n@endpoint GET /suggestions/{sellerId}/{sellerSkuId}\n@desc Get SKU suggestion by ID\n@required {sellerId: str # A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built., sellerSkuId: str # A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.}\n@returns(200) OK\n\n@endpoint DELETE /suggestions/{sellerId}/{sellerSkuId}\n@desc Delete SKU suggestion\n@required {sellerId: str # A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built., sellerSkuId: str # A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.}\n@returns(200) OK\n\n@endpoint GET /suggestions/{sellerId}/{sellerskuid}/versions\n@desc Get all versions\n@required {sellerId: str # A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built., sellerskuid: str # A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.}\n@returns(200) OK\n\n@endpoint GET /suggestions/{sellerId}/{sellerskuid}/versions/{version}\n@desc Get version by ID\n@required {sellerId: str # A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built., sellerskuid: str # A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications., version: str # Whenever an SKU Suggestion is updated or changed, a new version of the original one is created. All versions are logged, so you can search for previous our current states of SKU suggestions. This field is the `versionId` associated to the version you choose to search for. You can get this field's value through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion). through the `latestVersionId` field.}\n@returns(200) OK\n\n@endpoint PUT /suggestions/{sellerId}/{sellerskuid}/versions/{version}/matches/{matchid}\n@desc Match received SKUs individually\n@required {sellerId: str # A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built., sellerskuid: str # A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications., version: str # Whenever an SKU Suggestion is updated or changed, a new version of the original one is created. All versions are logged, so you can search for previous our current states of SKU suggestions. This field is the versionId associated to the version you choose to search for. You can get this field's value through the[Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion). through the `latestVersionId` field., matchid: str # Whenever an SKU suggestion is matched, it is associated to a unique ID. Fill in this field with the matchId you wish to filter by. The `matchId`'s value can be obtained through the *[Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion) endpoint., matcherId: str=vtex-matcher # Identifies the matching entity. It can be either VTEX's matcher, or an external matcher developed by partners, for example. The `matcherId`'s value can be obtained through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion) endpoint., matchType: str # Define the action you want to apply to each SKU. Values include:   1. `newproduct`: match the SKU as a new product.   2. `itemMatch`: associate the received SKU to an existing SKU.   3. `productMatch`: associate the received SKU to an existing product.   4. `deny`: deny the received SKU.   5. `pending`: the received SKU requires attention.   6. `incomplete`: the received SKU is lacking information to be matched.   7. `insufficientScore`: the score given by the Matcher to this received SKU doesn't qualify it to be matched.   Note that  if the autoApprove setting is enabled, the SKUs will be approved, regardless of the Score., score: str=80 # Matcher rates received SKUs by correlating the data sent by sellers, to existing fields in the marketplace. The calculation of these scores determines whether the product has been:   `Approved`: score equal to or greater than 80 points.   `Pending`: from 31 to 79 points.  `Denied`: from 0 to 30 points.   Note that  if the autoApprove setting is enabled, the SKUs will be approved, regardless of the Score.}\n@optional {skuRef: str # In `itemMatch` actions, fill in this field on your request to match the item to an existing SKU in the marketplace., productRef: str # In `productMatch` actions, fill in this field on your request to match the item to an existing product in the marketplace., product: map{name!: str, description!: str, categoryId!: int(int32), brandId!: int(int32), specifications!: map} # Represents the product details in the catalog. The product object includes essential attributes such as the product's name, description, category, brand, and specifications. This information is used to define and manage the product within the marketplace, ensuring that it is properly categorized and described for users., sku: map{name!: str, eans!: [str], refId!: str, height!: int(int32), width!: int(int32), length!: int(int32), weight!: int(int32), images!: map, unitMultiplier!: int(int32), measurementUnit!: str, specifications!: map} # Represents the SKU (Stock Keeping Unit) details for a product. The SKU is a unique identifier that contains specific attributes such as dimensions, weight, and other product specific information. This object is crucial for defining and managing the individual variations of a product in the catalog.}\n@returns(200) OK\n@example_request {\"matcherId\":\"{{matcherid}}\",\"matchType\":\"itemMatch\",\"score\":\"{{score}} (must be decimal)\",\"skuRef\":\"{{skuid}}(should be specifed when match is a sku match)\",\"productRef\":\"{{productRef}}(should be specified when match is a product match)\",\"product\":{\"name\":\"Book A\",\"description\":\"Book description\",\"categoryId\":12,\"brandId\":1234567,\"matchType\":\"itemMatch\",\"specifications\":null},\"sku\":{\"name\":\"Sku exemplo\",\"eans\":[\"12345678901213\"],\"refId\":null,\"height\":1,\"width\":1,\"length\":1,\"weight\":1,\"images\":{\"imagem1.jpg\":\"https://imageurl.example\"},\"unitMultiplier\":1,\"measurementUnit\":\"un\",\"specifications\":{\"Packaging\":\"3kg\"}}}\n\n@endpoint PUT /suggestions/matches/action/{actionName}\n@desc Match multiple received SKUs\n@required {actionName: str(newproduct/skuassociation/productassociation/deny) # Operation to apply to received SKUs. Possible values include:   * `newproduct`: match the SKU as a new product.   * `skuassociation`: associate the received SKU to an existing SKU.   * `productassociation`: associate the received SKU to an existing product.   * `deny`: deny the received SKU.}\n@returns(200) OK\n@example_request [{\"itemId\":\"1234567\",\"versionId\":\"v.2\",\"matchId\":\"06272023010821403\",\"matcherId\":\"vtex-matcher\",\"categoryId\":12,\"brandId\":1234567,\"skuRef\":\"123 sku ref\",\"productRef\":null,\"sellerId\":\"seller123\"}]\n\n@endpoint PUT /suggestions/configuration/{sellerID}/specifications\n@desc Map seller specifications to marketplace catalog\n@required {sellerID: str # Marketplace seller ID whose specifications will be mapped}\n@returns(200) OK\n@example_request {\"43\":\"41\",\"Size\":\"SIZE\",\"Cor\":\"Color\",\"BROWN\":\"Brown\",\"Brand\":\"brand\"}\n\n@end\n"}}