{
    "openapi": "3.0.0",
    "info": {
        "title": "VTEX Do API",
        "description": "[VTEX DO](https://help.vtex.com/en/tutorial/vtex-do--7KMbRL4OslN8DTX9oiuCiu) is a task management system for authorized [users](https://help.vtex.com/en/tutorial/how-to-manage-users--tutorials_512) to process VTEX store orders. The functionality allows you to control notes, and create, update, list, and retrieve tasks. \r\n\r\n## VTEX DO API Index\r\n\r\n### Note\r\n\r\n- `POST` [Create Note](https:\/\/developers.vtex.com\/docs\/api-reference\/vtex-do-api#post-\/notes)\r\n- `GET` [Get Notes by orderId](https:\/\/developers.vtex.com\/docs\/api-reference\/vtex-do-api#get-\/notes)\r\n- `GET` [Retrieve Note](https:\/\/developers.vtex.com\/docs\/api-reference\/vtex-do-api#get-\/notes\/-noteId-)\r\n\r\n### Task\r\n\r\n- `POST` [Create Task](https:\/\/developers.vtex.com\/docs\/api-reference\/vtex-do-api#post-\/tasks)\r\n- `GET` [List tasks](https:\/\/developers.vtex.com\/docs\/api-reference\/vtex-do-api#get-\/tasks)\r\n- `GET` [Retrieve Task](https:\/\/developers.vtex.com\/docs\/api-reference\/vtex-do-api#get-\/tasks\/-taskId-)\r\n- `PUT` [Update Task](https:\/\/developers.vtex.com\/docs\/api-reference\/vtex-do-api#put-\/tasks\/-taskId-)\r\n- `POST` [Add Comment on a Task](https:\/\/developers.vtex.com\/docs\/api-reference\/vtex-do-api#post-\/tasks\/-taskId-\/comments) \r\n\r\n## Common parameters\r\n\r\n| **Parameter name** | **Description** | **Type** |\r\n| :---: | :--- | :--- |\r\n| `{{accountName}}` | Name of the VTEX account. Used as part of the URL. | Server variable. |\r\n| `{{environment}}` | Environment to use. Used as part of the URL. The default value is `vtexcommercestable`. | Server variable. |\r\n| `X-VTEX-API-AppKey` | Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys). | Authentication header. Must be used together with `X-VTEX-API-AppToken`. Not necessary when using `VtexIdclientAutCookie`. |\r\n| `X-VTEX-API-AppToken` | Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys). | Authentication header. Must be used together with X-VTEX-API-AppKey. Not necessary when using `VtexIdclientAutCookie`. |\r\n| `VtexIdclientAutCookie` | [User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours. | Authentication header. Not necessary when using `X-VTEX-API-AppKey` and `X-VTEX-API-AppToken`. |",
        "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": "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": [
                    {
                        "$ref": "#/components/parameters/Content-Type"
                    },
                    {
                        "$ref": "#/components/parameters/Accept"
                    }
                ],
                "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": "You can choose between using the complete target URL or only `/orders/{OrderID}`.",
                                                "example": "https://basedevmkp.environment.com/admin/checkout/#/orders/v964741bdev-01"
                                            }
                                        }
                                        },
                                    "domain": {
                                        "type": "string",
                                        "description": "Domain identification.",
                                        "example": "oms"
                                    },
                                    "description": {
                                        "type": "string",
                                        "description": "Note description. Maximum number of characters: 2000.",
                                        "example": "Order ID in the marketplace is 786-09."
                                    },
                                    "createdBy": {
                                        "type": "object",
                                        "description": "Object with information about the user that created the note.",
                                        "properties": {
                                            "id": {
                                                "type": "string",
                                                "description": "Identification code of the user that created the note.",
                                                "example": "fb542e51-5488-4c34-8d17-ed8fcf597a94"
                                            },
                                            "name": {
                                                "type": "string",
                                                "description": "Name of the user that created the note.",
                                                "example": "Mario Smith"                                            
                                            }                                                                           
                                        }                                    
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "string",
                                            "description": "Note ID."
                                        },
                                        "domain": {
                                            "type": "string",
                                            "description": "VTEX module `oms`."
                                        },
                                        "owner": {
                                            "type": "string",
                                            "description": "Owner ID."
                                        },
                                        "target": {
                                            "type": "object",
                                            "description": "Target object information.",    
                                            "properties": {
                                                "id": {
                                                    "type": "string",                                    
                                                    "description": "Order ID."
                                                },
                                                "type": {
                                                    "type": "string",                                    
                                                    "description": "Target type."
                                                },
                                                "url": {
                                                    "type": "string",                                    
                                                    "description": "Target URL."
                                                }
                                            }
                                        },
                                        "description": {
                                            "type": "string",
                                            "description": "Note description."
                                        },
                                        "creationDate": {
                                            "type": "string",
                                            "description": "Creation date in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`."
                                        },
                                        "lastUpdate": {
                                            "type": "string",
                                            "description": "Last update date in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`."
                                        },
                                        "createdBy": {
                                            "type": "object",                                    
                                            "description": "Identification of the user who created the note.",
                                            "properties": {
                                                "id": {
                                                    "type": "object",                                    
                                                    "description": "User ID."
                                                },
                                                "name": {
                                                    "type": "object",                                    
                                                    "description": "User name."
                                                },
                                                "email": {
                                                    "type": "object",                                    
                                                    "description": "User email."
                                                },
                                                "key": {
                                                    "type": "object",                                    
                                                    "description": "Authentication key used.",
                                                    "nullable": true
                                                }
                                            },
                                            "nullable": true
                                        }
                                    }
                                },
                                "example": {
                                    "id": "A08CDB2519AC4FA49EB6099CF72C3642",
                                    "domain": "oms",
                                    "owner": "c97ef6c8491a439f927cf9918644329f",
                                    "target": {
                                        "id": "v964735bdev-01",
                                        "type": "order",
                                        "url": "https://basedevmkp.environment.com.br/admin/checkout/#/orders/v964741bdev-01"
                                    },
                                    "description": "Order ID in the marketplace is 786-09.",
                                    "creationDate": "2024-03-11T15:49:17.8785392Z",
                                    "lastUpdate": "2024-05-11T15:49:17.8785392Z",
                                    "createdBy": {
                                        "id": "fb542e51-5488-4c34-8d17-ed8fcf597a94",
                                        "name": "Mario Smith",
                                        "email": "mario.smith@store.com",
                                        "key": "appkey-appvtex"
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "get": {
                "tags": [
                    "Note"
                ],
                "summary": "Get notes by orderId",
                "description": "Retrieves notes related to a specific `orderId`.",
                "operationId": "GetNotesbyorderId",
                "parameters": [
                    {
                        "name": "target.id",
                        "in": "query",
                        "description": "Order ID.",
                        "required": true,
                        "style": "form",
                        "explode": true,
                        "schema": {
                            "type": "string",
                            "example": "1172452900788-01"
                        }
                    },
                    {
                        "name": "perPage",
                        "in": "query",
                        "description": "Number of notes per page. Maximum: 30.",
                        "required": false,
                        "style": "form",
                        "explode": true,
                        "schema": {
                            "type": "integer",
                            "example": 20
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "description": "Number of the page to be retrieved.",
                        "required": false,
                        "style": "form",
                        "explode": true,
                        "schema": {
                            "type": "integer",
                            "example": 3
                        }
                    },
                    {
                        "name": "reason",
                        "in": "query",
                        "description": "This parameter is relevant only for accounts using [Data Protection Plus](https://developers.vtex.com/docs/guides/data-protection-plus). When sending requests to this endpoint, accounts with the [PII data architecture](https://developers.vtex.com/docs/guides/pii-data-architecture-specifications) 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"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Content-Type"
                    },
                    {
                        "$ref": "#/components/parameters/Accept"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {},
                                "example": {}
                            }
                        }
                    }
                }
            }
        },
        "/notes/{noteId}": {
            "get": {
                "tags": [
                    "Note"
                ],
                "summary": "Retrieve note",
                "description": "Retrieves a given note in VTEX DO, filtering by `noteId`.",
                "operationId": "GetNote",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Content-Type"
                    },
                    {
                        "$ref": "#/components/parameters/Accept"
                    },
                    {
                        "name": "noteId",
                        "in": "path",
                        "description": "Note ID.",
                        "required": true,
                        "style": "simple",
                        "schema": {
                            "type": "string",
                            "example": "654321cba"
                        }
                    },
                    {
                        "name": "reason",
                        "in": "query",
                        "description": "This parameter is relevant only for accounts using [Data Protection Plus](https://developers.vtex.com/docs/guides/data-protection-plus). When sending requests to this endpoint, accounts with the [PII data architecture](https://developers.vtex.com/docs/guides/pii-data-architecture-specifications) 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"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {},
                                "example": {}
                            }
                        }
                    }
                }
            }
        },
        "/tasks": {
            "post": {
                "tags": [
                    "Task"
                ],
                "summary": "Create task",
                "description": "Creates a new task in VTEX DO.",
                "operationId": "NewTask",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Content-Type"
                    },
                    {
                        "$ref": "#/components/parameters/Accept"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "target",
                                    "domain",
                                    "context",
                                    "name",
                                    "priority",
                                    "surrogateKey",
                                    "dueDate",
                                    "assignee",
                                    "followers"
                                ],
                                "type": "object",
                                "properties": {
                                    "target": {
                                        "type": "array",
                                        "description": "Target information for creating the task.",
                                        "items": {                            
                                            "type": "object",
                                            "description": "Target details.",
                                            "required": [
                                                "id", 
                                                "type", 
                                                "url"
                                            ],                                
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "description": "Order ID.",
                                                    "example": "v964735bdev-01"
                                                },
                                                "type": {
                                                    "type": "string",
                                                    "description": "Task type.",
                                                    "example": "order"
                                                },
                                                "url": {
                                                    "type": "string",
                                                    "description": "Order ID link in VTEX Admin.",
                                                    "example": "https://basedevmkp.environment.com.br/admin/checkout/#/orders/v964741bdev-01"
                                                }
                                            }                            
                                        }
                                    },
                                    "domain": {
                                        "type": "string",
                                        "description": "",
                                        "example": "oms"
                                    },
                                    "context": {
                                        "type": "string",
                                        "description": "",
                                        "example": "Marketplace"
                                    },
                                    "name": {
                                        "type": "string",
                                        "description": "",
                                        "example": "pricing"
                                    },
                                    "priority": {
                                        "type": "string",
                                        "description": "",
                                        "example": "Critical"
                                    },
                                    "surrogateKey": {
                                        "type": "string",
                                        "description": "",
                                        "example": "505224-0",
                                        "nullable": true
                                    },
                                    "description": {
                                        "type": "string",
                                        "description": "Additional task comment.",
                                        "example": ""
                                    },
                                    "dueDate": {
                                        "type": "string",
                                        "description": "",
                                        "example": ""
                                    },
                                    "assignee": {
                                        "$ref": "#/components/schemas/Assignee"
                                    },
                                    "followers": {
                                        "type": "array",
                                        "items": {
                                            "$ref": "#/components/schemas/Follower"
                                        },
                                        "description": ""
                                    },
                                    "parentTaskId": {
                                        "type": "string",
                                        "description": "",
                                        "example": "",
                                        "nullable": true
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {},
                                "example": {}
                            }
                        }
                    }
                }
            },
            "get": {
                "tags": ["Task"],
                "summary": "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": "assigneeName@email.com"
                        }
                    },
                    {
                        "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": "page"
                        }
                    },
                    {
                        "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"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Content-Type"
                    },
                    {
                        "$ref": "#/components/parameters/Accept"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {},
                                "example": {}
                            }
                        }
                    }
                }
            }
        },
        "/tasks/{taskId}": {
            "get": {
                "tags": ["Task"],
                "summary": "Retrieve task",
                "description": "Retrieves a given task, filtering by `taskId`.",
                "operationId": "GetTask",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Content-Type"
                    },
                    {
                        "$ref": "#/components/parameters/Accept"
                    },
                    {
                        "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": {}
                            }
                        }
                    }
                }
            },
            "put": {
                "tags": ["Task"],
                "summary": "Update task",
                "description": "Updates a given task's status, for example, filtering by `taskId`.",
                "operationId": "EditTask",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Content-Type"
                    },
                    {
                        "$ref": "#/components/parameters/Accept"
                    },
                    {
                        "name": "taskId",
                        "in": "path",
                        "description": "Task ID.",
                        "required": true,
                        "style": "simple",
                        "schema": {
                            "type": "string",
                            "example": "123456abc"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EditTaskRequest"
                            },
                            "example": {
                                "status": "InProgress"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {},
                                "example": {}
                            }
                        }
                    }
                }
            }
        },
        "/tasks/{taskId}/comments": {
            "post": {
                "tags": ["Task"],
                "summary": "Add comment on a task",
                "description": "Adds a comment to a given task, filtering by `taskId`.",
                "operationId": "AddComment",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Content-Type"
                    },
                    {
                        "$ref": "#/components/parameters/Accept"
                    },
                    {
                        "name": "taskId",
                        "in": "path",
                        "description": "Task ID.",
                        "required": true,
                        "style": "simple",
                        "schema": {
                            "type": "string",
                            "example": "123456abc"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {                                
                                "type": "object",
                                "required": [
                                    "text"
                                ],
                                "properties": {
                                    "text": {
                                        "type": "string",
                                        "description": "Text you wish to add to the task."
                                    }
                                },
                                "example": {
                                    "text": "write your comment here"
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {},
                                "example": {}
                            }
                        }
                    }
                }
            }
        }
    },
    "security": [
        {
            "appKey": [],
            "appToken": []
        },
        {
            "VtexIdclientAutCookie": []
        }
    ],
    "components": {
        "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."
            }
        },
        "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"
                    }
                }
            },
            "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": null,
                    "name": null,
                    "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": null,
                    "name": null,
                    "email": "alan.dantas@vtex.com.br"
                }
            },
            "EditTaskRequest": {
                "title": "EditTaskRequest",
                "required": ["status"],
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string"
                    }
                },
                "example": {
                    "status": "InProgress"
                }
            }
        },
        "parameters": {
            "Content-Type": {
                "name": "Content-Type",
                "in": "header",
                "description": "Type of the content being sent.",
                "required": true,
                "style": "simple",
                "schema": {
                    "type": "string",
                    "example": "application/json"
                }
            },
            "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"
                }
            }
        }
    },
    "tags": [
        {
            "name": "Note"
        },
        {
            "name": "Task"
        }
    ]
}