@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api VTEX DO API
@base https://apiexamples.vtexcommercestable.com.br/api/do
@version 1.0
@auth ApiKey X-VTEX-API-AppKey in header | ApiKey X-VTEX-API-AppToken in header | ApiKey VtexIdclientAutCookie in header
@common_fields {Content-Type: str # Type of the content being sent., Accept: str # HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.}
@endpoints 8
@toc notes(3), tasks(5)

@group notes
@endpoint POST /notes
@desc Create note
@required {target: map{id: str, type: str, url: str} # Target., domain: str # Domain identification., description: str # Note description. Maximum number of characters: 2000.}
@optional {createdBy: map{id: str, name: str} # Object with information about the user that created the note.}
@returns(200) {id: str, domain: str, owner: str, target: map{id: str, type: str, url: str}, description: str, creationDate: str, lastUpdate: str, createdBy: map?{id: str, name: str, email: str, key: str?}} # OK

@endpoint GET /notes
@desc Get notes by order ID
@required {target.id: str # Order ID.}
@optional {perPage: int # Number of notes per page. Maximum: 30., page: int # Number of the page to be retrieved., reason: str # 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.}
@returns(200) OK

@endpoint GET /notes/{noteId}
@desc Retrieve note
@required {noteId: str # Note ID.}
@optional {reason: str # 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.}
@returns(200) OK

@endgroup

@group tasks
@endpoint POST /tasks
@desc Create task
@required {target: [map{id!: str, type!: str, url!: str}] # Target information for creating the task., domain: str # Task domain in the VTEX environment., context: str # Task context., name: str # Task name., priority: str # Task level of priority., surrogateKey: str # [Surrogate key](https://www.ibm.com/docs/en/ida/9.1?topic=keys-surrogate) unique identifier of the task., dueDate: str # Task deadline in `hh:mm:ss` format., assignee: map{id: str, name: str, email!: str} # Assignee to whom the task will be designated., followers: [map{id: str, name: str, email!: str}] # Task follower array.}
@optional {description: str # Additional task comment., parentTaskId: str # Parent task ID of another task related the task being created, when applicable.}
@returns(200) OK

@endpoint GET /tasks
@desc List tasks
@optional {assignee.email: str # If you wish to list tasks by assignee, insert the desired assignee's email and status., target.id: str # If you wish to list tasks by target, insert the desired `targetId` and `status`., context: str # If you wish to list tasks by context, insert the desired context, `page`, `perPage` and `status`., page: str # If you wish to list tasks by context, also insert the desired `page`., perPage: str # If you wish to list tasks by context, also insert the desired `perPage` value., status: str # If you wish to list tasks by context, also insert the desired `status`.}
@returns(200) {piiHidden: bool, items: [map], paging: map{page: int, perPage: int, total: int, pages: int}} # OK

@endpoint GET /tasks/{taskId}
@desc Retrieve task
@required {taskId: str # Task ID.}
@returns(200) OK

@endpoint PUT /tasks/{taskId}
@desc Update task
@required {taskId: str # Task ID., status: str(Open/Closed/Suspended/InProgress) # Task status update.}
@returns(200) OK

@endpoint POST /tasks/{taskId}/comments
@desc Add comment on a task
@required {taskId: str # Task ID., text: str # Text you wish to add to the task.}
@returns(200) OK

@endgroup

@end