VTEX Clusters API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Clusters 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: Clusters
paths:
  /api/dataentities/{dataEntityName}/documents/{id}/clusters:
    post:
      tags:
      - Clusters
      summary: VTex Validate document by clusters
      description: "Checks if a document is present in one or more clusters (specific set of field values).\r\n\r\n>ℹ️ There is a limit of five rules per request.  \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      operationId: Validatedocumentbyclusters
      parameters:
      - $ref: '#/components/parameters/dataEntityName'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/id'
      requestBody:
        description: Request body for validating a document by clusters
        content:
          application/json:
            schema:
              type: array
              description: List of cluster validation rule information.
              items:
                type: object
                description: Cluster validation rule information.
                properties:
                  name:
                    type: string
                    description: Cluster name.
                    example: male
                  rule:
                    type: string
                    description: Cluster validation rule.
                    example: gender=male
            example:
            - name: male
              rule: gender=male
            - name: complex
              rule: ((gender=male AND percent=0.35) AND any is null) AND (name=*go*)
            - name: complex2
              rule: ((gender=male AND percent=0.35) AND any is not null) OR (name=*go*)
            - name: createdIn
              rule: createdIn between 2015-10-28 AND 2015-10-30
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: Array with objects validating each cluster rule.
                items:
                  type: object
                  description: Cluster rule validation object.
                  properties:
                    name:
                      type: string
                      description: Cluster name.
                    isValid:
                      type: boolean
                      description: Informs if the document is valid according to the cluster rule (`true`) or not (`false`).
              example:
              - name: male
                isValid: false
              - name: complex
                isValid: false
              - name: complex2
                isValid: false
              - name: createdIn
                isValid: false
      deprecated: false
components:
  parameters:
    id:
      name: id
      in: path
      description: ID of the Document.
      required: true
      style: simple
      schema:
        type: string
        example: b818cbda-e489-11e6-94f4-0ac138d2d42e
    Accept:
      name: Accept
      in: header
      description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
      required: true
      style: simple
      schema:
        type: string
        example: application/json
    dataEntityName:
      name: dataEntityName
      in: path
      required: true
      description: Name of the data entity.
      schema:
        type: string
        example: Newsletter
  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.'