{
    "openapi": "3.1.0",
    "info": {
        "title": "Bestshopping Cashback — IT, DE, FR",
        "version": "1.1.0",
        "description": "Search public merchant information and prepare personal cashback links. The USER must click go.html in their shopping browser with tracking cookies allowed and AdBlock disabled. API calls never activate cashback or visit merchants. Exact rates are on the official merchant cashback page. Use the Bestshopping account market; merchant IDs and nicknames are market-specific.",
        "termsOfService": "https://it.bestshopping.com/condizioni.html",
        "contact": {
            "name": "Bestshopping",
            "url": "https://it.bestshopping.com/contatti.html"
        }
    },
    "servers": [
        {
            "url": "https://it.bestshopping.com/ai"
        }
    ],
    "security": [],
    "paths": {
        "/global-search.php": {
            "get": {
                "operationId": "search_merchants",
                "summary": "Search the current Bestshopping merchant catalog for the selected account market by name, domain or ID. Distinguishes online cashback, gift cards and top-ups. Does not activate tracking or visit merchants.",
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "market": {
                                            "enum": [
                                                "it",
                                                "de",
                                                "fr"
                                            ],
                                            "type": "string"
                                        },
                                        "query": {
                                            "type": "string"
                                        },
                                        "total": {
                                            "type": "integer"
                                        },
                                        "offset": {
                                            "type": "integer"
                                        },
                                        "next_offset": {
                                            "type": [
                                                "integer",
                                                "null"
                                            ]
                                        },
                                        "merchants": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "merchant_id": {
                                                        "type": "integer"
                                                    },
                                                    "name": {
                                                        "type": "string"
                                                    },
                                                    "market": {
                                                        "enum": [
                                                            "it",
                                                            "de",
                                                            "fr"
                                                        ],
                                                        "type": "string"
                                                    },
                                                    "kind": {
                                                        "type": "string",
                                                        "enum": [
                                                            "online_cashback",
                                                            "gift_card",
                                                            "top_up"
                                                        ]
                                                    },
                                                    "merchant_domain": {
                                                        "type": [
                                                            "string",
                                                            "null"
                                                        ]
                                                    },
                                                    "cashback_page_url": {
                                                        "type": "string",
                                                        "format": "uri"
                                                    },
                                                    "tracking_supported": {
                                                        "type": "boolean"
                                                    }
                                                },
                                                "required": [
                                                    "merchant_id",
                                                    "name",
                                                    "market",
                                                    "kind",
                                                    "merchant_domain",
                                                    "cashback_page_url",
                                                    "tracking_supported"
                                                ],
                                                "additionalProperties": false
                                            }
                                        },
                                        "checked_at": {
                                            "type": "string",
                                            "format": "date-time"
                                        }
                                    },
                                    "required": [
                                        "market",
                                        "query",
                                        "total",
                                        "offset",
                                        "next_offset",
                                        "merchants",
                                        "checked_at"
                                    ],
                                    "additionalProperties": false
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Invalid arguments, unavailable merchant or service error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "code": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                }
                                            },
                                            "required": [
                                                "code",
                                                "message"
                                            ],
                                            "additionalProperties": false
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ],
                                    "additionalProperties": false
                                }
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "query",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 150,
                            "description": "Merchant name, website domain or ID. Empty string lists the catalog."
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 20,
                            "default": 10
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 10000,
                            "default": 0
                        }
                    },
                    {
                        "name": "market",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "it",
                                "de",
                                "fr"
                            ],
                            "description": "Bestshopping ACCOUNT market: it (Italy), de (Germany), fr (France). Ask the user if missing or ambiguous; never infer it from language or reuse IDs across markets."
                        }
                    }
                ]
            }
        },
        "/global-merchant.php": {
            "get": {
                "operationId": "get_merchant",
                "summary": "Read current public merchant information, cashback conditions and browser tracking rules. Exact cashback rates must be checked on the returned Bestshopping page; this tool does not provide a personalized quote or access an account.",
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "merchant": {
                                            "type": "object",
                                            "properties": {
                                                "merchant_id": {
                                                    "type": "integer"
                                                },
                                                "name": {
                                                    "type": "string"
                                                },
                                                "market": {
                                                    "enum": [
                                                        "it",
                                                        "de",
                                                        "fr"
                                                    ],
                                                    "type": "string"
                                                },
                                                "kind": {
                                                    "type": "string",
                                                    "enum": [
                                                        "online_cashback",
                                                        "gift_card",
                                                        "top_up"
                                                    ]
                                                },
                                                "merchant_domain": {
                                                    "type": [
                                                        "string",
                                                        "null"
                                                    ]
                                                },
                                                "cashback_page_url": {
                                                    "type": "string",
                                                    "format": "uri"
                                                },
                                                "tracking_supported": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "required": [
                                                "merchant_id",
                                                "name",
                                                "market",
                                                "kind",
                                                "merchant_domain",
                                                "cashback_page_url",
                                                "tracking_supported"
                                            ],
                                            "additionalProperties": false
                                        },
                                        "description": {
                                            "type": "string"
                                        },
                                        "conditions": {
                                            "type": "string"
                                        },
                                        "cashback_rate": {
                                            "type": "null"
                                        },
                                        "rate_notice": {
                                            "type": "string"
                                        },
                                        "tracking_rules": {
                                            "type": "object",
                                            "properties": {
                                                "user_click_required": {
                                                    "const": true,
                                                    "type": "boolean"
                                                },
                                                "browser_required": {
                                                    "const": true,
                                                    "type": "boolean"
                                                },
                                                "tracking_activated_by_tool": {
                                                    "const": false,
                                                    "type": "boolean"
                                                },
                                                "instructions": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                }
                                            },
                                            "required": [
                                                "user_click_required",
                                                "browser_required",
                                                "tracking_activated_by_tool",
                                                "instructions"
                                            ],
                                            "additionalProperties": false
                                        },
                                        "checked_at": {
                                            "type": "string",
                                            "format": "date-time"
                                        }
                                    },
                                    "required": [
                                        "merchant",
                                        "description",
                                        "conditions",
                                        "cashback_rate",
                                        "rate_notice",
                                        "tracking_rules",
                                        "checked_at"
                                    ],
                                    "additionalProperties": false
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Invalid arguments, unavailable merchant or service error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "code": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                }
                                            },
                                            "required": [
                                                "code",
                                                "message"
                                            ],
                                            "additionalProperties": false
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ],
                                    "additionalProperties": false
                                }
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "merchant_id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "description": "Merchant ID returned by search_merchants. Never guess or reuse IDs from another market."
                        }
                    },
                    {
                        "name": "market",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "it",
                                "de",
                                "fr"
                            ],
                            "description": "Bestshopping ACCOUNT market: it (Italy), de (Germany), fr (France). Ask the user if missing or ambiguous; never infer it from language or reuse IDs across markets."
                        }
                    }
                ]
            }
        },
        "/global-prepare.php": {
            "post": {
                "operationId": "prepare_cashback_link",
                "summary": "Prepare a personal Bestshopping go.html link using an existing recipient nickname and a verified online cashback merchant. Does NOT activate cashback, follow the URL, set merchant cookies, register a purchase click or make a purchase. Show the returned link and tell the USER to click it in their shopping browser, allow tracking cookies and disable AdBlock. Never open or prefetch the link on the server. Never say cashback is already activated.",
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "const": "link_prepared",
                                            "type": "string"
                                        },
                                        "tracking_activated": {
                                            "const": false,
                                            "type": "boolean"
                                        },
                                        "user_click_required": {
                                            "const": true,
                                            "type": "boolean"
                                        },
                                        "activation_url": {
                                            "type": "string",
                                            "format": "uri"
                                        },
                                        "merchant": {
                                            "type": "object",
                                            "properties": {
                                                "merchant_id": {
                                                    "type": "integer"
                                                },
                                                "name": {
                                                    "type": "string"
                                                },
                                                "market": {
                                                    "enum": [
                                                        "it",
                                                        "de",
                                                        "fr"
                                                    ],
                                                    "type": "string"
                                                },
                                                "kind": {
                                                    "type": "string",
                                                    "enum": [
                                                        "online_cashback",
                                                        "gift_card",
                                                        "top_up"
                                                    ]
                                                },
                                                "merchant_domain": {
                                                    "type": [
                                                        "string",
                                                        "null"
                                                    ]
                                                },
                                                "cashback_page_url": {
                                                    "type": "string",
                                                    "format": "uri"
                                                },
                                                "tracking_supported": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "required": [
                                                "merchant_id",
                                                "name",
                                                "market",
                                                "kind",
                                                "merchant_domain",
                                                "cashback_page_url",
                                                "tracking_supported"
                                            ],
                                            "additionalProperties": false
                                        },
                                        "conditions": {
                                            "type": "string"
                                        },
                                        "tracking_rules": {
                                            "type": "object",
                                            "properties": {
                                                "user_click_required": {
                                                    "const": true,
                                                    "type": "boolean"
                                                },
                                                "browser_required": {
                                                    "const": true,
                                                    "type": "boolean"
                                                },
                                                "tracking_activated_by_tool": {
                                                    "const": false,
                                                    "type": "boolean"
                                                },
                                                "instructions": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                }
                                            },
                                            "required": [
                                                "user_click_required",
                                                "browser_required",
                                                "tracking_activated_by_tool",
                                                "instructions"
                                            ],
                                            "additionalProperties": false
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "checked_at": {
                                            "type": "string",
                                            "format": "date-time"
                                        }
                                    },
                                    "required": [
                                        "status",
                                        "tracking_activated",
                                        "user_click_required",
                                        "activation_url",
                                        "merchant",
                                        "conditions",
                                        "tracking_rules",
                                        "message",
                                        "checked_at"
                                    ],
                                    "additionalProperties": false
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Invalid arguments, unavailable merchant or service error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "code": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                }
                                            },
                                            "required": [
                                                "code",
                                                "message"
                                            ],
                                            "additionalProperties": false
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ],
                                    "additionalProperties": false
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "merchant_id": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "Merchant ID returned by search_merchants. Never guess or reuse IDs from another market."
                                    },
                                    "nickname": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 80,
                                        "description": "Exact nickname for the selected Bestshopping market explicitly supplied by the user. Ask if missing. Never request a password."
                                    },
                                    "market": {
                                        "type": "string",
                                        "enum": [
                                            "it",
                                            "de",
                                            "fr"
                                        ],
                                        "description": "Bestshopping ACCOUNT market: it (Italy), de (Germany), fr (France). Ask the user if missing or ambiguous; never infer it from language or reuse IDs across markets."
                                    }
                                },
                                "required": [
                                    "merchant_id",
                                    "nickname",
                                    "market"
                                ],
                                "additionalProperties": false
                            }
                        }
                    }
                }
            }
        },
        "/global-markets.php": {
            "get": {
                "operationId": "list_markets",
                "summary": "List supported Bestshopping markets",
                "responses": {
                    "200": {
                        "description": "Supported account markets",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "markets": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "market": {
                                                        "type": "string",
                                                        "enum": [
                                                            "it",
                                                            "de",
                                                            "fr"
                                                        ]
                                                    },
                                                    "name": {
                                                        "type": "string"
                                                    },
                                                    "website_url": {
                                                        "type": "string",
                                                        "format": "uri"
                                                    }
                                                },
                                                "required": [
                                                    "market",
                                                    "name",
                                                    "website_url"
                                                ],
                                                "additionalProperties": false
                                            }
                                        },
                                        "selection_rule": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "markets",
                                        "selection_rule"
                                    ],
                                    "additionalProperties": false
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}