openapi: 3.0.0
info:
  title: VTEX Do API
  description: VTEX DO is a task management system for authorized users to process orders. It is possible to control notes, and create, update, list, and retrieve tasks.
  contact: {}
  version: '1.0'
servers:
  - url: https://{accountName}.{environment}.com.br/api/do
    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
paths:
  /notes:
    post:
      tags:
        - Note
      summary: VTex Create Note
      description: "This endpoint creates a new note in VTEX DO. Be aware of the following limitations:\r\n\n\r- The maximum number of notes for an order is 30.\r\n\n\r- The maximum number of characters in a note's description is 2000."
      operationId: NewNote
      parameters:
        - 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
        - name: Content-Type
          in: header
          description: Type of the content being sent.
          required: true
          style: simple
          schema:
            type: string
            example: application/json
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - target
                - domain
                - description
              properties:
                target:
                  type: object
                  description: Target.
                  properties:
                    id:
                      type: string
                      description: Target ID.
                      example: v964735bdev-01
                    type:
                      type: string
                      description: Target type.
                      example: order
                    url:
                      type: string
                      description: Target URL.
                      example: https://basedevmkp.vtexcommercebeta.com.br/admin/checkout/#/orders/v964741bdev-01
                domain:
                  type: string
                  description: Note domain.
                  example: oms
                description:
                  type: string
                  description: 'Note description. Maximum number of characters: 2000.'
                  example: Order ID in the marketplace is 786-09.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
              example:
                id: A08CDB2519AC4FA49EB6099CF72C3642
                domain: oms
                owner: c97ef6c8491a439f927cf9918644329f
                target:
                  id: v964735bdev-01
                  type: order
                  url: https://basedevmkp.vtexcommercebeta.com.br/admin/checkout/#/orders/v964741bdev-01
                description: The order's ID in the marketplace is 786-09
                creationDate: '2022-01-11T15:49:17.8785392Z'
                lastUpdate: '2022-01-11T15:49:17.8785392Z'
                createdBy:
                  id: fb542e51-5488-4c34-8d17-ed8fcf597a94
                  name: pedro.costa@vtex.com.br
                  email: pedro.costa@vtex.com.br
                  key:
      deprecated: false
    get:
      tags:
        - Note
      summary: VTex Get Notes by orderId
      description: Retrieves notes related to a specific `orderId`.
      operationId: GetNotesbyorderId
      parameters:
        - name: target.id
          in: query
          description: ID of the order.
          required: true
          style: form
          explode: true
          schema:
            type: string
            description: ID of the order.
            example: 1172452900788-01
        - name: perPage
          in: query
          description: 'Number of notes per page. Maximum: 30.'
          required: false
          style: form
          explode: true
          schema:
            type: integer
            description: 'Number of notes per page. Maximum: 30.'
            example: 20
        - name: page
          in: query
          description: Number of the page to be retrieved.
          required: false
          style: form
          explode: true
          schema:
            type: integer
            description: Number of the page to be retrieved.
            example: 3
        - 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
        - name: Content-Type
          in: header
          description: Type of the content being sent.
          required: true
          style: simple
          schema:
            type: string
            example: application/json
        - $ref: '#/components/parameters/reason'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
              example: {}
      deprecated: false
  /notes/{noteId}:
    get:
      tags:
        - Note
      summary: VTex Retrieve Note
      description: Retrieves a given note in VTEX DO, filtering by `noteId`.
      operationId: GetNote
      parameters:
        - 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
        - name: Content-Type
          in: header
          description: Type of the content being sent.
          required: true
          style: simple
          schema:
            type: string
            example: application/json
        - name: noteId
          in: path
          description: Note's ID.
          required: true
          style: simple
          schema:
            type: string
            example: 654321cba
            description: Note's ID.
        - $ref: '#/components/parameters/reason'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
              example: {}
      deprecated: false
  /tasks:
    post:
      tags:
        - Task
      summary: VTex Create Task
      description: Creates a new task in VTEX DO.
      operationId: NewTask
      parameters:
        - name: Content-Type
          in: header
          description: Type of the content being sent.
          required: true
          style: simple
          schema:
            type: string
            example: application/json
        - 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
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTaskRequest'
            example:
              target:
                - id: 633730670642-01
                  type: order
                  url: https://recorrenciaqa.vtexcommercebeta.com.br/admin/checkout/orders/633730670642-01
              domain: oms
              context: Marketplace
              name: pricing
              priority: Critical
              surrogateKey: 505224-0
              description: Ajudar na doc API para lancar no postman
              dueDate: '2016-03-01'
              assignee:
                id:
                name:
                email: frederico.santos@vtex.com.br
              followers:
                - id:
                  name:
                  email: alan.dantas@vtex.com.br
              parentTaskId:
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
              example: {}
      deprecated: false
    get:
      tags:
        - Task
      summary: VTex List tasks
      description: "This endpoint allows you to filter tasks. You can choose between the following filtering options: \r\n\r\n- **Assignees:** using `assignee.email` and `status`. Example: `https://{{accountName}}.{{environment}}.com.br/api/do/tasks?assignee.email={{person@email.com}}&status={{open}}`. \r\n\r\n- **Targets:** using `targetId` and `status`. Example: `https://{{accountName}}.{{environment}}.com.br/api/do/tasks?target.id={{name}}&status={{open}}`. \r\n\r\n- **Paged tasks:** using `page`, `perPage` and `status`. Example: `https://{{accountName}}.{{environment}}.com.br/api/do/tasks?page={{1}}&perPage={{10}}&status=;{{-Closed}}`. \r\n\r\n- **Context:** using `context`, `page`, `perPage` and `status`. Example: `https://{{accountName}}.{{environment}}.com.br/api/do/tasks?context={{context}}&page={{1}}&perPage={{10}}&status={{-Closed}}`."
      operationId: Listtasksbyassignee
      parameters:
        - name: assignee.email
          in: query
          description: If you wish to list tasks by assignee, insert the desired assignee's email and status.
          required: false
          style: form
          explode: true
          schema:
            type: string
            example: '{{assigneeEmail}}'
        - name: target.id
          in: query
          description: If you wish to list tasks by target, insert the desired `targetId` and `status`.
          required: false
          style: form
          explode: true
          schema:
            type: string
            example: '{{targetId}}'
        - name: context
          in: query
          description: If you wish to list tasks by context, insert the desired context, `page`, `perPage` and `status`.
          required: false
          style: form
          explode: true
          schema:
            type: string
            example: '{{context}}'
        - name: page
          in: query
          description: If you wish to list tasks by context, also insert the desired `page`.
          required: false
          style: form
          explode: true
          schema:
            type: string
            example: '{{page}}'
        - name: perPage
          in: query
          description: If you wish to list tasks by context, also insert the desired `perPage` value.
          required: false
          style: form
          explode: true
          schema:
            type: string
            example: '{{desired number per page}}'
        - name: status
          in: query
          description: If you wish to list tasks by context, also insert the desired `status`.
          required: false
          style: form
          explode: true
          schema:
            type: string
            example: open
        - 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
        - name: Content-Type
          in: header
          description: Type of the content being sent.
          required: true
          style: simple
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
              example: {}
      deprecated: false
  /tasks/{taskId}:
    get:
      tags:
        - Task
      summary: VTex Retrieve Task
      description: Retrieves a given task, filtering by `taskId`.
      operationId: GetTask
      parameters:
        - 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
        - name: Content-Type
          in: header
          description: Type of the content being sent.
          required: true
          style: simple
          schema:
            type: string
            example: application/json
        - name: taskId
          in: path
          description: Task ID.
          required: true
          style: simple
          schema:
            type: string
            example: 123456abc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
              example: {}
      deprecated: false
    put:
      tags:
        - Task
      summary: VTex Update Task
      description: Updates a given task's status, for example, filtering by `taskId`.
      operationId: EditTask
      parameters:
        - 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
        - name: Content-Type
          in: header
          description: Type of the content being sent.
          required: true
          style: simple
          schema:
            type: string
            example: application/json
        - name: taskId
          in: path
          description: Task ID.
          required: true
          style: simple
          schema:
            type: string
            example: 123456abc
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditTaskRequest'
            example:
              status: InProgress
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
              example: {}
      deprecated: false
  /tasks/{taskId}/comments:
    post:
      tags:
        - Task
      summary: VTex Add Comment on a Task
      description: Adds a comment to a given task, filtering by `taskId`.
      operationId: AddComment
      parameters:
        - 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
        - name: Content-Type
          in: header
          description: Type of the content being sent.
          required: true
          style: simple
          schema:
            type: string
            example: application/json
        - name: taskId
          in: path
          description: Task ID.
          required: true
          style: simple
          schema:
            type: string
            example: 123456abc
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCommentRequest'
            example:
              text: write your comment here
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
              example: {}
      deprecated: false
