openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Manage Suggestions 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: Manage Suggestions
paths:
  /suggestions/{sellerId}/{sellerSkuId}:
    put:
      tags:
      - Manage Suggestions
      summary: VTex Send SKU Suggestion
      description: 'This request is used by the seller when it wants to suggest that one of their SKUs is sold in the marketplace.


        Before using this request, the seller should always use the [Change Notification](https://developers.vtex.com/vtex-rest-api/reference/catalog-api-get-seller-sku-notification) request in order to check if the SKU already exists in the marketplace. If it doesn''t, then this is the next call in the SKU integration flow.


        In the Send Suggestion request, the seller must send information about the SKU, such as the product and SKU name, the seller ID, and the image URL. All parameters are explained below. '
      operationId: SaveSuggestion
      parameters:
      - name: accountName
        in: path
        required: true
        description: Name of the VTEX account to which the seller wants to suggest a new SKU. It is used as part of the request URL.
        schema:
          type: string
          default: apiexamples
      - 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/vnd.vtex.suggestion.v0+json
          default: application/json
      - name: Content-Type
        in: header
        description: Describes the type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: sellerId
        in: path
        description: A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.
        required: true
        style: simple
        schema:
          type: string
          default: seller123
      - name: sellerSkuId
        in: path
        description: A string that identifies the SKU in the seller. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.
        required: true
        style: simple
        schema:
          type: string
          default: '1234'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveSuggestionRequest'
            example:
              ProductId: '321'
              ProductName: Product sample
              NameComplete: Complete product name
              ProductDescription: sample
              BrandName: Brand 1
              SkuName: Sku sample
              SellerId: string
              Height: 1
              Width: 1
              Length: 1
              Weight: 1
              Updated: null
              RefId: REFID123
              SellerStockKeepingUnitId: 567
              CategoryFullPath: Category 1
              Images:
              - imageName: Principal
                imageUrl: https://i.pinimg.com/originals/2d/96/4a/2d964a6bf37d9224d0615dc85fccdd62.jpg
              ProductSpecifications:
              - fieldName: Fabric
                fieldValues:
                - Cotton
                - Velvet
              SkuSpecifications:
              - fieldName: Color
                fieldValues:
                - Red
                - Blue
              EAN: EAN123
              MeasurementUnit: un
              UnitMultiplier: 1
              AvailableQuantity: 111
              Pricing:
                Currency: BRL
                SalePrice: 399
                CurrencySymbol: R$
        required: true
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
    delete:
      tags:
      - Manage Suggestions
      summary: VTex Delete SKU Suggestion
      description: This endpoint deletes a chosen SKU suggestion. Only one SKU should be deleted per request. This request cannot be undone. A workaround to revert its action, is to send the suggestion again, through the Send Suggestion API.
      operationId: DeleteSuggestion
      parameters:
      - name: accountName
        in: path
        required: true
        description: Name of the VTEX account. Used as part of the URL.
        schema:
          type: string
          default: apiexamples
      - 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
      - name: Content-Type
        in: header
        description: Describes the type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: sellerId
        in: path
        description: A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.
        required: true
        style: simple
        schema:
          type: string
          default: seller123
      - name: sellerSkuId
        in: path
        description: A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.
        required: true
        style: simple
        schema:
          type: string
          default: '1234'
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
components:
  schemas:
    SkuSpecification:
      title: skuSpecification
      type: object
      properties:
        fieldName:
          type: string
          description: 'Name of the SKU specification field. Example: ''Color''.'
          default: color
        fieldValues:
          type: array
          items:
            type: string
            default: Red
            description: Value of the SKU specification field.
          default:
          - Red
          description: 'Array with values of the SKU specification field. Example: ''Red''.'
      default:
        fieldName: Color
        fieldValues:
        - Red
        - Green
    Image:
      title: Image
      required:
      - imageName
      - imageUrl
      type: object
      properties:
        imageName:
          type: string
          description: Name of the SKU image.
        imageUrl:
          type: string
          description: URL of the SKU image. The image must be sent through `https` protocol, otherwise it will not be rendered in VTEX Admin.
          default: https://imageurl.example
      example:
        imageName: Principal
        imageUrl: https://i.pinimg.com/originals/2d/96/4a/2d964a6bf37d9224d0615dc85fccdd62.jpg
    SaveSuggestionRequest:
      title: SaveSuggestionRequest
      required:
      - ProductName
      - ProductId
      - ProductDescription
      - BrandName
      - SkuName
      - SellerId
      - Height
      - Width
      - Length
      - Weight
      - Updated
      - RefId
      - CategoryFullPath
      - Images
      - EAN
      - AvailableQuantity
      - Pricing
      type: object
      properties:
        ProductName:
          type: string
          description: Name of the suggested product. This field has a limit of 150 characters.
          default: ''
        ProductId:
          type: string
          description: Product ID in seller's account.
          default: '1234'
        ProductDescription:
          type: string
          description: Product Description containing the main information about the product (not the SKU).
        BrandName:
          type: string
          description: Name of the brand to which this SKU belongs. It must match the brand created in the marketplace.
        SkuName:
          type: string
          description: Name of the suggested SKU.
        SellerId:
          type: string
          description: ID of the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.
          default: '1'
        Height:
          type: integer
          format: decimal
          description: Height of the SKU.
          default: 10
        Width:
          type: integer
          format: decimal
          description: Width of the SKU.
          default: 10
        Length:
          type: integer
          format: decimal
          description: Length of the SKU.
          default: 10
        Weight:
          type: integer
          format: decimal
          description: Weight of the SKU in grams.
          default: 100
        RefId:
          type: string
          description: SKU reference code. Mandotory if the EAN is not informed.
          default: REF10
        EAN:
          type: string
          description: SKU reference code. Mandatory if the RefId is not informed.
          default: EAN10
        SellerStockKeepingUnitId:
          type: integer
          format: int32
          description: ID of the SKU registered in the seller.
        CategoryFullPath:
          type: string
          description: 'Full path to the SKU''s category. It should be written as {department}/{category}. For example: if the department is **Appliances** and the category is **Oven**, the full path should be ''Appliances/Oven''.'
        SkuSpecifications:
          type: array
          items:
            $ref: '#/components/schemas/SkuSpecification'
          description: Array containing the names and values of the SKU specifications.
        ProductSpecifications:
          type: array
          items:
            $ref: '#/components/schemas/ProductSpecification'
          description: Array containing the names and values of the product specifications.
        Images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
          description: Array containing the URLs and names the SKU images.
        MeasurementUnit:
          type: string
          description: Measurement unit that should be used for this SKU. If this information doesn't apply, you should use the default value `un`.
        UnitMultiplier:
          type: integer
          format: int32
          description: Unit multiplier for this SKU. If this information doesn't apply, you should use the default value `1`.
        AvailableQuantity:
          type: integer
          format: int32
          description: ''
        Pricing:
          type: object
          properties:
            Currency:
              type: string
            SalePrice:
              type: integer
              format: int32
            CurrencySymbol:
              type: string
          description: ''
      default:
        ProductId: '321'
        ProductName: Product sample
        NameComplete: My complete product name?
        ProductDescription: sample
        BrandName: Brand 1
        SkuName: Sku sample
        SellerId: '123'
        Height: 1
        Width: 1
        Length: 1
        Weight: 1
        Updated: null
        RefId: REFID123
        SellerStockKeepingUnitId: 567
        CategoryFullPath: Category 1
        Images:
        - imageName: Principal
          imageUrl: https://i.pinimg.com/originals/2d/96/4a/2d964a6bf37d9224d0615dc85fccdd62.jpg
        ProductSpecifications:
        - fieldName: prodspec1
          fieldValues:
          - value1
          - value2
        SkuSpecifications:
        - fieldName: skuspec1
          fieldValues:
          - value1
          - value2
        EAN: EAN123
        MeasurementUnit: un
        UnitMultiplier: 1
        AvailableQuantity: 111
        Pricing:
          Currency: BRL
          SalePrice: 399
          CurrencySymbol: R$
    ProductSpecification:
      title: Product Specification
      type: object
      properties:
        fieldName:
          type: string
          description: 'Name of the product specification field. Example: ''Fabric''.'
          default: Fabric type
        fieldValues:
          type: array
          description: 'Value of the product specification field. Example: ''Cotton''.'
          items:
            type: string
            default: Cotton
            description: Value of the product specification field.
      example:
        fieldName: Color
        fieldValues:
        - Red
        - Green
  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.'