@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Master Data API - v2
@base https://apiexamples.vtexcommercestable.com.br
@version 1.0
@auth ApiKey X-VTEX-API-AppKey in header | ApiKey X-VTEX-API-AppToken in header | ApiKey VtexIdclientAutCookie in header
@common_fields {dataEntityName: str # Name of the data entity.}
@endpoints 20
@toc api(20)

@endpoint POST /api/dataentities/{dataEntityName}/documents
@desc Create new document
@required {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.}
@optional {_schema: str # Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with. This field is required when using `_where` or `_fields` query parameters.}
@returns(201) {Id: str, Href: str, DocumentId: str} # Created
@returns(202) {Id: str, Href: str, DocumentId: str} # Accepted  The document creation has been accepted and will be processed asynchronously due to background operations.
@example_request {"email":"clark.kent@examplemail.com","firstName":"Clark","lastName":"Kent","phone":"+12025550195","documentType":"CPF","document":"12345678900","isCorporate":false,"isNewsletterOptIn":false,"localeDefault":"en-US"}

@endpoint PATCH /api/dataentities/{dataEntityName}/documents
@desc Create partial document
@required {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.}
@optional {_schema: str # Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with. This field is required when using `_where` or `_fields` query parameters.}
@returns(200) {Id: str, Href: str, DocumentId: str} # OK
@example_request {"phone":"+12025550195","isNewsletterOptIn":false}

@endpoint GET /api/dataentities/{dataEntityName}/documents/{id}
@desc Get document
@required {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., id: str # ID of the Document.}
@optional {_fields: str # Fields that should be returned by document. Separate fields' names with commas. For example `_fields=email,firstName,document`. You can also use `_fields=_all` to fetch all fields., _schema: str # Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with. This field is required when using `_where` or `_fields` query parameters.}
@returns(200) {id: str, accountId: str, accountName: str, dataEntityId: str} # OK

@endpoint PUT /api/dataentities/{dataEntityName}/documents/{id}
@desc Create document with custom ID or update entire document
@required {Accept: str # HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand., id: str # ID of the document. If you inform an **unused ID**, this endpoint will create a new document with the informed custom ID, differently from the [Create new document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents) endpoint, which automatically generates the ID. If you inform an **existing ID**, this endpoint will update the entire document associated with the informed ID.}
@optional {_where: str # Defines a condition the document must comply with. When referring to fields, you can use a nested field up to the first level (e.g. `wishlistProduct.productName`)., _schema: str # Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with. This field is required when using `_where` or `_fields` query parameters.}
@returns(204) No Content
@errors {400: Bad Request  Invalid information in JSON., 403: Forbidden  Unauthorized access.}
@example_request {"email":"clark.kent@examplemail.com","firstName":"Clark","lastName":"Kent","phone":"+12025550195","documentType":"CPF","document":"12345678900","isCorporate":false,"isNewsletterOptIn":false,"localeDefault":"en-US"}

@endpoint PATCH /api/dataentities/{dataEntityName}/documents/{id}
@desc Update partial document
@required {Accept: str # HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand., id: str # ID of the Document.}
@optional {_where: str # Defines a condition the document must comply with. When referring to fields, you can use a nested field up to the first level (e.g. `wishlistProduct.productName`)., _schema: str # Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with. This field is required when using `_where` or `_fields` query parameters.}
@returns(204) No Content
@example_request {"phone":"+12025550195","isNewsletterOptIn":false}

@endpoint DELETE /api/dataentities/{dataEntityName}/documents/{id}
@desc Delete document
@required {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., id: str # ID of the Document.}
@returns(204) No Content

@endpoint GET /api/dataentities/{dataEntityName}/search
@desc Search documents
@required {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., REST-Range: str # Specifies the range of documents to be returned in the response. The value should follow the format `resources={x}-{y}`, where: * `x`: Index of the first document in the returned array. * `y`: Index of the last document in the returned array + 1.  This field controls pagination by defining the subset of documents to be retrieved. The maximum number of documents returned per query is limited to 100. For example, `resources=0-10` returns the first 10 documents.}
@optional {_fields: str # Fields that should be returned by document. Separate fields' names with commas. For example `_fields=email,firstName,document`. You can also use `_fields=_all` to fetch all fields., _where: str # Defines a condition the document must comply with. When referring to fields, you can use a nested field up to the first level (e.g. `wishlistProduct.productName`)., _schema: str # Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with. This field is required when using `_where` or `_fields` query parameters., _sort: str # Defines sorting mode in two parts. The first part is the name of the field you want to sort by. It can be a nested field up to the first level (e.g. `wishlistProduct.productName`). In the second part, use `ASC` for ascending order or `DESC` for descending order.}
@returns(200) OK
@errors {400: Bad Request, 403: Forbidden, 503: Service Unavailable  Wildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`.}

@endpoint GET /api/dataentities/{dataEntityName}/scroll
@desc Scroll documents
@required {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.}
@optional {_token: str # Value of the `X-VTEX-MD-TOKEN` token obtained in the response header of the first request, necessary on subsequent requests to continue scrolling through documents. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer., _size: int=100 # Inform the number of documents per request. Maximum value of `1000`., _fields: str # Fields that should be returned by document. Separate fields' names with commas. For example `_fields=email,firstName,document`. You can also use `_fields=_all` to fetch all fields., _where: str # Defines a condition the document must comply with. When referring to fields, you can use a nested field up to the first level (e.g. `wishlistProduct.productName`)., _schema: str # Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with. This field is required when using `_where` or `_fields` query parameters., _sort: str # Defines sorting mode in two parts. The first part is the name of the field you want to sort by. It can be a nested field up to the first level (e.g. `wishlistProduct.productName`). In the second part, use `ASC` for ascending order or `DESC` for descending order.}
@returns(200) OK
@errors {400: Bad Request, 429: Too Many Requests  Wildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`.}

@endpoint GET /api/dataentities/{dataEntityName}/schemas
@desc Get schemas
@required {Content-Type: str # Type of the content being sent.}
@returns(200) OK

@endpoint GET /api/dataentities/{dataEntityName}/schemas/{schemaName}
@desc Get schema by name
@required {Content-Type: str # Type of the content being sent., schemaName: str # Name of the schema.}
@returns(200) {properties: map{name: map{type: str}}, v-indexed: [str]} # OK

@endpoint PUT /api/dataentities/{dataEntityName}/schemas/{schemaName}
@desc Save schema by name
@required {schemaName: str # Name of the schema., properties: map{name: map} # Object containing schema properties.}
@optional {v-indexed: [str] # Names of properties to index for /search, /scroll, and _sort. Required for reliable filtering (e.g. _where=field=value) and sorting (_sort=field ASC). Indexing is asynchronous after schema save.}
@returns(200) {Message: str} # OK
@example_request {"properties":{"name":{"type":"string"}}}

@endpoint DELETE /api/dataentities/{dataEntityName}/schemas/{schemaName}
@desc Delete schema by name
@required {Content-Type: str # Type of the content being sent., schemaName: str # Name of the schema.}
@returns(204) No Content

@endpoint GET /api/dataentities/{dataEntityName}/indices
@desc Get indices
@required {Content-Type: str # Type of the content being sent.}
@returns(200) OK

@endpoint PUT /api/dataentities/{dataEntityName}/indices
@desc Create index
@required {name: str # Name to identify the index., multiple: bool # Determines whether the values need to be unique. If false, values must be unique., fields: str # Comma-separated fields of the index.}
@returns(200) OK
@example_request {"name":"indexName","multiple":false,"fields":"fieldName"}

@endpoint GET /api/dataentities/{dataEntityName}/indices/{index_name}
@desc Get index by name
@required {Content-Type: str # Type of the content being sent., index_name: str # Name of the index.}
@returns(200) {name: str, acronym: str, isGlobal: bool, multiple: bool, fields: str} # OK

@endpoint DELETE /api/dataentities/{dataEntityName}/indices/{index_name}
@desc Delete index by name
@required {Content-Type: str # Type of the content being sent., index_name: str # Name of the index.}
@returns(204) No Content

@endpoint POST /api/dataentities/{dataEntityName}/documents/{id}/clusters
@desc Validate document by clusters
@required {Accept: str # HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand., id: str # ID of the Document.}
@returns(200) OK
@example_request [{"name":"male","rule":"gender=male"},{"name":"complex","rule":"((gender=male AND percent=0.35) AND any is null) AND (name=*go*)"},{"name":"complex2","rule":"((gender=male AND percent=0.35) AND any is not null) OR (name=*go*)"},{"name":"createdIn","rule":"createdIn between 2015-10-28 AND 2015-10-30"}]

@endpoint GET /api/dataentities/{dataEntityName}/documents/{id}/versions
@desc List versions
@required {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., id: str # ID of the Document.}
@optional {load: bool=true # If true, return all the fields in each version of the document., fields: str=id,dataEntityId,isNewsletterOptIn,createdBy # If `load` is true, the response will return only these specific fields.}
@returns(200) OK

@endpoint GET /api/dataentities/{dataEntityName}/documents/{id}/versions/{versionId}
@desc Get version
@required {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., id: str # ID of the Document., versionId: str # ID of the version to update.}
@returns(200) {id: str, author: str, document: map{id: str, dataEntityId: str, accountId: str, accountName: str, followers: [str], schemas: [str], email: str}} # OK

@endpoint PUT /api/dataentities/{dataEntityName}/documents/{id}/versions/{versionId}
@desc Update version
@required {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., id: str # ID of the Document., versionId: str # ID of the version to update}
@returns(200) {Id: str, Href: str} # OK
@errors {304: Not Modified}

@end