components:
  schemas:
    NewNoteRequest:
      type: object
      required:
        - target
        - domain
        - description
      properties:
        target:
          type: object
          description: Target.
          properties:
            id:
              type: string
            type:
              type: string
            url:
              type: string
        domain:
          type: string
        description:
          type: string
    Target:
      title: Target
      required:
        - id
        - type
        - url
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        url:
          type: string
      example:
        id: v964735bdev-01
        type: order
        url: https://basedevmkp.vtexcommercebeta.com.br/admin/checkout/#/orders/v964741bdev-01
    NewTaskRequest:
      title: NewTaskRequest
      required:
        - target
        - domain
        - context
        - name
        - priority
        - surrogateKey
        - description
        - dueDate
        - assignee
        - followers
        - parentTaskId
      type: object
      properties:
        target:
          type: array
          items:
            $ref: '#/components/schemas/Target'
          description: ''
        domain:
          type: string
        context:
          type: string
        name:
          type: string
        priority:
          type: string
        surrogateKey:
          type: string
        description:
          type: string
        dueDate:
          type: string
        assignee:
          $ref: '#/components/schemas/Assignee'
        followers:
          type: array
          items:
            $ref: '#/components/schemas/Follower'
          description: ''
        parentTaskId:
          type: string
          nullable: true
      example:
        target:
          - id: 633730670642-01
            type: order
            url: https://recorrenciaqa.vtexcommercebeta.com.br/admin/checkout/orders/633730670642-01
        domain: oms
        context: Marketplace
        name: pricing
        priority: Critical
        surrogateKey: 505224-0
        description: Ajudar na doc API para lancar no postman
        dueDate: '2016-03-01'
        assignee:
          id:
          name:
          email: frederico.santos@vtex.com.br
        followers:
          - id:
            name:
            email: alan.dantas@vtex.com.br
        parentTaskId:
    Assignee:
      title: Assignee
      required:
        - id
        - name
        - email
      type: object
      properties:
        id:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        email:
          type: string
      example:
        id:
        name:
        email: frederico.santos@vtex.com.br
    Follower:
      title: Follower
      required:
        - id
        - name
        - email
      type: object
      properties:
        id:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        email:
          type: string
      example:
        id:
        name:
        email: alan.dantas@vtex.com.br
    AddCommentRequest:
      title: AddCommentRequest
      required:
        - text
      type: object
      properties:
        text:
          type: string
      example:
        text: escreva seu comentário
    EditTaskRequest:
      title: EditTaskRequest
      required:
        - status
      type: object
      properties:
        status:
          type: string
      example:
        status: InProgress
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
  parameters:
    reason:
      name: reason
      in: query
      description: This parameter is relevant only for PII-compliant accounts. When sending requests to this endpoint, PII-compliant accounts can use this parameter to declare the reason for requesting unmasked data. Otherwise, this endpoint will return masked PII data.
      required: false
      style: form
      schema:
        type: string
        example: data-validation
tags:
  - name: Note
  - name: Task
security:
  - appKey: []
    appToken: []