openapi: 3.0.0
info:
title: VTex Anti-fraud Provider Account Events API
description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Anti-fraud Provider Protocol is a set of definitions to help you integrate your anti-fraud service API into VTEX platform.\r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications described in this documentation.\r\n\r\n>⚠️ You can also access our [template on GitHub](https://github.com/vtex-apps/antifraud-provider-example) to help you quickly develop your anti-fraud connector using the Anti-fraud Provider Protocol and VTEX IO.\r\n\r\nTo learn more about the Anti-fraud Provider Protocol, check our [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works).\r\n\r\n## Anti-fraud Provider API Index\r\n\r\n### Anti-fraud Flow\r\n\r\n- `POST` [Send Anti-fraud Pre-Analysis Data (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/pre-analysis)\r\n- `POST` [Send Anti-fraud Data](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions)\r\n- `PUT` [Update Anti-fraud Transactions (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#put-/transactions/-transactionId-)\r\n- `GET` [List Anti-fraud Provider Manifest](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/manifest)\r\n- `GET` [Get Anti-fraud Status](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/transactions/-transactions.id-)\r\n- `DELETE` [Stop Anti-fraud Analysis (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#delete-/transactions/-transactions.Id-)\r\n\r\n### OAuth Flow\r\n\r\n1. `POST` [Retrieve Token](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token)\r\n2. `GET` [Redirect](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/redirect)\r\n3. `GET` [Return to VTEX](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorizationCode)\r\n4. `GET` [Get Credentials](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorization/credentials)"
version: '1.0'
servers:
- url: https://{providerApiEndpoint}
description: Anti-fraud provider endpoint URL.
variables:
providerApiEndpoint:
description: Anti-fraud provider endpoint URL.
default: '{providerApiEndpoint}'
tags:
- name: Events
paths:
/event:
post:
summary: VTex Save events
description: "Creates search events to integrate with VTEX Intelligent Search using a headless implementation. \r\n\r\n >⚠️ **This API applies only to Headless scenarios**. It doesn't apply to stores using VTEX's storefront solution, natively integrated with Intelligent Search."
parameters:
- name: accountName
in: path
description: Name of the VTEX account. Used as part of the URL.
required: true
schema:
type: string
example: apiexamples
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SessionPing'
- $ref: '#/components/schemas/PageCart'
- $ref: '#/components/schemas/PageEmptyCart'
- $ref: '#/components/schemas/PageConfirmation'
- $ref: '#/components/schemas/Click'
- $ref: '#/components/schemas/Query'
examples:
Session Ping:
value:
session: zZlNhqz1vFJP6iPG5Oqtt
anonymous: Om1TNluGvgmSgU5OOTvkkd
url: https://example.com/search/?query=zapatilha
agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0
type: search.query
text: zapatilha
misspelled: true
match: 392
operator: and
Page Cart:
value:
session: zZlNhqz1vFJP6iPG5Oqtt
anonymous: Om1TNluGvgmSgU5OOTvkkd
products:
- productId: ABC123
quantity: 2
- productId: XYZ789
quantity: 1
type: page.cart
Empty Cart:
value:
session: zZlNhqz1vFJP6iPG5Oqtt
anonymous: Om1TNluGvgmSgU5OOTvkkd
products: []
type: page.empty_cart
Page Confirmation:
value:
session: zZlNhqz1vFJP6iPG5Oqtt
anonymous: Om1TNluGvgmSgU5OOTvkkd
products:
- productId: ABC123
price: 9.99
quantity: 3
- productId: XYZ789
price: 5.99
quantity: 2
order: 123ABC
type: page.confirmation
Search Click:
value:
type: search.click
productId: '12345'
position: 1
url: https://example.com/s?q=pneu&sort=score_desc&page=0
text: pneu
agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36
anonymous: 1ce47e50-3f10-4556-95d3-57d4881c03a4
session: 51a53ce3-096d-4740-a6d0-3cf86085ba13
Search Query:
value:
session: zZlNhqz1vFJP6iPG5Oqtt
anonymous: Om1TNluGvgmSgU5OOTvkkd
url: https://example.com/search/?query=zapatilha
agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0
type: search.query
text: zapatilha
misspelled: true
match: 392
operator: and
tags:
- Events
responses:
'204':
description: No content
components:
schemas:
UserIdentification:
properties:
anonymous:
type: string
title: anonymous
description: Identifier related to related to the user, according to the [nanoid](https://github.com/ai/nanoid) pattern. This information is kept in storage for one year.
example: Om1TNluGvgmSgU5OOTvkkd
session:
type: string
title: session
description: Identifier related to the current navigation, according to the [nanoid](https://github.com/ai/nanoid) pattern. It is a cookie that lasts for 30 minutes, changing if the user opens another tab in private navigation mode.
example: zZlNhqz1vFJP6iPG5Oqtt
Query:
title: Search Query
description: Sends a query event every time the shopper makes a full-text search.
type: object
required:
- session
- anonymous
- type
- misspelled
- text
- match
- operator
properties:
session:
$ref: '#/components/schemas/UserIdentification/properties/session'
anonymous:
$ref: '#/components/schemas/UserIdentification/properties/anonymous'
url:
type: string
title: url
description: URL that identifies from which page the event occurred.
example: https://example.com/search/?query=zapatilha
agent:
type: string
title: agent
description: Identifies whether the request came from a mobile or desktop application. It's used as a filter in the search report.
default: desktop
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0
type:
type: string
title: type
description: 'Type of event, which can be one of the following: `page.cart`, `page.empty_cart`, `search.query`, `page.confirmation`, `session.ping`, `search.click`.'
example: search.query
text:
type: string
title: text
description: Query used in the search.
example: tv
misspelled:
type: boolean
title: misspelled
description: Indicates whether the query has a typo (`true`) or not (`false`).
example: true
match:
type: number
title: match
description: Amount of products retrieved by the search.
example: 396
operator:
type: string
title: operator
description: 'Identifies the type of operator used on the search. The possible values are: `and`, `or`. Find more details in [this Elastic Search guide](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query.html).'
example: and
PageConfirmation:
title: Page Confirmation
description: Sends a confirmation informing the products that were bought.
type: object
required:
- session
- anonymous
- type
- order
- products
properties:
session:
$ref: '#/components/schemas/UserIdentification/properties/session'
anonymous:
$ref: '#/components/schemas/UserIdentification/properties/anonymous'
products:
type: array
title: products
description: Array of objects containing products. If the event type is `page.cart`, the array contains all the products in the cart, with their ID and quantity. Each interaction should include all products inside the shopping cart at that time. In case a product is removed, sent the updated card. If there are no products in the cart (page.`empty_cart`), the array is empty. If the event type is `page.confirmation`, the array contains all the products that were purchased, with their ID, price and quantity.
items:
$ref: '#/components/schemas/OrderProduct'
order:
type: string
title: order
description: Order ID.
example: 123ABC
type:
type: string
title: type
description: 'Type of event, which can be one of the following: `page.cart`, `page.empty_cart`, `search.query`, `page.confirmation`, `session.ping`, `search.click`.'
example: page.confirmation
OrderProduct:
type: object
description: Product information.
required:
- productId
- price
- quantity
properties:
productId:
type: string
description: Unique identifier of the product.
example: ABC123
price:
type: number
description: Price of the product.
example: 9.99
quantity:
type: number
description: Quantity of the product.
example: 3
PageCart:
title: PageCart
description: Sends an event every time the shopper enters the cart page. Each interaction should include all products inside the shopping cart at that time. In case a product is removed, sent the updated card.
type: object
required:
- session
- anonymous
- type
- products
properties:
session:
$ref: '#/components/schemas/UserIdentification/properties/session'
anonymous:
$ref: '#/components/schemas/UserIdentification/properties/anonymous'
products:
type: array
title: products
description: Array of objects containing products. If the event type is `page.cart`, the array contains all the products in the cart, with their ID and quantity. Each interaction should include all products inside the shopping cart at that time. In case a product is removed, sent the updated card. If there are no products in the cart (page.`empty_cart`), the array is empty. If the event type is `page.confirmation`, the array contains all the products that were purchased, with their ID, price and quantity.
items:
$ref: '#/components/schemas/CartProduct'
type:
type: string
title: type
description: 'Type of event, which can be one of the following: `page.cart`, `page.empty_cart`, `search.query`, `page.confirmation`, `session.ping`, `search.click`.'
example: page.cart
PageEmptyCart:
title: Empty Cart
description: Sends an event if there are no products in the shopping cart at that time.
type: object
required:
- session
- anonymous
- type
- products
properties:
session:
$ref: '#/components/schemas/UserIdentification/properties/session'
anonymous:
$ref: '#/components/schemas/UserIdentification/properties/anonymous'
products:
type: array
title: products
description: Array of objects containing products. If the event type is `page.cart`, the array contains all the products in the cart, with their ID and quantity. Each interaction should include all products inside the shopping cart at that time. In case a product is removed, sent the updated card. If there are no products in the cart (page.`empty_cart`), the array is empty. If the event type is `page.confirmation`, the array contains all the products that were purchased, with their ID, price and quantity.
items:
$ref: '#/components/schemas/CartProduct'
type:
type: string
title: type
description: 'Type of event, which can be one of the following: `page.cart`, `page.empty_cart`, `search.query`, `page.confirmation`, `session.ping`, `search.click`.'
example: page.empty_cart
SessionPing:
title: SessionPing
description: Sends an ACK to the API to renew the session server-side. It should be sent every 1 minute.
type: object
required:
- session
- anonymous
- type
- agent
properties:
session:
$ref: '#/components/schemas/UserIdentification/properties/session'
anonymous:
$ref: '#/components/schemas/UserIdentification/properties/anonymous'
type:
type: string
title: type
description: 'Type of event, which can be one of the following: `page.cart`, `page.empty_cart`, `search.query`, `page.confirmation`, `session.ping`, `search.click`.'
example: session.ping
agent:
type: string
title: agent
description: Identifies whether the request came from a mobile or desktop application. It's used as a filter in the search report.
default: desktop
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0
Click:
title: Search Click
description: Sends an event every time a shopper clicks on a product from a search page.
type: object
required:
- type
- productId
- position
- text
- anonymous
- session
properties:
type:
type: string
title: type
description: 'Type of event, which can be one of the following: `page.cart`, `page.empty_cart`, `search.query`, `page.confirmation`, `session.ping`, `search.click`.'
example: search.click
productId:
type: string
description: Unique identifier of the clicked product.
example: '12345'
position:
type: integer
description: Position of the clicked product on the search results page.
example: 1
url:
type: string
title: url
description: URL that identifies from which page the event occurred.
example: https://example.com/s?q=pneu&sort=score_desc&page=0
text:
type: string
title: text
description: Query used in the search.
example: tv
agent:
type: string
title: agent
description: Identifies whether the request came from a mobile or desktop application. It's used as a filter in the search report.
default: desktop
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0
anonymous:
$ref: '#/components/schemas/UserIdentification/properties/anonymous'
session:
$ref: '#/components/schemas/UserIdentification/properties/session'
CartProduct:
type: object
description: Product information.
required:
- productId
- quantity
properties:
productId:
type: string
description: Unique identifier of the product.
example: ABC123
quantity:
type: number
description: Quantity of the product.
example: 2
securitySchemes:
VtexIdclientAutCookie:
type: apiKey
in: header
name: VtexIdclientAutCookie
description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'