How to implement the "SearchProduct" API
Catalog management
When implementing the endpoint, the method must be GET.
You will receive the following data in the queryString:
query: Refers to the search term.
from: The from parameter defines the number of hits to skip, defaulting to 0.
size: Total items per page. Default is 10.
teamId: Id of the team that is carrying out this search.
userId: Id of the user who is performing this search.
userEmail: Email of the user who is performing this search.
integrationId: Id of the integration being used.
searchType: The type of query, whether by TEXT , ID, SKUID, URL and REFERENCE. Default is TEXT.
Example:
curl --location 'https://your_endpoint?searchType=TEXT&query=blue shirt&size=15&from=0&teamId=123&userId=1234&[email protected]&integrationId=abcd-1234'Whenever a product is consulted by OmniChat, this api will be called, and it must return a list of products following the pattern below:
[
{
"blocked": false,
"objectId": "12345",
"name": "iPhone 14 Pro",
"productDescription": "Produto de teste",
"externalUrl": "https://www.apple.com/br/iphone-14-pro/",
"externalProduct": true,
"mainVariant": {
"objectId": "12345-1",
"externalImageURL": "https://www.apple.com/newsroom/images/product/iphone/geo/Apple-iPhone-14-Pro-iPhone-14-Pro-Max-deep-purple-220907-geo_inline.jpg.large.jpg",
"erpId": "12345-2",
"name": "iPhone 14 Pro 128gb Purple",
"visible": true,
"price": 4771.59,
"salePrice": 4485.29,
"quantity": 30,
"sellerId": "1",
"sellerName": "Apple",
"installmentOptions": [
{
"name": "Visa",
"oneTimePayment": 4485.29,
"maxInstallments": 21,
"installmentPrice": 255.76,
"interest": 1.7,
"totalWithInterest": 5370.96
},
{
"name": "Mastercard",
"oneTimePayment": 4485.29,
"maxInstallments": 21,
"installmentPrice": 255.76,
"interest": 1.7,
"totalWithInterest": 5370.96
},
{
"name": "Pix",
"oneTimePayment": 4199,
"maxInstallments": 1,
"installmentPrice": 4199,
"interest": 0,
"totalWithInterest": 4199
}
],
"width": 7.15,
"height": 14.8,
"variantLength": 1,
"weight": 206,
"variations": [
{
"key": "Cor",
"value": "Purple"
},
{
"key": "Memória",
"value": "128gb"
}
]
},
"variants": [
{
"objectId": "12345-1",
"externalImageURL": "https://www.apple.com/newsroom/images/product/iphone/geo/Apple-iPhone-14-Pro-iPhone-14-Pro-Max-deep-purple-220907-geo_inline.jpg.large.jpg",
"erpId": "54321-1",
"name": "iPhone 14 Pro 128gb Purple",
"visible": true,
"price": 4771.59,
"salePrice": 4485.29,
"quantity": 30,
"sellerId": "1",
"sellerName": "Apple",
"installmentOptions": [
{
"name": "Visa",
"oneTimePayment": 4485.29,
"maxInstallments": 21,
"installmentPrice": 255.76,
"interest": 1.7,
"totalWithInterest": 5370.96
},
{
"name": "Mastercard",
"oneTimePayment": 4485.29,
"maxInstallments": 21,
"installmentPrice": 255.76,
"interest": 1.7,
"totalWithInterest": 5370.96
},
{
"name": "Pix",
"oneTimePayment": 4199,
"maxInstallments": 1,
"installmentPrice": 4199,
"interest": 0,
"totalWithInterest": 4199
}
],
"width": 7.15,
"height": 14.8,
"variantLength": 1,
"weight": 206,
"variations": [
{
"key": "Cor",
"value": "Purple"
},
{
"key": "Memória",
"value": "128gb"
}
]
},
{
"objectId": "12345-2",
"externalImageURL": "https://store.storeimages.cdn-apple.com/4982/as-images.apple.com/is/iphone-14-pro-gold-witb-202209_FMT_WHH?wid=560&hei=744&fmt=jpeg&qlt=90&.v=1660789320262",
"erpId": "54321-2",
"name": "iPhone 14 Pro 128gb Gold",
"visible": true,
"price": 4771.59,
"salePrice": 4485.29,
"quantity": 28,
"sellerId": "1",
"sellerName": "Apple",
"width": 7.15,
"height": 14.8,
"variantLength": 1,
"weight": 206,
"variations": [
{
"key": "Cor",
"value": "Gold"
},
{
"key": "Memória",
"value": "128gb"
}
]
},
{
"objectId": "12345-3",
"externalImageURL": "https://www.apple.com/newsroom/images/product/iphone/geo/Apple-iPhone-14-Pro-iPhone-14-Pro-Max-silver-220907-geo_inline.jpg.large.jpg",
"erpId": "54321-2",
"name": "iPhone 14 Pro 128gb Silver",
"visible": true,
"price": 4771.59,
"salePrice": 4771.59,
"quantity": 0,
"sellerId": "1",
"sellerName": "Apple",
"width": 7.15,
"height": 14.8,
"variantLength": 1,
"weight": 206,
"variations": [
{
"key": "Cor",
"value": "Gold"
},
{
"key": "Memória",
"value": "128gb"
}
]
}
],
"sellOutOfStock": false,
"trackInventory": true
},
{
"blocked": false,
"objectId": "123456",
"name": "iPhone 13",
"productDescription": "Produto de teste",
"externalUrl": "https://www.apple.com/br/shop/buy-iphone/iphone-13",
"mainVariant": {
"objectId": "123456-1",
"externalImageURL": "https://store.storeimages.cdn-apple.com/4982/as-images.apple.com/is/iphone-13-blue-witb-2021_FMT_WHH?wid=560&hei=744&fmt=jpeg&qlt=90&.v=1638579080000",
"erpId": "123456-2",
"name": "iPhone 13 128gb blue",
"visible": true,
"price": 6499.99,
"salePrice": 6400.5,
"quantity": 30,
"sellerId": "1",
"sellerName": "Apple",
"width": 7.15,
"height": 14.8,
"variantLength": 1,
"weight": 206,
"variations": [
{
"key": "Cor",
"value": "Purple"
},
{
"key": "Memória",
"value": "128gb"
}
]
},
"variants": [
{
"objectId": "123456-1",
"externalImageURL": "https://store.storeimages.cdn-apple.com/4982/as-images.apple.com/is/iphone-13-blue-witb-2021_FMT_WHH?wid=560&hei=744&fmt=jpeg&qlt=90&.v=1638579080000",
"erpId": "123456-2",
"name": "iPhone 13 128gb blue",
"visible": true,
"price": 6499.99,
"salePrice": 6400.5,
"quantity": 30,
"sellerId": "1",
"sellerName": "Apple",
"width": 7.15,
"height": 14.8,
"variantLength": 1,
"weight": 206,
"variations": [
{
"key": "Cor",
"value": "Blue"
},
{
"key": "Memória",
"value": "128gb"
}
]
}
],
"sellOutOfStock": false,
"trackInventory": true
}
]Payment options (installmentOptions)
installmentOptions)installmentOptions is an optional field available on mainVariant and on each item of variants. It lists the installment plans available for that variant, with one entry per payment method. When the variant has no installment plans, omit the field — do not send an empty array.
Each entry describes the plan with the highest number of installments for that payment method:
name: Name of the payment method (for example, Visa, Mastercard, Pix).
oneTimePayment: Amount charged for a single payment (1x).
maxInstallments: Maximum number of installments available for this payment method.
installmentPrice: Amount of each installment at maxInstallments.
interest: Interest rate applied at maxInstallments. Use 0 for interest-free plans.
totalWithInterest: Total amount paid at maxInstallments, including interest.
In the example above, the product on sale for 4485.29 can be paid upfront on card for 4485.29, in up to 21 installments of 255.76 (5370.96 total with interest), or for 4199 via Pix — the lower upfront price for that payment method.
If you want to use omnichat's collections functionality, you need to implement the search endpoint by id (more details in "How to implement the "SearchProduct by Id" API").
Updated 16 days ago