# Reference ## Demande d'annonces sponsorisées ## POST /v1/\_deliver > Deliver contextual ads ```json {"openapi":"3.0.0","info":{"title":"veasybl.io","version":"1.0.7"},"servers":[{"url":"https://[retailer-endpoint]"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"DeliverRequest":{"type":"object","properties":{"visitor":{"type":"string","description":"Unique identifier for the site visitor session."},"alias":{"type":"string","description":"Hashed, pseudonymous customer ID for analytics, if available."},"placement":{"type":"string","enum":["search","plp","pdp","hub","home"],"description":"Type of page where the banner/request is shown. Use \"search\" for search results, \"plp\" for product listing/collection pages, \"pdp\" for product detail pages, \"hub\" for editorial/grouping hubs, and \"home\" for homepages."},"slots":{"description":"List of ad slot requests, describing the slot type and desired maximum number of banners per slot.","type":"array","items":{"$ref":"#/components/schemas/SlotRequest"}},"search_terms":{"type":"string","description":"The search query terms entered by the user, used to refine and personalize content or offers."},"category":{"type":"string","description":"Identifier for the current category page, used to contextualize the request on a category/collection listing."},"product":{"description":"Information about the current product page, if viewing a product detail. Populated when placement is \"pdp\".","allOf":[{"$ref":"#/components/schemas/ProductPage"}]},"listed_products":{"description":"Set of products listed on the current page (for example, all products shown on a category page). Used to exclude those products from banners or offers.","allOf":[{"$ref":"#/components/schemas/ListedProducts"}]},"extra":{"description":"Additional contextual or technical information about the request, such as device type, operating system, preview flags, etc.","allOf":[{"$ref":"#/components/schemas/DeliverRequestExtra"}]}},"required":["placement","slots"]},"SlotRequest":{"type":"object","properties":{"id":{"type":"string","description":"A unique identifier for the ad slot where content will be delivered."},"max":{"type":"number","default":1,"description":"Maximum number of ads or content items to display in this slot. Defaults to 1 if not specified."}},"required":["id"]},"ProductPage":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the product, such as an SKU."},"categories":{"description":"List of category identifiers the product belongs to, ordered from the top-level category to the most specific subcategory.","type":"array","items":{"type":"string"}},"offer_id":{"type":"string","description":"Unique identifier for the associated offer, if available."},"seller_id":{"type":"string","description":"Unique identifier for the seller offering this product, if available."},"brand":{"type":"string","description":"Brand name or unique identifier for the product's brand."},"rating":{"type":"number","description":"Average user rating for the product, based on a star system."},"reviews":{"type":"number","description":"Total number of user reviews for the product."},"price":{"type":"number","description":"Current price of the product, in the store’s default currency."},"availability":{"type":"string","enum":["in stock","in store","out of stock"],"description":"Availability status of the product. Possible values: \"in stock\", \"in store\", or \"out of stock\"."}},"required":["id","categories"]},"ListedProducts":{"type":"object","properties":{"ids":{"description":"Array of product identifiers (SKUs) currently displayed on the page, listed in their visible order.","type":"array","items":{"type":"string"}},"page":{"type":"number","default":1,"description":"Current page number for the product list in paginated results. Defaults to the first page if not specified."},"sort":{"type":"string","description":"Specifies the sorting method applied to the product list (e.g., \"price_asc\" for ascending prices, \"rating_desc\" for top-rated)."},"total":{"type":"number","description":"Total number of products available for the current selection or filters, regardless of pagination."},"filters":{"description":"Array of active filter criteria applied to the product list. Each filter describes a condition (such as color, price, or rating) currently used on the page.","type":"array","items":{"$ref":"#/components/schemas/ListedProductsFilter"}}},"required":["ids"]},"ListedProductsFilter":{"type":"object","properties":{"code":{"type":"string","description":"The unique key or name identifying the filter applied (e.g., color, price, rating, availability)."},"op":{"type":"string","enum":["eq","in","lt","lte","gt","gte"],"description":"Operator used for filtering. \"eq\" for exact match, \"in\" for inclusion in a list, \"lt\"/\"lte\" for less than/less than or equal, and \"gt\"/\"gte\" for greater than/greater than or equal comparisons."},"value":{"type":"object","description":"The value or values used in the filter condition. Can be a single value or an array, depending on the operator."}},"required":["code","op","value"]},"DeliverRequestExtra":{"type":"object","properties":{"device":{"type":"string","enum":["mobile","desktop","tablet","app"],"description":"Type of device making the request. Typical values include \"mobile\", \"desktop\", \"tablet\", or \"app\". Use \"app\" for requests from native applications, and \"mobile\" for mobile web browsers."},"store":{"type":"string","description":"Identifier of the selected or geo-targeted physical store. Used for tailoring content to a specific in-store location."},"url":{"type":"string","description":"Relative URL path of the current page, useful for contextual targeting or analytics."},"segments":{"description":"List of audience segments (DMP: Data Management Platform segments) attributed to the visitor, used for audience targeting or personalization.","type":"array","items":{"type":"string"}},"search_hint":{"type":"string","description":"Curated search terms or topics relevant to the current context, for example highlighting a specific keyword or product theme."},"vz_preview":{"type":"string","description":"Identifier of a campaign to be previewed, typically used by internal tools or during QA and preview environments."}}},"DeliverResponse":{"type":"object","properties":{"slots":{"description":"Array of slot responses, each representing one ad slot with its delivered items.","type":"array","items":{"$ref":"#/components/schemas/SlotResponse"}}},"required":["slots"]},"SlotResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the ad slot. Corresponds to the requested slot ID."},"max":{"type":"number","description":"Maximum number of ads that can be filled in this slot, as configured in the request."},"fill":{"type":"number","default":0,"description":"Number of ads returned for this slot in the current response. Indicates actual fill compared to the max allowed."},"products":{"description":"List of sponsored product items delivered for this slot.","type":"array","items":{"$ref":"#/components/schemas/ProductItem"}},"banners":{"description":"List of sponsored banner items delivered for this slot.","type":"array","items":{"$ref":"#/components/schemas/BannerItem"}},"creative":{"description":"List of sponsored display items delivered for this slot.","allOf":[{"$ref":"#/components/schemas/CreativeItem"}]}},"required":["id","max","fill"]},"ProductItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique product identifier (SKU or similar)."},"oid":{"type":"string","description":"Unique identifier of the related offer, if applicable."},"title":{"type":"string","description":"Full product title or name as displayed in the store."},"brand":{"type":"string","description":"Brand or manufacturer of the product."},"link":{"type":"string","description":"Direct URL to the product details page in the storefront."},"image_link":{"type":"string","description":"URL pointing to the main image of the product."},"price":{"type":"number","description":"Current price of the product (in marketplace’s currency)."},"seller":{"type":"string","description":"Marketplace seller or store providing the product."},"team":{"type":"string","description":"Name of the advertiser's team associated with this product listing."},"index":{"type":"number","description":"Position or rank of the product within a recommendation or search result list."},"beacon":{"type":"string","description":"Tracking beacon or unique token for product attribution and analytics."}},"required":["id","beacon"]},"BannerItem":{"type":"object","properties":{"image":{"type":"string","description":"URL of the main banner image to display."},"image_picture":{"description":"Responsive images for use in HTML tags, allowing appropriate image selection based on device or resolution.","type":"array","items":{"$ref":"#/components/schemas/ImagePicture"}},"image_width":{"type":"number","description":"Width of the main banner image, in pixels."},"image_height":{"type":"number","description":"Height of the main banner image, in pixels."},"image_alt_text":{"type":"string","description":"Alternative text for the main image, for accessibility or when the image cannot be loaded."},"logo_alt_text":{"type":"string","description":"Alternative text for the logo image, helps with accessibility."},"link":{"type":"string","description":"URL the banner should link to, such as a product or promotional page."},"link_text":{"type":"string","description":"Text to display for the call-to-action (CTA) link."},"headline":{"type":"string","description":"Headline or main text displayed within the banner."},"text_color":{"type":"string","description":"Color of the headline text, specified as a hex code."},"background_image":{"type":"string","description":"URL of the background image for the banner."},"background_color":{"type":"string","description":"Background color of the banner, specified as a hex code."},"team":{"type":"string","description":"Name of the advertiser team responsible for this banner."},"index":{"type":"number","description":"Position or order index of the banner within a list."},"beacon":{"type":"string","description":"Unique tracking beacon for banner analytics."}}},"ImagePicture":{"type":"object","properties":{"type":{"type":"string","description":"MIME type of the image resource, used for the \"type\" attribute in an HTML tag (e.g., \"image/webp\" or \"image/jpeg\")."},"srcset":{"type":"string","description":"Comma-separated list of image URLs and their display densities, intended for the \"srcset\" attribute in the tag to support responsive and retina images."}},"required":["type","srcset"]},"CreativeItem":{"type":"object","properties":{"headline":{"type":"string","description":"Headline or main promotional message displayed in the creative."},"text_link":{"type":"string","description":"Label for the primary call-to-action button or link."},"href_link":{"type":"string","description":"URL to which the creative directs users when they click the call-to-action."},"brand_image":{"type":"string","description":"URL of the logo or brand image shown in the creative."},"background_image":{"type":"string","description":"URL for the creative's background image."},"video_file":{"type":"string","description":"URL to the main video file for video creatives, if provided."},"video_thumb":{"type":"string","description":"URL of the thumbnail image shown before the video plays."},"video_in_loop":{"type":"boolean","description":"Indicates if the video should play in a continuous loop."},"aspect_ratio":{"type":"string","description":"Aspect ratio of the creative or video, such as \"16:9\" or \"9:16\"."},"auto_slide":{"type":"boolean","description":"If true, enables automatic sliding for the product carousel."},"team":{"type":"string","description":"Name of the advertiser team or agency responsible for this creative."},"beacon":{"type":"string","description":"Encoded string for tracking impressions and attribution."}}}}},"paths":{"/v1/_deliver":{"post":{"operationId":"apiDeliver","parameters":[{"name":"x-retailer-id","in":"header","style":"simple","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverRequest"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverResponse"}}}},"400":{"description":"Bad Request."},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."}},"summary":"Deliver contextual ads","tags":["Docs"]}}}} ``` {% hint style="info" %} Pour demander des annonces, vous devez fournir un **contexte**. Un **contexte** correspond à un ensemble de filtres que les campagnes doivent satisfaire avant d'être diffusées. Il garantit ainsi que seules les annonces pertinentes sont affichées. {% endhint %} {% tabs %} {% tab title="EXEMPLE" %} ```json POST https://[retailer-endpoint]/v1/_deliver x-api-key: [your_api_key_goes_here] x-retailer-id: [your_retailer_id_goes_here] Content-Type: application/json { "visitor": "string", "alias": "string", "placement": "plp", "slots": [ { "id": "sp", "max": 3 } ], "category": "catId1", "listed_products": { "ids": ["id1","id2","id3","id4","id5","id6","id7"], "page": 1, "sort": "relevance", "total": 135 }, "extra": { "device": "mobile", "os": "ios", "url": "/cat-pages/cat-corresponding-to-cat-id-1/", "store": "141", "vz_preview":"xiLvzAwJ9k6K1IrEKfIE" } } ``` {% endtab %} {% tab title="EXEMPLE SEARCH" %} ```json POST https://[retailer-endpoint]/v1/_deliver x-api-key: [your_api_key_goes_here] x-retailer-id: [your_retailer_id_goes_here] Content-Type: application/json { "placement": "search", "slots": [ { "id": "sp", "max": 6 } ], "search_terms": "your search keywords", "listed_products": { "ids": ["id1","id2","id3","id4","id5","id6","id7"], "page": 2, "sort": "price_asc", "total": 289 }, } ``` {% endtab %} {% tab title="EXEMPLE PDP" %} ```json POST https://[retailer-endpoint]/v1/_deliver x-api-key: [your_api_key_goes_here] x-retailer-id: [your_retailer_id_goes_here] Content-Type: application/json { "visitor": "_aLpmZsOAXqbH219SO0Nnf", "placement": "pdp", "slots": [ { "id": "slider", "max": 10 } ], "product": { "id": "sku910d", "categories": ["c290", "c2902", "c29023"], }, "extra": { "device": "desktop" } } ``` {% endtab %} {% tab title="EXEMPLE HOME" %} ```json POST https://[retailer-endpoint]/v1/_deliver x-api-key: [your_api_key_goes_here] x-retailer-id: [your_retailer_id_goes_here] Content-Type: application/json { "placement": "home", "slots": [ { "id": "ban-970x250" }, { "id": "slider", "max": 10 } ], } ``` {% endtab %} {% endtabs %} ## Enregistrement des évènements ## POST /v1/\_event > Track events (display, view, click) ```json {"openapi":"3.0.0","info":{"title":"veasybl.io","version":"1.0.7"},"servers":[{"url":"https://[retailer-endpoint]"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"EventRequest":{"type":"object","properties":{"display":{"description":"Array of event beacons associated with ads that were displayed to the user. Each beacon is a unique, encoded token representing a particular ad impression.","type":"array","items":{"type":"string"}},"view":{"description":"Array of event beacons for ads that were visible within the user’s viewport. Use this to track which ad impressions were actually viewed.","type":"array","items":{"type":"string"}},"click":{"description":"Array of event beacons for ads that were clicked by the user. Each token corresponds to a unique click event on an ad creative.","type":"array","items":{"type":"string"}}}}}},"paths":{"/v1/_event":{"post":{"operationId":"apiEvent","parameters":[{"name":"x-retailer-id","in":"header","style":"simple","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventRequest"}}}},"responses":{"204":{"description":"No Content."},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."}},"summary":"Track events (display, view, click)","tags":["Docs"]}}}} ``` ### Liste des Événements Suivis
eventIndicateurDescription
displayAffichageL'annonce a été chargée
viewVueL'annonce est devenue visible
clickClicL’utilisateur a cliqué sur l'annonce
view_s2Vue 2 secondes (vidéo)Vidéo vue pendant 2 secondes
view_s5Vue 5 secondes (vidéo)Vidéo vue pendant 5 secondes
view_q1Premier quartile (vidéo)25 % de la vidéo ont été vus
view_mMilieu (vidéo)La moitié de la vidéo a été vue
view_q3Troisième quartile (vidéo)75 % de la vidéo ont été vus
view_fVue complète (vidéo)100 % de la vidéo ont été vus
unmuteActivation du son (vidéo)Le son a été (ré)activé par l’utilisateur
{% tabs %} {% tab title="EXEMPLE" %} ```json POST https://[retailer-endpoint]/v1/_event x-api-key: [your_api_key_goes_here] x-retailer-id: [your_retailer_id_goes_here] Content-Type: application/json { "display": [ "tYdH1JZroRdc01NHb5o-b0T9b9kVBHnYTfy1OXoANGhEweHLwIJEN-1W", "qSUaO_EYpgShat8p8-bm_wiskKYotoBDbwMVU-8li2lO8KC-J8nFyvB21u" ] } ``` {% endtab %} {% endtabs %} ## Enregistrement des ventes ## POST /v1/\_purchase > Report transaction (purchase) ```json {"openapi":"3.0.0","info":{"title":"veasybl.io","version":"1.0.7"},"servers":[{"url":"https://[retailer-endpoint]"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"PurchaseRequest":{"type":"object","properties":{"visitor":{"type":"string","description":"Unique identifier for the visitor session during which the purchase was made."},"alias":{"type":"string","description":"Optional hashed customer identifier for anonymous or privacy-safe tracking of the buyer."},"currency":{"type":"string","description":"Three-letter currency code (ISO 4217 format) representing the transaction currency.","enum":["EUR"]},"purchase_id":{"type":"string","description":"Unique identifier for the purchase transaction."},"purchase_date":{"type":"string","description":"ISO 8601 timestamp of when the purchase was completed (e.g., \"YYYY-MM-DDTHH:mm:ss.sssZ\")."},"items":{"description":"List of items purchased in the transaction. Each item contains detailed purchase information.","type":"array","items":{"$ref":"#/components/schemas/PurchaseItem"}}},"required":["visitor","currency","purchase_id","purchase_date","items"]},"PurchaseItem":{"type":"object","properties":{"product_id":{"type":"string","description":"Unique product identifier (SKU) for the purchased item."},"price":{"type":"number","description":"Unit price of the purchased item in the specified transaction currency."},"quantity":{"type":"number","description":"Quantity of this product included in the purchase. Defaults to 1 if not provided."},"offer_id":{"type":"string","description":"Optional identifier for the specific sales offer or promotion associated with this item."},"seller_id":{"type":"string","description":"Identifier for the seller or merchant offering this product."},"seller":{"type":"string","description":"Name of the seller or merchant for this item."},"brand":{"type":"string","description":"Brand name or identifier for the purchased product."}},"required":["product_id","price"]}}},"paths":{"/v1/_purchase":{"post":{"operationId":"apiPurchase","parameters":[{"name":"x-retailer-id","in":"header","style":"simple","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseRequest"}}}},"responses":{"204":{"description":"No Content."},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."}},"summary":"Report transaction (purchase)","tags":["Docs"]}}}} ``` {% tabs %} {% tab title="EXEMPLE" %} ```json POST https://[retailer-endpoint]/v1/_purchase x-api-key: [your_api_key_goes_here] x-retailer-id: [your_retailer_id_goes_here] Content-Type: application/json { "visitor" : "string", "alias" : "string", "purchase_id" : "string", "purchase_date": "string (iso date)" , "currency" : "string (iso currency code)", "items": [ { "product_id" : "string", "price" : number, "quantity": number, "offer_id" : "string", "seller_id" : "string", "seller" : "string", "brand" : "string" } ] } ``` {% endtab %} {% endtabs %} {% hint style="info" %} Munissez-vous de votre API\_KEY pour utiliser l'API. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.veasybl.io/api-integration/reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.