VTEX Specification Field API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Specification Field 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: Specification Field
paths:
  /api/catalog_system/pub/specification/fieldGet/{fieldId}:
    get:
      tags:
      - Specification Field
      summary: VTex Get specification field
      description: "Retrieves details from a specification field by this field's ID. \r\n>⚠️ This is a legacy endpoint. We recommend using [Get specification](https://developers.vtex.com/vtex-rest-api/reference/get_api-catalog-pvt-specification-specificationid) instead.\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| Catalog | Commercial | **SKU management** |\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: SpecificationsField
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: fieldId
        in: path
        description: Specification field ID.
        required: true
        style: simple
        schema:
          type: integer
          example: 88
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                Name: Material
                CategoryId: 4
                FieldId: 88
                IsActive: true
                IsRequired: true
                FieldTypeId: 1
                FieldTypeName: Texto
                FieldValueId: null
                Description: Composition of the product.
                IsStockKeepingUnit: false
                IsFilter: true
                IsOnProductDetails: false
                Position: 1
                IsWizard: false
                IsTopMenuLinkActive: false
                IsSideMenuLinkActive: true
                DefaultValue: null
                FieldGroupId: 20
                FieldGroupName: Clothes specifications
              schema:
                type: object
                properties:
                  Name:
                    type: string
                    description: Specification field name.
                  FieldId:
                    type: integer
                    description: Specification field ID.
                  IsActive:
                    type: boolean
                    description: Enable (`true`) or disable (`false`) specification.
                  IsRequired:
                    type: boolean
                    description: Makes the specification mandatory (`true`) or optional (`false`).
                  FieldTypeId:
                    type: integer
                    description: Field type ID can be `1 - Text`, `2 - Multi-Line Text`, `4 - Number`, `5 - Combo`, `6 - Radio`, `7 - Checkbox`, `8 - Indexed Text`, `9 - Indexed Multi-Line Text`.
                  FieldTypeName:
                    type: string
                    description: Field type name, which can be `Text`, `Multi-Line Text`, `Number`, `Combo`, `Radio`, `Checkbox`, `Indexed Text` or `Indexed Multi-Line Text`.
                  FieldValueId:
                    type: integer
                    description: Specification value ID.
                    nullable: true
                  Description:
                    type: string
                    deprecated: true
                    nullable: true
                  IsStockKeepingUnit:
                    type: boolean
                    description: If `true`, it will be added as a SKU specification. If `false`, it will be added as a product specification field.
                  IsFilter:
                    type: boolean
                    description: "Store Framework - Deprecated.\r\nLegacy CMS Portal - To allow the specification to be used as a facet (filter) on the search navigation bar."
                  IsOnProductDetails:
                    type: boolean
                    description: "Store Framework - Deprecated.\r\nLegacy CMS Portal -If specification is visible on the product page."
                  Position:
                    type: integer
                    description: "Store Framework - Deprecated.\r\nLegacy CMS Portal - This position number is used in ordering the specifications both in the navigation menu and in the specification listing on the product page."
                  IsWizard:
                    type: boolean
                    deprecated: true
                    description: Deprecated field.
                    nullable: true
                  IsTopMenuLinkActive:
                    type: boolean
                    description: "Store Framework - Deprecated.\r\nLegacy CMS Portal - To make the specification visible in the store's upper menu."
                  IsSideMenuLinkActive:
                    type: boolean
                    description: "Store Framework - Deprecated.\r\nLegacy CMS Portal - To make the specification field clickable in the search navigation bar."
                  DefaultValue:
                    type: string
                    description: Specification default value.
                    nullable: true
                  FieldGroupId:
                    type: integer
                    description: ID of the group of specifications that contains the new specification.
                  FieldGroupName:
                    type: string
                    description: Specification field group name.
      deprecated: false
  /api/catalog_system/pvt/specification/field:
    post:
      tags:
      - Specification Field
      summary: VTex Create specification field
      description: "Creates a specification field in a category. \r\n>⚠️ This is a legacy endpoint. We recommend using [Create specification](https://developers.vtex.com/docs/api-reference/catalog-api#post-/api/catalog/pvt/specification?endpoint=post-/api/catalog/pvt/specification) instead.\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| Catalog | Commercial | **SKU management** |\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: SpecificationsInsertField
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecificationsInsertFieldRequest'
            example:
              Name: Material
              CategoryId: 4
              FieldId: 88
              IsActive: true
              IsRequired: true
              FieldTypeId: 1
              FieldValueId: 1
              IsStockKeepingUnit: false
              Description: Composition of the product.
              IsFilter: true
              IsOnProductDetails: false
              Position: 1
              IsWizard: false
              IsTopMenuLinkActive: true
              IsSideMenuLinkActive: true
              DefaultValue: null
              FieldGroupId: 20
              FieldGroupName: Clothes specifications
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              example: 89
              schema:
                type: integer
                description: Specification field ID.
      deprecated: false
    put:
      tags:
      - Specification Field
      summary: VTex Update specification field
      description: "Updates a specification field in a category. \r\n>⚠️ This is a legacy endpoint. We recommend using [Update specification](https://developers.vtex.com/docs/api-reference/catalog-api#put-/api/catalog/pvt/stockkeepingunit/-skuId-/specification?endpoint=put-/api/catalog/pvt/stockkeepingunit/-skuId-/specification) instead.\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| Catalog | Commercial | **SKU management** |\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: SpecificationsInsertFieldUpdate
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecificationsInsertFieldUpdateRequest'
            example:
              FieldId: 89
              Name: Material
              CategoryId: 4
              IsActive: true
              IsRequired: true
              FieldTypeId: 1
              Description: Composition of the product.
              IsStockKeepingUnit: false
              IsFilter: true
              IsOnProductDetails: true
              Position: 1
              IsWizard: false
              IsTopMenuLinkActive: false
              IsSideMenuLinkActive: false
              DefaultValue: Cotton
              FieldGroupId: 20
              FieldGroupName: Clothes specifications
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              example: 89
              schema:
                type: integer
                description: Specification field ID.
      deprecated: false
