VTEX SKU File API

openapi: 3.2.0
info:
  title: VTex Catalog SKU File API
  description: '> Check the new Catalog onboarding guide.'
  version: '1.0'
servers:
- url: https://{accountName}.{environment}.com.br
  description: VTEX server URL.
  variables:
    accountName:
      description: Name of the VTEX account. Used as part of the URL.
      default: apiexamples
    environment:
      description: Environment to use. Used as part of the URL.
      enum:
      - vtexcommercestable
      default: vtexcommercestable
security:
- appKey: []
  appToken: []
- VtexIdclientAutCookie: []
tags:
- name: SKU File
paths:
  /api/catalog/pvt/stockkeepingunit/{skuId}/file:
    get:
      tags:
      - SKU File
      summary: VTex Get SKU files
      description: 'Retrieves general information about all files in the SKU.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        required: true
        description: SKU's unique numerical identifier.
        schema:
          type: integer
          example: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: Array with objects containing SKU files information.
                items:
                  type: object
                  description: Object containing each SKU file's information.
                  properties:
                    Id:
                      type: integer
                      description: Unique identifier of the association of the image to the SKU.
                    ArchiveId:
                      type: integer
                      description: Unique identifier of the image.
                    SkuId:
                      type: integer
                      description: Unique identifier of the SKU.
                    Name:
                      type: string
                      description: Image name.
                    IsMain:
                      type: boolean
                      description: Defines if the image is the main image of the SKU.
                    Label:
                      type:
                      - string
                      - 'null'
                      description: Image label.
              example:
              - Id: 549
                ArchiveId: 155485
                SkuId: 310118490
                Name: chimera-cat-quimera-5
                IsMain: true
                Label: miau
              - Id: 550
                ArchiveId: 155486
                SkuId: 310118490
                Name: Gato-siames
                IsMain: false
                Label: Gato siames
              - Id: 555
                ArchiveId: 155491
                SkuId: 310118490
                Name: Cat-Sleeping-Pics
                IsMain: false
                Label: null
      operationId: getApiCatalogPvtStockkeepingunitBySkuIdFile
      x-operation-id-source: derived
    post:
      tags:
      - SKU File
      summary: VTex Create SKU file
      description: 'Creates a new image for an SKU based on its URL or on a form-data request body.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        required: true
        description: SKU's unique numerical identifier.
        schema:
          type: integer
          example: 123456
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SKUFileURL'
          form-data:
            schema:
              $ref: '#/components/schemas/SKUFile'
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                Id: 625
                ArchiveId: 155569
                SkuId: 123456
                IsMain: true
                Label: Main
              schema:
                type: object
                properties:
                  Id:
                    type: integer
                    description: ID of the association of the SKU and the image (`SkuFileId`). This is the ID that is used to update or delete it.
                  ArchiveId:
                    type: integer
                    description: Unique identifier of the image file.
                  SkuId:
                    type: integer
                    description: SKU ID.
                  IsMain:
                    type: boolean
                    description: Set the image as the main image for the product.
                  Label:
                    type: string
                    description: Image label.
      operationId: postApiCatalogPvtStockkeepingunitBySkuIdFile
      x-operation-id-source: derived
    delete:
      tags:
      - SKU File
      summary: VTex Delete all SKU files
      description: 'Deletes all SKU image files.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        required: true
        description: SKU's unique numerical identifier.
        schema:
          type: integer
          example: 1
      responses:
        '200':
          description: OK
      operationId: deleteApiCatalogPvtStockkeepingunitBySkuIdFile
      x-operation-id-source: derived
  /api/catalog/pvt/stockkeepingunit/{skuId}/file/{skuFileId}:
    put:
      tags:
      - SKU File
      summary: VTex Update SKU file
      description: 'Updates a new image on an SKU based on its URL or on a form-data request body.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        required: true
        description: SKU's unique numerical identifier.
        schema:
          type: integer
          example: 123456
      - name: skuFileId
        in: path
        required: true
        description: ID of the association of the SKU and the image, which can be obtained by placing a request to the [Get SKU file](https://developers.vtex.com/vtex-rest-api/reference/catalog-api-get-sku-file) endpoint and copying the `Id` field.
        schema:
          type: integer
          example: 517
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SKUFileURL'
          form-data:
            schema:
              $ref: '#/components/schemas/SKUFile'
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                Id: 625
                ArchiveId: 155569
                SkuId: 123456
                IsMain: true
                Label: Main
              schema:
                type: object
                properties:
                  Id:
                    type: integer
                    description: ID of the association of the SKU and the image (`SkuFileId`). This is the ID that is used to update or delete it.
                  ArchiveId:
                    type: integer
                    description: Unique identifier of the image file.
                  SkuId:
                    type: integer
                    description: SKU ID.
                  IsMain:
                    type: boolean
                    description: Set the image as the main image for the product.
                  Label:
                    type: string
                    description: Image label.
      operationId: putApiCatalogPvtStockkeepingunitBySkuIdFileBySkuFileId
      x-operation-id-source: derived
    delete:
      tags:
      - SKU File
      summary: VTex Delete SKU image file
      description: 'Deletes a specific SKU image file.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        required: true
        description: SKU's unique numerical identifier.
        schema:
          type: integer
          example: 1
      - name: skuFileId
        in: path
        required: true
        description: ID of the association of the SKU and the image, which can be obtained by placing a request to the [Get SKU file](https://developers.vtex.com/vtex-rest-api/reference/catalog-api-get-sku-file) endpoint and copying the `Id` field.
        schema:
          type: integer
          example: 1
      responses:
        '200':
          description: OK
      operationId: deleteApiCatalogPvtStockkeepingunitBySkuIdFileBySkuFileId
      x-operation-id-source: derived
  /api/catalog/pvt/stockkeepingunit/copy/{skuIdfrom}/{skuIdto}/file:
    put:
      tags:
      - SKU File
      summary: VTex Copy files from an SKU to another SKU
      description: 'Copy all existing files from an SKU to another SKU.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuIdfrom
        in: path
        required: true
        description: __Origin__ SKU's unique numerical identifier.
        schema:
          type: integer
          example: 1
      - name: skuIdto
        in: path
        required: true
        description: __Target__ SKU's unique numerical identifier.
        schema:
          type: integer
          example: 2
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: Array with objects containing information about each of the target SKU's files.
                items:
                  type: object
                  description: Object containing each SKU file's information.
                  properties:
                    Id:
                      type: integer
                      description: Unique identifier of the association of the image to the SKU.
                    ArchiveId:
                      type: integer
                      description: Unique identifier of the image file.
                    SkuId:
                      type: integer
                      description: Unique identifier of the SKU.
                    IsMain:
                      type: boolean
                      description: Defines if the image is the main image of the SKU.
                    Label:
                      type:
                      - string
                      - 'null'
                      description: Image label.
              example:
              - Id: 1964
                ArchiveId: 155404
                SkuId: 1
                IsMain: true
                Label: ''
              - Id: 1965
                ArchiveId: 155429
                SkuId: 1
                IsMain: false
                Label: ''
      operationId: putApiCatalogPvtStockkeepingunitCopyBySkuIdfromBySkuIdtoFile
      x-operation-id-source: derived
  /api/catalog/pvt/stockkeepingunit/disassociate/{skuId}/file/{skuFileId}:
    delete:
      tags:
      - SKU File
      summary: VTex Disassociate SKU file
      description: 'Disassociates an SKU file from an SKU.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Content | **SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        required: true
        description: SKU's unique numerical identifier.
        schema:
          type: integer
          example: 1
      - name: skuFileId
        in: path
        required: true
        description: ID of the association of the SKU and the image, which can be obtained by placing a request to the [Get SKU file](https://developers.vtex.com/vtex-rest-api/reference/catalog-api-get-sku-file) endpoint and copying the `Id` field.
        schema:
          type: integer
          example: 32
      responses:
        '200':
          description: OK
      operationId: deleteApiCatalogPvtStockkeepingunitDisassociateBySkuIdFileBySkuFileId
      x-operation-id-source: derived
components:
  schemas:
    SKUFileURL:
      type: object
      required:
      - Name
      - Url
      properties:
        IsMain:
          type: boolean
          description: Defines if the image is the main image of the SKU.
          example: true
        Label:
          type: string
          description: SKU image label.
          example: Main
        Name:
          type: string
          description: SKU image name.
          example: Nike-Red-Janoski-1
        Text:
          type:
          - string
          - 'null'
          description: General text of the image.
          example: Nike-Red-Janoski
        Url:
          type: string
          description: External image's URL.  The URL must start with the protocol identifier (`http://` or `https://`) and end with the file extension (`.jpg`, `.png` or `.gif`).
          example: https://m.media-amazon.com/images/I/610G2-sJx5L._AC_UX695_.jpg
    SKUFile:
      type: string
      format: binary
      description: The image file has a size limit of 3200 x 3200 pixels.
  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:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
      description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
      description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    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.'