{ "components": { "schemas": { "CarrefourksaCategoriesListCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "carrefourksa.categories.list" ], "type": "string" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "carrefourksa" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "results": { "items": { "additionalProperties": false, "properties": { "data": { "description": "Raw capability output. Its shape may evolve with the upstream source; the example is illustrative, not a compatibility guarantee.", "example": { "categories": [ { "id": "FKSA1600000", "leaf": false, "level": 1, "name": "Fresh Food", "parent": "", "thumbnail": "https://cdnprod.mafretailproxy.com/sys-master-root/hea/h28/10752247365662/FreshFood.png", "title": "Fresh Food", "url": "/c/FKSA1600000" }, { "id": "FKSA1620000", "leaf": false, "level": 2, "name": "Chilled Food Counter", "parent": "FKSA1600000", "thumbnail": "https://framestrapimaster.blob.core.windows.net/assets/images/[redacted:token].png", "title": "Chilled Food Counter", "url": "/c/FKSA1620000" }, { "id": "FKSA1620100", "leaf": true, "level": 3, "name": "Cold Cuts & Meat Snacks", "parent": "FKSA1620000", "thumbnail": "https://hybrisproduction.blob.core.windows.net/sys-master-prod/L3-images/FreshFood/1620100.png", "title": "Cold Cuts & Meat Snacks", "url": "/c/FKSA1620100" } ] } }, "error": { "type": "null" }, "index": { "const": 0, "type": "integer" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "index", "url", "data", "error" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "state": { "const": "completed", "type": "string" }, "stats": { "$ref": "#/components/schemas/JobStats" }, "success": { "const": true, "type": "boolean" } }, "required": [ "job_id", "request_id", "platform", "capability", "state", "success", "results", "billing", "stats" ], "type": "object" }, "CarrefourksaCategoriesListExecuteRequest": { "additionalProperties": false, "example": { "capability": "carrefourksa.categories.list", "input": {} }, "properties": { "capability": { "enum": [ "carrefourksa.categories.list" ], "type": "string" }, "input": { "$ref": "#/components/schemas/CarrefourksaCategoriesListInput" }, "network": { "$ref": "#/components/schemas/ExecuteNetwork" }, "timeout_ms": { "description": "Optional request timeout in milliseconds. Values above the capability timeout are rejected.", "maximum": 120000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "type": "object" }, "CarrefourksaCategoriesListInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "latitude": { "description": "Store catchment latitude. Defaults to 24.7136 (Riyadh).", "type": "string" }, "limit": { "minimum": 1, "type": "integer" }, "longitude": { "description": "Store catchment longitude. Defaults to 46.6753 (Riyadh).", "type": "string" }, "max_records": { "minimum": 1, "type": "integer" } }, "type": "object" }, "CarrefourksaCategoryProductsListCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "carrefourksa.category.products.list" ], "type": "string" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "carrefourksa" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "results": { "items": { "additionalProperties": false, "properties": { "data": { "description": "Raw capability output. Its shape may evolve with the upstream source; the example is illustrative, not a compatibility guarantee.", "example": { "pagination": { "num_of_pages": 19, "page": 0, "total_products": 455 }, "products": [ { "soldByWeight": false, "isBulk": false, "ean": "12000051999", "isFBC": false, "category": [ { "aliasName": "FKSA1500000", "id": "FKSA1500000", "level": 1, "name": "Beverages", "url": "/c/FKSA1500000/" }, { "aliasName": "FKSA1550000", "id": "FKSA1550000", "level": 2, "name": "Soft Drinks", "url": "/c/FKSA1550000/" } ], "freeGift": false, "amendableOrders": [], "links": { "defaultImages": [ "https://cdn.mafrservices.com/sys-master-root/he8/h41/51636552597534/627660_main.jpg?im=Resize=1700" ], "images": [ { "href": "https://cdn.mafrservices.com/sys-master-root/he8/h41/51636552597534/627660_main.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/sys-master-root/he8/h41/51636552597534/627660_main.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" } ], "productUrl": { "href": "/mafsau/en/lemonade-mixers/7-up-can-325ml-x24/p/627660", "kind": "product", "rel": "self", "type": "GET" }, "tracking": [] }, "type": "FOOD", "promoVoucher": {}, "variants": [], "dxtVouchers": [], "isMarketPlace": false, "availability": { "isAvailable": true, "max": 50 }, "servingIntents": [ "SLOTTED" ], "foodType": "DRY", "preorder": false, "howGood": false, "bulkMessage": "", "isVirtualBundle": false, "supplier": "Carrefour", "delivery": [], "name": "7UP, Carbonated Soft Drink, Cans, 325ml x 24", "id": "627660", "promoBadges": [ { "id": "4905752a-e5cc-40b4-84f2-a104030865db", "placement": "AREA-A", "priority": 10, "seller": "Carrefour", "text": { "boldText": "Online Exclusive Offer", "normalText": "" }, "type": "Campaign" } ], "productCategoriesHearchi": "Beverages/Soft Drinks/Carbonated Drinks/Lemonade Mixers", "price": { "currency": "SAR", "discount": { "endDate": "8/4/2026, 8:59:00 PM", "formattedValue": "SAR52.99", "minBuyingValue": "52.99", "price": 52.99, "type": "percentage", "value": 5 }, "formattedValue": "SAR56.00", "minBuyingValue": "56.00", "price": 56 }, "warranty": false, "extraLoyaltyPointsEarned": 0, "size": "325ml x 24", "brand": { "id": "01023", "name": "7Up" }, "isExpress": false, "loyaltyPoints": 0, "isScalable": false, "isRecommended": false, "deliveryFees": { "freeDeliveryThreshold": 120 }, "unit": { "incrementBy": 1, "itemsPerUnit": 0, "max": 50, "maxToOrder": 50, "min": 1, "size": "325ml x 24", "unitItem": 0, "unitOfMeasure": "pieces" }, "page_type": "group_id", "stock": { "stockLevelStatus": "inStock" }, "isDirectMatch": false, "offers": [ { "brightbites": false, "id": "offer_carrefour_", "internationalShipping": false, "purchaseIndicators": { "SHIPPING": [ "SLOTTED" ] }, "sellerName": "Carrefour", "serviceProductTypes": null, "shippingIndicator": "SLOTTED", "shopId": "0000", "type": "main" } ], "availableVariants": [] }, { "soldByWeight": false, "isBulk": false, "ean": "12000062278", "isFBC": false, "category": [ { "aliasName": "FKSA1500000", "id": "FKSA1500000", "level": 1, "name": "Beverages", "url": "/c/FKSA1500000/" }, { "aliasName": "FKSA1550000", "id": "FKSA1550000", "level": 2, "name": "Soft Drinks", "url": "/c/FKSA1550000/" } ], "freeGift": false, "amendableOrders": [], "links": { "defaultImages": [ "https://cdn.mafrservices.com/sys-master-root/hb8/h77/61617751752734/694540_main.jpg?im=Resize=1700" ], "images": [ { "href": "https://cdn.mafrservices.com/sys-master-root/hb8/h77/61617751752734/694540_main.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/sys-master-root/hb8/h77/61617751752734/694540_main.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" } ], "productUrl": { "href": "/mafsau/en/lemonade-mixers/7up-zero-sugar-cans-150ml-x12/p/694540", "kind": "product", "rel": "self", "type": "GET" }, "tracking": [] }, "type": "FOOD", "promoVoucher": {}, "variants": [], "dxtVouchers": [], "isMarketPlace": false, "availability": { "isAvailable": true, "max": 50 }, "servingIntents": [ "SLOTTED" ], "foodType": "DRY", "preorder": false, "howGood": false, "bulkMessage": "", "isVirtualBundle": false, "supplier": "Carrefour", "delivery": [], "name": "7UP Zero Sugar Cans 150ml x12", "id": "694540", "promoBadges": [], "productCategoriesHearchi": "Beverages/Soft Drinks/Carbonated Drinks/Lemonade Mixers", "price": { "currency": "SAR", "discount": { "endDate": "8/4/2026, 8:59:00 PM", "formattedValue": "SAR15.00", "minBuyingValue": "15.00", "price": 15, "type": "percentage", "value": 17 }, "formattedValue": "SAR18.00", "minBuyingValue": "18.00", "price": 18 }, "warranty": false, "extraLoyaltyPointsEarned": 0, "size": "150ml x12", "brand": { "id": "01023", "name": "7Up" }, "isExpress": false, "loyaltyPoints": 0, "isScalable": false, "isRecommended": false, "deliveryFees": { "freeDeliveryThreshold": 120 }, "unit": { "incrementBy": 1, "itemsPerUnit": 0, "max": 50, "maxToOrder": 50, "min": 1, "size": "150ml x12", "unitItem": 0, "unitOfMeasure": "pieces" }, "page_type": "group_id", "stock": { "stockLevelStatus": "inStock" }, "isDirectMatch": false, "offers": [ { "brightbites": false, "id": "offer_carrefour_", "internationalShipping": false, "purchaseIndicators": { "SHIPPING": [ "SLOTTED" ] }, "sellerName": "Carrefour", "serviceProductTypes": null, "shippingIndicator": "SLOTTED", "shopId": "0000", "type": "main" } ], "availableVariants": [] }, { "soldByWeight": false, "isBulk": false, "ean": "12000060359", "isFBC": false, "category": [ { "aliasName": "FKSA1500000", "id": "FKSA1500000", "level": 1, "name": "Beverages", "url": "/c/FKSA1500000/" }, { "aliasName": "FKSA1550000", "id": "FKSA1550000", "level": 2, "name": "Soft Drinks", "url": "/c/FKSA1550000/" } ], "freeGift": false, "amendableOrders": [], "links": { "defaultImages": [ "https://cdn.mafrservices.com/sys-master-root/h39/h8d/15071872942110/663739_main.jpg?im=Resize=1700" ], "images": [ { "href": "https://cdn.mafrservices.com/sys-master-root/h39/h8d/15071872942110/663739_main.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/sys-master-root/h39/h8d/15071872942110/663739_main.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" } ], "productUrl": { "href": "/mafsau/en/cola-zero/diet-pepsi-mini-can-150ml-x12/p/663739", "kind": "product", "rel": "self", "type": "GET" }, "tracking": [] }, "type": "FOOD", "promoVoucher": {}, "variants": [], "dxtVouchers": [], "isMarketPlace": false, "availability": { "isAvailable": true, "max": 50 }, "servingIntents": [ "SLOTTED" ], "foodType": "DRY", "preorder": false, "howGood": false, "bulkMessage": "", "isVirtualBundle": false, "supplier": "Carrefour", "delivery": [], "name": "Pepsi Cola Diet Can 150ml x 12", "id": "663739", "promoBadges": [ { "id": "a72f55da-96e5-4e30-9b9c-d93188d791ca", "placement": "AREA-A", "priority": 1, "seller": "Carrefour", "text": { "boldText": "BESTSELLER", "normalText": "" }, "type": "BestSeller" } ], "productCategoriesHearchi": "Beverages/Soft Drinks/Carbonated Drinks/Cola Zero", "price": { "currency": "SAR", "discount": { "endDate": "8/4/2026, 8:59:00 PM", "formattedValue": "SAR15.00", "minBuyingValue": "15.00", "price": 15, "type": "percentage", "value": 17 }, "formattedValue": "SAR18.00", "minBuyingValue": "18.00", "price": 18 }, "warranty": false, "extraLoyaltyPointsEarned": 0, "size": "150ml x 12", "brand": { "id": "12177", "name": "Pepsi cola" }, "isExpress": false, "loyaltyPoints": 0, "isScalable": false, "isRecommended": false, "deliveryFees": { "freeDeliveryThreshold": 120 }, "unit": { "incrementBy": 1, "itemsPerUnit": 0, "max": 50, "maxToOrder": 50, "min": 1, "size": "150ml x 12", "unitItem": 0, "unitOfMeasure": "pieces" }, "page_type": "group_id", "stock": { "stockLevelStatus": "inStock" }, "isDirectMatch": false, "offers": [ { "brightbites": false, "id": "offer_carrefour_", "internationalShipping": false, "purchaseIndicators": { "SHIPPING": [ "SLOTTED" ] }, "sellerName": "Carrefour", "serviceProductTypes": null, "shippingIndicator": "SLOTTED", "shopId": "0000", "type": "main" } ], "availableVariants": [] } ], "raw": { "algoliaQueryID": "[redacted:token]", "breadCrumb": [ { "aliasName": "FKSA1500000", "id": "FKSA1500000", "level": 1, "name": "Beverages", "url": "/c/FKSA1500000/" }, { "aliasName": "FKSA1550000", "id": "FKSA1550000", "level": 2, "name": "Soft Drinks", "url": "/c/FKSA1550000/" } ], "exactMatch": true, "hybridMeta": { "usedHybridSplit": true, "vectorHits": 24 }, "is_food_category": true, "keywordSuggestions": [], "numOfPages": 19, "outOfStockProducts": [], "pagination": { "currentPage": 0, "pageSize": 24, "skip": 0, "sort": "relevance", "top": 24, "totalPages": 19, "totalResults": 455 }, "posInfo": { "DEFAULT": "301", "MKP_GLOBAL": "MKP_GLOBAL", "SLOTTED": "301" }, "products": [ { "soldByWeight": false, "isBulk": false, "ean": "12000051999", "isFBC": false, "category": [ { "aliasName": "FKSA1500000", "id": "FKSA1500000", "level": 1, "name": "Beverages", "url": "/c/FKSA1500000/" }, { "aliasName": "FKSA1550000", "id": "FKSA1550000", "level": 2, "name": "Soft Drinks", "url": "/c/FKSA1550000/" } ], "freeGift": false, "amendableOrders": [], "links": { "defaultImages": [ "https://cdn.mafrservices.com/sys-master-root/he8/h41/51636552597534/627660_main.jpg?im=Resize=1700" ], "images": [ { "href": "https://cdn.mafrservices.com/sys-master-root/he8/h41/51636552597534/627660_main.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/sys-master-root/he8/h41/51636552597534/627660_main.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" } ], "productUrl": { "href": "/mafsau/en/lemonade-mixers/7-up-can-325ml-x24/p/627660", "kind": "product", "rel": "self", "type": "GET" }, "tracking": [] }, "type": "FOOD", "promoVoucher": {}, "variants": [], "dxtVouchers": [], "isMarketPlace": false, "availability": { "isAvailable": true, "max": 50 }, "servingIntents": [ "SLOTTED" ], "foodType": "DRY", "preorder": false, "howGood": false, "bulkMessage": "", "isVirtualBundle": false, "supplier": "Carrefour", "delivery": [], "name": "7UP, Carbonated Soft Drink, Cans, 325ml x 24", "id": "627660", "promoBadges": [ { "id": "4905752a-e5cc-40b4-84f2-a104030865db", "placement": "AREA-A", "priority": 10, "seller": "Carrefour", "text": { "boldText": "Online Exclusive Offer", "normalText": "" }, "type": "Campaign" } ], "productCategoriesHearchi": "Beverages/Soft Drinks/Carbonated Drinks/Lemonade Mixers", "price": { "currency": "SAR", "discount": { "endDate": "8/4/2026, 8:59:00 PM", "formattedValue": "SAR52.99", "minBuyingValue": "52.99", "price": 52.99, "type": "percentage", "value": 5 }, "formattedValue": "SAR56.00", "minBuyingValue": "56.00", "price": 56 }, "warranty": false, "extraLoyaltyPointsEarned": 0, "size": "325ml x 24", "brand": { "id": "01023", "name": "7Up" }, "isExpress": false, "loyaltyPoints": 0, "isScalable": false, "isRecommended": false, "deliveryFees": { "freeDeliveryThreshold": 120 }, "unit": { "incrementBy": 1, "itemsPerUnit": 0, "max": 50, "maxToOrder": 50, "min": 1, "size": "325ml x 24", "unitItem": 0, "unitOfMeasure": "pieces" }, "page_type": "group_id", "stock": { "stockLevelStatus": "inStock" }, "isDirectMatch": false, "offers": [ { "brightbites": false, "id": "offer_carrefour_", "internationalShipping": false, "purchaseIndicators": { "SHIPPING": [ "SLOTTED" ] }, "sellerName": "Carrefour", "serviceProductTypes": null, "shippingIndicator": "SLOTTED", "shopId": "0000", "type": "main" } ], "availableVariants": [] }, { "soldByWeight": false, "isBulk": false, "ean": "12000062278", "isFBC": false, "category": [ { "aliasName": "FKSA1500000", "id": "FKSA1500000", "level": 1, "name": "Beverages", "url": "/c/FKSA1500000/" }, { "aliasName": "FKSA1550000", "id": "FKSA1550000", "level": 2, "name": "Soft Drinks", "url": "/c/FKSA1550000/" } ], "freeGift": false, "amendableOrders": [], "links": { "defaultImages": [ "https://cdn.mafrservices.com/sys-master-root/hb8/h77/61617751752734/694540_main.jpg?im=Resize=1700" ], "images": [ { "href": "https://cdn.mafrservices.com/sys-master-root/hb8/h77/61617751752734/694540_main.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/sys-master-root/hb8/h77/61617751752734/694540_main.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" } ], "productUrl": { "href": "/mafsau/en/lemonade-mixers/7up-zero-sugar-cans-150ml-x12/p/694540", "kind": "product", "rel": "self", "type": "GET" }, "tracking": [] }, "type": "FOOD", "promoVoucher": {}, "variants": [], "dxtVouchers": [], "isMarketPlace": false, "availability": { "isAvailable": true, "max": 50 }, "servingIntents": [ "SLOTTED" ], "foodType": "DRY", "preorder": false, "howGood": false, "bulkMessage": "", "isVirtualBundle": false, "supplier": "Carrefour", "delivery": [], "name": "7UP Zero Sugar Cans 150ml x12", "id": "694540", "promoBadges": [], "productCategoriesHearchi": "Beverages/Soft Drinks/Carbonated Drinks/Lemonade Mixers", "price": { "currency": "SAR", "discount": { "endDate": "8/4/2026, 8:59:00 PM", "formattedValue": "SAR15.00", "minBuyingValue": "15.00", "price": 15, "type": "percentage", "value": 17 }, "formattedValue": "SAR18.00", "minBuyingValue": "18.00", "price": 18 }, "warranty": false, "extraLoyaltyPointsEarned": 0, "size": "150ml x12", "brand": { "id": "01023", "name": "7Up" }, "isExpress": false, "loyaltyPoints": 0, "isScalable": false, "isRecommended": false, "deliveryFees": { "freeDeliveryThreshold": 120 }, "unit": { "incrementBy": 1, "itemsPerUnit": 0, "max": 50, "maxToOrder": 50, "min": 1, "size": "150ml x12", "unitItem": 0, "unitOfMeasure": "pieces" }, "page_type": "group_id", "stock": { "stockLevelStatus": "inStock" }, "isDirectMatch": false, "offers": [ { "brightbites": false, "id": "offer_carrefour_", "internationalShipping": false, "purchaseIndicators": { "SHIPPING": [ "SLOTTED" ] }, "sellerName": "Carrefour", "serviceProductTypes": null, "shippingIndicator": "SLOTTED", "shopId": "0000", "type": "main" } ], "availableVariants": [] }, { "soldByWeight": false, "isBulk": false, "ean": "12000060359", "isFBC": false, "category": [ { "aliasName": "FKSA1500000", "id": "FKSA1500000", "level": 1, "name": "Beverages", "url": "/c/FKSA1500000/" }, { "aliasName": "FKSA1550000", "id": "FKSA1550000", "level": 2, "name": "Soft Drinks", "url": "/c/FKSA1550000/" } ], "freeGift": false, "amendableOrders": [], "links": { "defaultImages": [ "https://cdn.mafrservices.com/sys-master-root/h39/h8d/15071872942110/663739_main.jpg?im=Resize=1700" ], "images": [ { "href": "https://cdn.mafrservices.com/sys-master-root/h39/h8d/15071872942110/663739_main.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/sys-master-root/h39/h8d/15071872942110/663739_main.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" } ], "productUrl": { "href": "/mafsau/en/cola-zero/diet-pepsi-mini-can-150ml-x12/p/663739", "kind": "product", "rel": "self", "type": "GET" }, "tracking": [] }, "type": "FOOD", "promoVoucher": {}, "variants": [], "dxtVouchers": [], "isMarketPlace": false, "availability": { "isAvailable": true, "max": 50 }, "servingIntents": [ "SLOTTED" ], "foodType": "DRY", "preorder": false, "howGood": false, "bulkMessage": "", "isVirtualBundle": false, "supplier": "Carrefour", "delivery": [], "name": "Pepsi Cola Diet Can 150ml x 12", "id": "663739", "promoBadges": [ { "id": "a72f55da-96e5-4e30-9b9c-d93188d791ca", "placement": "AREA-A", "priority": 1, "seller": "Carrefour", "text": { "boldText": "BESTSELLER", "normalText": "" }, "type": "BestSeller" } ], "productCategoriesHearchi": "Beverages/Soft Drinks/Carbonated Drinks/Cola Zero", "price": { "currency": "SAR", "discount": { "endDate": "8/4/2026, 8:59:00 PM", "formattedValue": "SAR15.00", "minBuyingValue": "15.00", "price": 15, "type": "percentage", "value": 17 }, "formattedValue": "SAR18.00", "minBuyingValue": "18.00", "price": 18 }, "warranty": false, "extraLoyaltyPointsEarned": 0, "size": "150ml x 12", "brand": { "id": "12177", "name": "Pepsi cola" }, "isExpress": false, "loyaltyPoints": 0, "isScalable": false, "isRecommended": false, "deliveryFees": { "freeDeliveryThreshold": 120 }, "unit": { "incrementBy": 1, "itemsPerUnit": 0, "max": 50, "maxToOrder": 50, "min": 1, "size": "150ml x 12", "unitItem": 0, "unitOfMeasure": "pieces" }, "page_type": "group_id", "stock": { "stockLevelStatus": "inStock" }, "isDirectMatch": false, "offers": [ { "brightbites": false, "id": "offer_carrefour_", "internationalShipping": false, "purchaseIndicators": { "SHIPPING": [ "SLOTTED" ] }, "sellerName": "Carrefour", "serviceProductTypes": null, "shippingIndicator": "SLOTTED", "shopId": "0000", "type": "main" } ], "availableVariants": [] } ], "queryCategorizationTree": [], "searchExperimentInfo": { "experimentKey": "hybridSearchFlag", "variationId": "3" }, "sorts": [ { "code": "relevance", "name": "Relevance", "selected": true }, { "code": "price_asc", "name": "Price (lowest first)", "selected": false }, { "code": "price_desc", "name": "Price (highest first)", "selected": false } ], "title": "Soft Drinks", "totalProducts": 455 } } }, "error": { "type": "null" }, "index": { "const": 0, "type": "integer" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "index", "url", "data", "error" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "state": { "const": "completed", "type": "string" }, "stats": { "$ref": "#/components/schemas/JobStats" }, "success": { "const": true, "type": "boolean" } }, "required": [ "job_id", "request_id", "platform", "capability", "state", "success", "results", "billing", "stats" ], "type": "object" }, "CarrefourksaCategoryProductsListExecuteRequest": { "additionalProperties": false, "example": { "capability": "carrefourksa.category.products.list", "input": { "category_id": "FKSA1550000" } }, "properties": { "capability": { "enum": [ "carrefourksa.category.products.list" ], "type": "string" }, "input": { "$ref": "#/components/schemas/CarrefourksaCategoryProductsListInput" }, "network": { "$ref": "#/components/schemas/ExecuteNetwork" }, "timeout_ms": { "description": "Optional request timeout in milliseconds. Values above the capability timeout are rejected.", "maximum": 120000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "type": "object" }, "CarrefourksaCategoryProductsListInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "category_id": { "description": "Leaf category id from carrefourksa.categories.list, e.g. FKSA1550000 (Soft Drinks). Root categories return empty sponsored pages upstream; use leaf ids.", "minLength": 1, "type": "string" }, "limit": { "minimum": 1, "type": "integer" }, "max_records": { "minimum": 1, "type": "integer" }, "page": { "description": "0-based shelf page. Defaults to 0; num_of_pages in the response is the page count.", "minimum": 0, "type": "integer" }, "page_size": { "description": "Products per page. Defaults to 24, capped at 100.", "maximum": 100, "minimum": 1, "type": "integer" }, "sort_by": { "description": "Upstream sort key. Defaults to relevance.", "type": "string" } }, "required": [ "category_id" ], "type": "object" }, "CarrefourksaProductDetailGetCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "carrefourksa.product.detail.get" ], "type": "string" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "carrefourksa" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "results": { "items": { "additionalProperties": false, "properties": { "data": { "description": "Raw capability output. Its shape may evolve with the upstream source; the example is illustrative, not a compatibility guarantee.", "example": { "product": { "@context": "https://schema.org/", "@type": "Product", "barcode": "12000062278", "brand": "food_7up", "breadcrumbs": [ { "aliasName": "FKSA1500000", "id": "FKSA1500000", "level": 1, "name": "Beverages", "name_ar": "المشروبات", "url": "/c/FKSA1500000/" }, { "aliasName": "FKSA1550000", "id": "FKSA1550000", "level": 2, "name": "Soft Drinks", "name_ar": "مشروبات غازية", "url": "/c/FKSA1550000/" }, { "aliasName": "FKSA1550100", "id": "FKSA1550100", "level": 3, "name": "Carbonated Drinks", "name_ar": "المشروبات الغازية والخلاطات", "url": "/c/FKSA1550100/" } ], "description": "", "hasMerchantReturnPolicy": { "@type": "MerchantReturnPolicy", "applicableCountry": "SAR", "merchantReturnDays": 7, "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow" }, "image": "https://cdn.mafrservices.com/sys-master-root/hb8/h77/61617751752734/694540_main.jpg", "name": "7UP Zero Sugar Cans 150ml x12", "offers": { "@type": "Offer", "availability": "https://schema.org/OutOfStock", "itemCondition": "https://schema.org/NewCondition", "priceCurrency": "SAR", "url": "https://www.carrefourksa.com/mafsau/en/p/694540" }, "productCategory": "fksa1500000", "sku": "694540" } } }, "error": { "type": "null" }, "index": { "const": 0, "type": "integer" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "index", "url", "data", "error" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "state": { "const": "completed", "type": "string" }, "stats": { "$ref": "#/components/schemas/JobStats" }, "success": { "const": true, "type": "boolean" } }, "required": [ "job_id", "request_id", "platform", "capability", "state", "success", "results", "billing", "stats" ], "type": "object" }, "CarrefourksaProductDetailGetExecuteRequest": { "additionalProperties": false, "example": { "capability": "carrefourksa.product.detail.get", "input": { "url": "https://www.carrefourksa.com/mafsau/en/lemonade-mixers/7up-zero-sugar-cans-150ml-x12/p/694540" } }, "properties": { "capability": { "enum": [ "carrefourksa.product.detail.get" ], "type": "string" }, "input": { "$ref": "#/components/schemas/CarrefourksaProductDetailGetInput" }, "network": { "$ref": "#/components/schemas/ExecuteNetwork" }, "timeout_ms": { "description": "Optional request timeout in milliseconds. Values above the capability timeout are rejected.", "maximum": 120000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "type": "object" }, "CarrefourksaProductDetailGetInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "limit": { "minimum": 1, "type": "integer" }, "max_records": { "minimum": 1, "type": "integer" }, "url": { "description": "Product page locator: a full PDP URL (https://www.carrefourksa.com/mafsau/en/.../p/694540), a PDP path (/mafsau/en/.../p/694540), or a bare numeric product id (694540, resolved to the canonical /mafsau/en/p/694540 route).", "minLength": 1, "type": "string" } }, "required": [ "url" ], "type": "object" }, "CredentialsRequiredError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "credentials_required", "type": "string" }, "message": { "const": "this capability requires authentication credentials; save them via POST /credentials", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "ExecuteAcceptedResponse": { "additionalProperties": false, "properties": { "capability": { "enum": [ "carrefourksa.categories.list", "carrefourksa.category.products.list", "carrefourksa.product.detail.get" ], "type": "string" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "carrefourksa" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "state": { "const": "queued", "type": "string" } }, "required": [ "job_id", "request_id", "platform", "capability", "state" ], "type": "object" }, "ExecuteNetwork": { "additionalProperties": false, "properties": { "session_id": { "description": "Optional explicit session identifier.", "minLength": 1, "type": "string" }, "session_key": { "description": "Optional stable key used to derive a reusable session.", "minLength": 1, "type": "string" }, "sticky": { "description": "Whether the request should reuse the resolved session.", "type": "boolean" } }, "type": "object" }, "ExecuteReplayResponse": { "additionalProperties": false, "description": "Replayed response matching the original job's current state (completed, failed, or pending).", "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "carrefourksa.categories.list", "carrefourksa.category.products.list", "carrefourksa.product.detail.get" ], "type": "string" }, "error": {}, "idempotent_replay": { "const": true, "type": "boolean" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "carrefourksa" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "results": {}, "state": { "enum": [ "queued", "running", "retrying", "completed", "failed" ], "type": "string" }, "stats": {}, "success": { "type": "boolean" } }, "required": [ "job_id", "request_id", "platform", "capability", "state", "idempotent_replay" ], "type": "object" }, "IdempotencyConflictError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "idempotency_conflict", "type": "string" }, "message": { "const": "idempotency key has already been used for a different request", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "InternalError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "internal_error", "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "JobBilling": { "additionalProperties": false, "properties": { "credits_charged": { "anyOf": [ { "description": "Actual credits charged. Null only when retained historical facts cannot establish the amount.", "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "credits_per_unit": { "anyOf": [ { "description": "Snapshotted price for one billed unit. Zero only for historical free work; null when unknown.", "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "model": { "enum": [ "per_request", "per_record", "free", "unknown" ], "type": "string" }, "pricing": { "additionalProperties": false, "properties": { "rule_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ] }, "scope": { "anyOf": [ { "enum": [ "module", "platform", "capability" ], "type": "string" }, { "type": "null" } ] }, "source": { "enum": [ "manifest", "price_book" ], "type": "string" }, "version": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ] } }, "required": [ "source", "scope", "version", "rule_id" ], "type": "object" }, "units": { "anyOf": [ { "description": "Billed units under the stated model. Null when units do not apply or cannot be established.", "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "model", "units", "credits_per_unit", "credits_charged", "pricing" ], "type": "object" }, "JobErrorObject": { "additionalProperties": false, "properties": { "code": { "description": "Machine-readable error code (e.g. forbidden, not_found, invalid_input, upstream_timeout, upstream_error).", "type": "string" }, "message": { "description": "Human-readable error description.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "JobFailedResponse": { "additionalProperties": false, "properties": { "capability": { "enum": [ "carrefourksa.categories.list", "carrefourksa.category.products.list", "carrefourksa.product.detail.get" ], "type": "string" }, "error": { "$ref": "#/components/schemas/JobErrorObject" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "carrefourksa" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "results": { "type": "null" }, "state": { "const": "failed", "type": "string" }, "stats": { "type": "null" }, "success": { "const": false, "type": "boolean" } }, "required": [ "job_id", "request_id", "platform", "capability", "state", "success", "error", "results", "stats" ], "type": "object" }, "JobPendingResponse": { "additionalProperties": false, "properties": { "capability": { "enum": [ "carrefourksa.categories.list", "carrefourksa.category.products.list", "carrefourksa.product.detail.get" ], "type": "string" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "carrefourksa" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "state": { "enum": [ "queued", "running", "retrying" ], "type": "string" } }, "required": [ "job_id", "request_id", "platform", "capability", "state" ], "type": "object" }, "JobStats": { "additionalProperties": false, "properties": { "duration_ms": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "failed": { "const": 0, "type": "integer" }, "passed": { "const": 1, "type": "integer" }, "total": { "const": 1, "type": "integer" } }, "required": [ "total", "passed", "failed", "duration_ms" ], "type": "object" }, "NotFoundError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "not_found", "type": "string" }, "message": { "const": "job not found", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "QuotaError": { "oneOf": [ { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "account_inactive", "type": "string" }, "message": { "const": "an active paid account is required", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "quota_exhausted", "type": "string" }, "message": { "const": "request quota exhausted for current billing period", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } ] }, "RateLimitError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "rate_limited", "type": "string" }, "message": { "const": "rate limit exceeded", "type": "string" }, "retry_after_ms": { "description": "Milliseconds until the rolling window resets enough to retry. The `retry-after` response header carries the same value rounded up to seconds.", "minimum": 0, "type": "integer" } }, "required": [ "code", "message", "retry_after_ms" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "UnauthorizedError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "unauthorized", "type": "string" }, "message": { "enum": [ "authentication required", "invalid bearer token", "missing bearer token" ], "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "ValidationErrors": { "additionalProperties": false, "properties": { "errors": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" } }, "required": [ "errors" ], "type": "object" } }, "securitySchemes": { "BearerAuth": { "bearerFormat": "API Key", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Scraper for Carrefour Saudi Arabia (Majid Al Futtaim React-web backend): the full category tree, leaf category shelf listings with SAR prices and discounts, and product detail pages with JSON-LD records, breadcrumbs, and barcodes.\nThis spec includes only the live `Carrefour KSA` capabilities exposed by Upscrape.\nExecution uses the generic `POST /execute` endpoint and job polling uses `GET /jobs/{id}`.\nSupported capabilities: `carrefourksa.categories.list`, `carrefourksa.category.products.list`, `carrefourksa.product.detail.get`\n## Rate limiting\n\nRequests are rate-limited per API key at **1200 requests per minute** on a rolling window. Every response includes `x-ratelimit-limit`, `x-ratelimit-remaining`, and `x-ratelimit-reset` (Unix ms) headers so clients can self-pace. When the limit is exceeded the API returns `429` with a `rate_limited` error body and a `retry-after` header in seconds plus a `retry_after_ms` field on the body for finer-grained backoff.", "title": "Carrefour KSA API", "version": "v0.1.2" }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "openapi": "3.1.0", "paths": { "/execute": { "post": { "description": "All executions are asynchronous. Submit a capability-specific payload to `POST /execute`, then poll the returned `job_id`.", "operationId": "carrefourksa_execute", "parameters": [ { "description": "Optional idempotency key. Reusing the same key with the same request replays the original job.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } }, { "description": "Request synchronous completion. Use `wait=N` to hold the connection up to N seconds (max 300). If the job completes within the window, the response is `200` with full results (same shape as `GET /jobs/{id}`). If not, the response is the normal `202` with a `job_id` for polling. Omit this header for default asynchronous behavior.", "examples": { "wait30": { "summary": "Wait up to 30 seconds", "value": "wait=30" }, "wait5": { "summary": "Wait up to 5 seconds", "value": "wait=5" } }, "in": "header", "name": "Prefer", "required": false, "schema": { "example": "wait=30", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "capability": "carrefourksa.categories.list", "input": {} }, "schema": { "discriminator": { "mapping": { "carrefourksa.categories.list": "#/components/schemas/CarrefourksaCategoriesListExecuteRequest", "carrefourksa.category.products.list": "#/components/schemas/CarrefourksaCategoryProductsListExecuteRequest", "carrefourksa.product.detail.get": "#/components/schemas/CarrefourksaProductDetailGetExecuteRequest" }, "propertyName": "capability" }, "oneOf": [ { "$ref": "#/components/schemas/CarrefourksaCategoriesListExecuteRequest" }, { "$ref": "#/components/schemas/CarrefourksaCategoryProductsListExecuteRequest" }, { "$ref": "#/components/schemas/CarrefourksaProductDetailGetExecuteRequest" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CarrefourksaCategoriesListCompletedJob" }, { "$ref": "#/components/schemas/CarrefourksaCategoryProductsListCompletedJob" }, { "$ref": "#/components/schemas/CarrefourksaProductDetailGetCompletedJob" }, { "$ref": "#/components/schemas/ExecuteReplayResponse" }, { "$ref": "#/components/schemas/JobFailedResponse" } ] } } }, "description": "Job completed within the `Prefer: wait` window, or existing job replayed via idempotency key.", "headers": { "Preference-Applied": { "description": "Present when the server honored the `Prefer: wait` preference.", "schema": { "example": "wait=30", "type": "string" } }, "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "202": { "content": { "application/json": { "example": { "capability": "carrefourksa.categories.list", "job_id": "00000000-0000-0000-0000-000000000001", "platform": "carrefourksa", "request_id": "00000000-0000-0000-0000-000000000001", "state": "queued", "success": false }, "schema": { "$ref": "#/components/schemas/ExecuteAcceptedResponse" } } }, "description": "Job accepted and queued.", "headers": { "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaError" } } }, "description": "The authenticated account cannot execute the request." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyConflictError" } } }, "description": "Idempotency conflict" }, "422": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ValidationErrors" }, { "$ref": "#/components/schemas/CredentialsRequiredError" } ] } } }, "description": "The request body failed validation." }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "rate limit exceeded", "retry_after_ms": 4200 } }, "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-API-key rate limit has been exceeded. Clients should back off until `retry_after_ms` has elapsed (or `retry-after` seconds).", "headers": { "retry-after": { "description": "Seconds until the client may retry (ceiling of `retry_after_ms`).", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } }, "description": "Unexpected server error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Queue a Carrefour KSA capability run", "tags": [ "Execution" ] } }, "/jobs/{id}": { "get": { "description": "Get job status and result", "operationId": "carrefourksa_getJob", "parameters": [ { "description": "The job ID returned by `POST /execute`.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CarrefourksaCategoriesListCompletedJob" }, { "$ref": "#/components/schemas/CarrefourksaCategoryProductsListCompletedJob" }, { "$ref": "#/components/schemas/CarrefourksaProductDetailGetCompletedJob" }, { "$ref": "#/components/schemas/JobFailedResponse" } ] } } }, "description": "Completed or terminal job state.", "headers": { "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "202": { "content": { "application/json": { "example": { "capability": "carrefourksa.categories.list", "job_id": "00000000-0000-0000-0000-000000000001", "platform": "carrefourksa", "request_id": "00000000-0000-0000-0000-000000000001", "state": "running", "success": false }, "schema": { "$ref": "#/components/schemas/JobPendingResponse" } } }, "description": "Job is still queued, running, or retrying.", "headers": { "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } }, "description": "Job not found" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "rate limit exceeded", "retry_after_ms": 4200 } }, "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-API-key rate limit has been exceeded. Clients should back off until `retry_after_ms` has elapsed (or `retry-after` seconds).", "headers": { "retry-after": { "description": "Seconds until the client may retry (ceiling of `retry_after_ms`).", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Poll a Carrefour KSA job", "tags": [ "Jobs" ] } }, "/jobs/{id}/result": { "get": { "description": "Backward-compatible alias for `/jobs/{id}`.", "operationId": "carrefourksa_getJobResult", "parameters": [ { "description": "The job ID returned by `POST /execute`.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CarrefourksaCategoriesListCompletedJob" }, { "$ref": "#/components/schemas/CarrefourksaCategoryProductsListCompletedJob" }, { "$ref": "#/components/schemas/CarrefourksaProductDetailGetCompletedJob" }, { "$ref": "#/components/schemas/JobFailedResponse" } ] } } }, "description": "Completed or terminal job state.", "headers": { "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "202": { "content": { "application/json": { "example": { "capability": "carrefourksa.categories.list", "job_id": "00000000-0000-0000-0000-000000000001", "platform": "carrefourksa", "request_id": "00000000-0000-0000-0000-000000000001", "state": "running", "success": false }, "schema": { "$ref": "#/components/schemas/JobPendingResponse" } } }, "description": "Job is still queued, running, or retrying.", "headers": { "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } }, "description": "Job not found" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "rate limit exceeded", "retry_after_ms": 4200 } }, "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-API-key rate limit has been exceeded. Clients should back off until `retry_after_ms` has elapsed (or `retry-after` seconds).", "headers": { "retry-after": { "description": "Seconds until the client may retry (ceiling of `retry_after_ms`).", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Poll a Carrefour KSA job", "tags": [ "Jobs" ] } } }, "servers": [ { "url": "https://data.upscrape.com" } ], "tags": [ { "description": "Submit asynchronous capability runs.", "name": "Execution" }, { "description": "Poll queued jobs for status and results.", "name": "Jobs" } ] }