components:
  schemas:
    SpecificationsInsertFieldUpdateRequest:
      required:
      - Name
      - CategoryId
      - IsActive
      - FieldId
      - IsRequired
      - FieldTypeId
      - Description
      - IsStockKeepingUnit
      - IsWizard
      - IsFilter
      - IsOnProductDetails
      - Position
      - IsTopMenuLinkActive
      - IsSideMenuLinkActive
      - DefaultValue
      - FieldGroupId
      - FieldGroupName
      type: object
      properties:
        Name:
          type: string
          description: Specification field ID.
        CategoryId:
          type: integer
          nullable: true
          description: Category ID.
        FieldId:
          type: integer
          nullable: true
          description: Specification field ID.
        IsActive:
          type: boolean
          description: Enables(`true`) or disables (`false`) the specification field.
          example: true
        IsRequired:
          type: boolean
          description: Makes the specification field mandatory (`true`) or optional (`false`).
        FieldTypeId:
          type: integer
          format: int32
          description: Specification field type ID.
        FieldValueId:
          type: integer
          nullable: true
          description: Specification field value ID.
        Description:
          type: string
          nullable: true
          description: Specification field description.
        IsStockKeepingUnit:
          type: boolean
          description: If `true`, it will be added as a SKU specification field. If `false`, it will be added as a product specification field.
        IsFilter:
          type: boolean
          description: "Store Framework - Deprecated.\r\nLegacy CMS Portal - To allow the specification to be used as a facet (filter) on the search navigation bar."
        IsOnProductDetails:
          type: boolean
          description: "Store Framework - Deprecated.\r\nLegacy CMS Portal -If specification is visible on the product page."
        Position:
          type: integer
          format: int32
          description: Specification field position.
        IsWizard:
          type: boolean
          description: Deprecated field.
          deprecated: true
        IsTopMenuLinkActive:
          type: boolean
          description: "Store Framework - Deprecated.\r\nLegacy CMS Portal - To make the specification visible in the store's upper menu."
        IsSideMenuLinkActive:
          type: boolean
          description: "Store Framework - Deprecated.\r\nLegacy CMS Portal - To make the specification field clickable in the search navigation bar."
          example: false
        DefaultValue:
          type: string
          nullable: true
          example: null
          description: Specification field default value.
        FieldGroupId:
          type: integer
          format: int32
          description: Specification field group ID.
          example: 1
        FieldGroupName:
          type: string
          description: Specification field group name.
          example: Name
    SpecificationsInsertFieldRequest:
      required:
      - Name
      - CategoryId
      - IsActive
      - FieldId
      - IsRequired
      - FieldTypeId
      - FieldValueId
      - Description
      - IsStockKeepingUnit
      - IsFilter
      - IsOnProductDetails
      - Position
      - IsWizard
      - IsTopMenuLinkActive
      - IsSideMenuLinkActive
      - DefaultValue
      - FieldGroupId
      - FieldGroupName
      type: object
      properties:
        Name:
          type: string
          description: Specification field name. Limited to 100 characters.
        CategoryId:
          type: integer
          nullable: true
          description: Category ID.
        FieldId:
          type: integer
          nullable: true
          description: Specification field ID.
        IsActive:
          type: boolean
          description: Defines if the specification field is active. The default value is `true`.
        IsRequired:
          type: boolean
          description: Makes the specification field mandatory (`true`) or optional (`false`).
        FieldTypeId:
          type: integer
          format: int32
          description: Specification field type ID.
        FieldValueId:
          type: integer
          nullable: true
          description: Specification field value ID.
        Description:
          type: string
          nullable: true
          description: Specification field description.
        IsStockKeepingUnit:
          type: boolean
          description: If `true`, it will be added as a SKU specification. If `false`, it will be added as a product specification field.
        IsFilter:
          type: boolean
          description: "Store Framework - Deprecated.\r\nLegacy CMS Portal - To allow the specification to be used as a facet (filter) on the search navigation bar."
        IsOnProductDetails:
          type: boolean
          description: "Store Framework - Deprecated.\r\nLegacy CMS Portal -If specification is visible on the product page."
        Position:
          type: integer
          format: int32
          description: Specification field position.
        IsWizard:
          type: boolean
          description: Deprecated field.
          deprecated: true
        IsTopMenuLinkActive:
          type: boolean
          description: "Store Framework - Deprecated.\r\nLegacy CMS Portal - To make the specification visible in the store's upper menu."
        IsSideMenuLinkActive:
          type: boolean
          description: "Store Framework - Deprecated.\r\nLegacy CMS Portal - To make the specification field clickable in the search navigation bar."
        DefaultValue:
          type: string
          nullable: true
          description: Specification field default value.
        FieldGroupId:
          type: integer
          format: int32
          description: Specification field group ID.
        FieldGroupName:
          type: string
          description: Specification field group name.
      example:
        Name: Material
        CategoryId: 4
        FieldId: 88
        IsActive: true
        IsRequired: true
        FieldTypeId: 1
        FieldValueId: 1
        IsStockKeepingUnit: false
        Description: Composition of the product.
        IsFilter: true
        IsOnProductDetails: false
        Position: 1
        IsWizard: false
        IsTopMenuLinkActive: true
        IsSideMenuLinkActive: true
        DefaultValue: null
        FieldGroupId: 20
        FieldGroupName: Clothes specifications
  parameters:
    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
        default: application/json
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
  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.'