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.'